Try Turborg Free → Open App →
← All posts

Don't Let Your Agent Hallucinate Your Toolchain: Pin It with an xshellz.box Manifest

August 24, 2026 · 4 min read · The xShellz Team

TL;DR

  • Pin exact tool versions with an xshellz.box manifest file, one line per package, using apt:, pip:, or npm: prefixes.
  • The manifest is reinstalled on every boot of your Agent Shell, so the environment is deterministic every time.
  • Your AI coding agent runs inside an always-on Ubuntu 24.04 box, with no idle timeout and no trial countdown, even on the free tier.

You write an xshellz.box manifest file that pins exact versions of Node, Python, and any other tool your agent needs. On every boot, the xshellz.box rebuilds the environment from that file, so your AI coding agent always gets the same versions. We run this on our own fleet of Agent Shell boxes, so every agent session starts with the exact toolchain we defined.

how do i make sure my ai coding agent has the right version of node and python installed every time?

Create a file named xshellz.box in your home directory on an Agent Shell. Each line specifies a package. Use apt: for system packages, pip: for Python, and npm: for Node. For example, to get Node 22 and Python 3 with the requests library and TypeScript:

apt:nodejs
apt:python3
pip:requests
npm:typescript

You can pin exact versions: apt:nodejs=version, pip:requests==2.31.0, npm:[email protected]. The box reads this file on every boot, so your agent always sees the same toolchain. No more guessing.

why does my ai agent keep failing to run my code?

Most AI agents run on your laptop or a random VPS where tool versions are whatever was last installed. The agent writes code that works in its hypothetical environment, but fails on yours because Node is 18 instead of 22, or a Python package is missing. An Agent Shell with a manifest eliminates that mismatch. The root filesystem is rebuilt from scratch on every boot, and only /root persists. So the manifest is the single source of truth, and the agent operates in a known, reproducible environment every time. No more "it works on my machine" surprises.

how do i create an xshellz.box manifest to pin my dev environment?

Place a file called xshellz.box in your home directory on the Agent Shell. Write one package per line. Three prefixes are supported:

  • apt: for system packages from the Ubuntu 24.04 LTS repositories.
  • pip: for Python packages from PyPI.
  • npm: for Node packages from the npm registry.

A bare package name without a prefix also defaults to apt. To pin versions, append =version for apt, ==version for pip, and @version for npm. Here is a manifest for a project that needs Node 22, Python 3, and specific versions of requests and typescript:

apt:nodejs=22.11.0-1nodesource1
apt:python3
pip:requests==2.31.0
npm:[email protected]

The box will install these packages on the next boot. You can also force a reboot by restarting the box from the xShellz dashboard, or wait for the next scheduled image update. The manifest is reinstalled every time, so changes are consistently applied.

can i automate the setup of my agent's linux box?

The manifest is the automation. Once you have the file in place, every boot of the Agent Shell applies it. You can pair it with any of the 6 preinstalled coding agents, like borg or Claude Code, to run tasks that depend on specific toolchains. For example, you could tell borg: "use the manifest to ensure the environment, then run the test suite." The agent runs inside a box that never sleeps, even on the free tier, so long-running tasks continue without your laptop online. This makes the environment not just reproducible but also always available for your agent.

what happens if I change my manifest after the agent starts working?

The manifest is read only at boot time. If you edit xshellz.box while the box is running, the changes do not take effect until the next reboot. This protects the agent from seeing a half-updated environment. You can safely iterate on the manifest, test changes in a separate ephemeral sandbox, and only reboot your main box when you are ready. The persistent /root directory holds the manifest, so it survives the rebuild. Once you reboot, the new environment is applied cleanly, and your agent picks up the exact toolchain you defined.

Frequently asked questions

Can the manifest install tools beyond apt, pip, and npm?

The manifest file supports apt, pip, and npm. For other tools, you can place a script in /root and run it manually, or use a preinstalled agent like borg to fetch and install them. The Agent Shell also includes build-essential, so you can compile from source if needed. The manifest covers the most common toolchains.

Does the manifest work on the free tier?

Yes. Every Agent Shell tier, including the free tier, reads and applies the manifest on every boot. The free tier gives you an always-on box with no idle timeout and no trial countdown, so your manifest-defined environment is always ready for your agent.

Can I use a manifest to set up a temporary sandbox?

Absolutely. The xShellz SDK lets you spin up ephemeral Agent Shell boxes for one-off jobs. You can include a manifest in the sandbox, test a new toolchain, then discard the box. This is great for experimenting with version pins without touching your main box. Stopped sandboxes are kept for 30 days before cleanup.