It Worked Yesterday: Pin Your Agent's Dependencies Before a Routine Install Breaks It
You did not touch anything. The agent ran fine at 8 a.m. yesterday. This morning the job failed with an error you have never seen, something like TypeError: x is not a function deep inside a package you did not know you had.
What changed was a dependency. Somewhere in the chain, a package you depend on, or a package it depends on, shipped a new version overnight. Your box pulled it the next time something ran npm install, pip install -r requirements.txt, or a skill’s own setup script. Nothing in your code moved. The ground under it did.
This is one of the most common ways a self-hosted agent breaks, and it is one of the easiest to prevent. The fix is to make every install on the box produce exactly the same set of packages until you decide otherwise.
Where the floating versions hide
On a typical home agent box, versions float in more places than people expect:
- The agent runtime itself. If you installed OpenClaw or another runtime with a global
npm install -gand an update script that runs on a timer, you may be on a different version every week. - Version ranges in
package.json. A line like"undici": "^6.0.0"means “any 6.x”. A fresh install months later can pull a very different 6.x than the one you tested. - Unpinned
requirements.txt. A Python helper script withrequestsoropenaiand no version number takes whatever is newest at install time. - Skills and plugins. Many agent skills ship their own install step. If that step runs on each start, every restart is a chance to pick up a new version.
- Docker images on
latest. A container you pull asimage:latestis a different image every time the maintainer pushes. - Your CI runner. If your build also runs in GitHub Actions or another CI system, it does a fresh install every time. With no lockfile, CI and the Pi can quietly run different code.
None of this is wrong on its own. Ranges exist so you get bug fixes. The problem is that on an unattended box, “you get bug fixes” turns into “you get changes nobody reviewed, at a time nobody is watching.”
The rule: installs are reproducible, upgrades are deliberate
Split the two jobs that usually get mixed together:
- Installing should always give you the exact same packages. It runs on a fresh box, in CI, after a restore, and after a crash. It should never surprise you.
- Upgrading is a separate task you do on purpose, on a day you are watching, with a way back.
Everything below is about enforcing that split.
Step 1: Commit a lockfile for every Node project
For any Node project on the box, including the agent’s own scripts folder and any site build, make sure a lockfile exists and is in Git:
cd /srv/agent/scripts
npm install # creates or updates package-lock.json
git add package.json package-lock.json
git commit -m "Pin dependencies"
Then change every automated install to npm ci instead of npm install:
npm ci
The difference matters. npm install can rewrite the lockfile to newer versions that still fit your ranges. npm ci installs exactly what the lockfile says, deletes node_modules first so leftovers cannot hide, and fails loudly if package.json and the lockfile disagree. That loud failure is what you want at 3 a.m.
If you use pnpm or Yarn, the equivalents are pnpm install --frozen-lockfile and yarn install --immutable.
Step 2: Pin Python helpers with exact versions
Python scripts are where most home boxes are loosest. Replace a hand-written requirements.txt with a pinned one.
The simplest way, with nothing new to install, is to freeze a known-good virtual environment:
cd /srv/agent/helpers
python3 -m venv .venv
. .venv/bin/activate
pip install requests feedparser # whatever the scripts need
pip freeze > requirements.txt
git add requirements.txt
git commit -m "Pin Python helper dependencies"
Now requirements.txt has lines like requests==2.32.3 instead of requests. Every install from that file gives you the same versions, including the sub-dependencies pip freeze captured.
If you want something tidier, pip-tools lets you keep a short requirements.in with the packages you actually chose and compile it into a fully pinned requirements.txt. Either way, the file your jobs install from has == on every line.
Always run helpers from that virtual environment, not the system Python. Your cron line or systemd unit should call /srv/agent/helpers/.venv/bin/python, not python3. Otherwise an OS update can swap the interpreter out from under you.
Step 3: Pin the runtime and the images
The agent runtime is a dependency too. Install a specific version instead of “latest”:
npm install -g openclaw@<the version you tested>
Write that version down in the same repo as your config, in a plain VERSIONS.md or a comment in your setup script. When something breaks, the first question is “what version were we on when it worked,” and you want that answer in Git, not in your memory.
For containers, replace :latest with a specific tag, or better, a digest:
image: ghcr.io/example/agent-tool@sha256:3f1c...
A digest can never point at different contents. A tag usually will not change, but nothing stops a maintainer from moving it.
Also turn off any self-update timer the runtime installed. Updates to the runtime belong in Step 5, not in a background job. The OpenClaw release stability checklist covers how to vet a new runtime release before it reaches your box.
Step 4: Stop skills from installing on every start
Look at how each skill or plugin gets its dependencies. If a skill runs npm install or pip install each time the agent starts, move that step to setup time and give the skill its own lockfile or pinned requirements.
A quick way to find the offenders is to search the agent’s folder for install commands that run outside of setup:
grep -rn --include='*.sh' --include='*.js' --include='*.py' \
-E 'npm install|pip install|npx -y' /srv/agent
npx -y some-tool deserves special attention. It downloads and runs the newest version of a package every time unless you pin it, as in npx -y some-tool@1.4.2. For a tool your agent runs every hour, that is an unreviewed update every hour.
Step 5: Upgrade on purpose, with a way back
Pinning does not mean never upgrading. Security fixes matter, and the unattended security updates post covers the OS side. For your agent’s own packages, pick a regular, boring slot, like one weekday morning a month, and do it like this:
- Check what is behind.
npm outdatedandpip list --outdatedshow what has moved. - Upgrade on a branch. Update the lockfile or
requirements.txton a Git branch, not on main. - Run one real job by hand. Run the agent’s actual daily task, not just a test, and compare its output to yesterday’s.
- Merge and note it. Merge the branch, and write the old and new versions in the commit message.
- Watch the next scheduled run. Do not upgrade the night before you travel.
If a security advisory forces an upgrade in between, the same steps apply, just sooner.
The way back is the payoff of all this. Because the old lockfile is in Git, rolling back is one revert and one clean install:
git revert <upgrade commit>
npm ci
Compare that with the unpinned box, where “roll back” means guessing which of 400 packages changed and hoping an older version is still downloadable. The rollback plan post covers how to make that kind of undo part of every change, not just dependency upgrades.
Step 6: Make CI and the box agree
If the same project builds in CI and on the Pi, both should install from the same lockfile with the same command. In GitHub Actions, that means npm ci in the workflow, with the Node version pinned too:
- uses: actions/setup-node@v4
with:
node-version: "20.18.0"
cache: npm
- run: npm ci
Pin the Node version on the box to the same number with nvm or a fixed package. When CI and the box disagree on Node or package versions, you get the worst kind of failure: green in CI, broken in production, or the reverse, and no obvious reason why.
A five-minute check you can run today
Before changing anything, find out how exposed you are. On the agent box:
# Node projects without a committed lockfile
find /srv/agent -name package.json -not -path '*/node_modules/*' \
-execdir sh -c 'test -f package-lock.json || pwd' \;
# Python requirements with unpinned lines
grep -rLE '==' --include='requirements*.txt' /srv/agent
# Containers on :latest
grep -rn ':latest' /srv/agent --include='*.yml' --include='*.yaml'
Every line those commands print is a place where tomorrow’s install can differ from today’s. Fix the ones your scheduled jobs touch first.
The short version
- Commit a lockfile for every Node project, and use
npm cifor every automated install. - Pin Python helpers with
==on every line and run them from their own virtual environment. - Pin the agent runtime and container images to tested versions, and turn off self-update timers.
- Move skill installs to setup time, and pin any
npxtool. - Upgrade on a schedule, on a branch, with one real run before merging.
- Make CI and the box use the same lockfile, the same install command, and the same Node version.
Pinning will not make your agent smarter. It means that when a job fails, the cause is something you changed, and you can find it in your Git history instead of in someone else’s release notes.
Let your agent do the inventory
You can hand the five-minute check to your agent. Start with MarketMai’s free AI prompt pack and adapt one into a “list every dependency install on this box, mark which ones are unpinned, and propose the pinned version” task, then review its list before you commit anything. For production configs and runbooks covering setup, hardening, monitoring, and cron, the OpenClaw Agent Ops Toolkit has the full set, and the MarketMai Ultimate Bundle puts 13 prompt, automation, and agent-operations products in one $49 download.
More from the build log
Suggested
Want the full MarketMai stack?
Get the core MarketMai guides and operator playbooks in one premium bundle for $49.
View Bundle