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 -g and 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 with requests or openai and 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 as image:latest is 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:

  1. 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.
  2. 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:

  1. Check what is behind. npm outdated and pip list --outdated show what has moved.
  2. Upgrade on a branch. Update the lockfile or requirements.txt on a Git branch, not on main.
  3. Run one real job by hand. Run the agent’s actual daily task, not just a test, and compare its output to yesterday’s.
  4. Merge and note it. Merge the branch, and write the old and new versions in the commit message.
  5. 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

  1. Commit a lockfile for every Node project, and use npm ci for every automated install.
  2. Pin Python helpers with == on every line and run them from their own virtual environment.
  3. Pin the agent runtime and container images to tested versions, and turn off self-update timers.
  4. Move skill installs to setup time, and pin any npx tool.
  5. Upgrade on a schedule, on a branch, with one real run before merging.
  6. 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