Does the manifest affect preinstalled agents like borg or Claude Code?

The 6 preinstalled agent CLIs are version-locked to the box image and update only when the box is rebuilt on a newer image. If you need a specific build of borg or another agent beyond what ships, you can pin your own version via the manifest with `apt:`, `npm:`, or `pip:`.

Can I change the manifest after the box is running?

Yes. Edit `/root/xshellz.box` at any time. The changes take effect on the next reboot, when the box reinstalls everything from that file. You can also trigger a manual reinstall by restarting the box from the control panel.

Do I need a manifest if I only use one-click apps?

One-click apps are convenient, but they don't pin underlying runtimes like Python or Node. Without a manifest, a box rebuild may bring a newer Python release that breaks your app. A manifest locks every piece so the app behaves the same after every boot.

The 'One-Click' Trap: Why You Should Use a Manifest to Pin Your Agent's Environment / xShellz

TL;DR

An xshellz.box manifest file pins exact package versions so your AI agent's environment stays identical on every box rebuild.

Pinning specific Python 3.12 and Node 22 versions via apt prevents silent breakage when a box image is updated.

Without a manifest, one-click apps may drift with each reboot; a manifest makes your setup reproducible.

Use an xshellz.box manifest file to declare every package and pin exact versions. We run our own agent builds this way on our fleet, and every box ends up identical. A single file in your home directory automates the environment your AI coding agent needs, whether it is borg, Claude Code, or any of the 6 preinstalled agent CLIs. No more “it worked yesterday” surprises after a rebuild.

How do I make sure my AI agent's dev environment stays exactly the same every time I spin up a new box?

Place a manifest at /root/xshellz.box on your Agent Shell box. Each line names a package with an optional prefix (apt:, pip:, npm:) and a version constraint. On every boot, the system reinstalls exactly the versions you listed, overwriting any ephemeral drift. The rest of the filesystem resets, but /root persists across rebuilds, so your manifest survives and re-applies each time. A typical minimal example:

apt:python3=3.12.3
apt:nodejs=22.11.0
pip:requests==2.31.0
npm:[email protected]
ripgrep

That single file means every fresh box lands with a pinned Python, a pinned Node runtime, and the exact npm and pip packages you need, every time.

what is an xshellz.box manifest?

An xshellz.box manifest is a plain text file you create in /root/xshellz.box on your Agent Shell box. Each line declares one package. A bare name like ripgrep installs the latest available apt version; prefixing with apt:, pip:, or npm: gives you full control over the provider and allows version pinning. On every boot the box reads that manifest and installs everything fresh. Because the box itself is a hardened sandbox built on Ubuntu 24.04 LTS, the manifest ensures that even after the operating system image is rebuilt, your toolchain does not change underneath your agent.

how do I pin specific python and node versions for my agent?

Use apt: lines with version qualifiers. The box ships with Node 22 and Python 3, but those distributions can shift when a box image is refreshed. To lock them down:

apt:python3=3.12.3
apt:nodejs=22.11.0

These run during the early boot phase, so your agent starts with those exact versions. For pip dependencies, add pip:requests==2.31.0 or pip:crewai>=0.30. Node global tools follow the same pattern: npm:[email protected]. The manifest reinstalls on every boot from the persistent /root, guaranteeing that the Python and Node runtimes your AI coding agent relies on never sneakily upgrade.

can I automate my entire toolchain setup with a manifest file?

Yes. A single manifest can carry every system library, language runtime, and global package your agent needs. Below is a full manifest that recreates a rich agent environment identical on every boot:

apt:build-essential
apt:python3=3.12.3
apt:nodejs=22.11.0
pip:langgraph
pip:requests==2.31.0
npm:[email protected]
ripgrep
tmux
znc

When a box boots, the manifest runs first, so even a freshly provisioned AI sandbox is ready for borg, Claude Code, or any of the other 5 preinstalled agent CLIs without manual setup. No SSH loops or custom init scripts: just the file.

what happens if I don't use a manifest for my AI agent's environment?

Without a manifest, your agent's environment is whatever the current box image provides, and that can change. The box ships 23 one-click apps and 6 coding agent CLIs with a known set of tools, but things like Python 3 or Node 22 might move to a later minor release when the underlying Ubuntu 24.04 LTS image is updated. After a rebuild, your agent could suddenly see a different numpy build or a newer npm version that breaks your scripts. If you skip the manifest, you would have to SSH in after every rebuild, remember which packages you needed, and install them by hand. A manifest replaces that manual routine with a single reproducible file.