Stop Rebuilding Your Dev Environment: Pin Your Entire Stack with an xshellz.box Manifest

Imagine you get a fresh Linux box, you scribble down a list of tools you always need, and the next time it boots, everything is installed. That's exactly what an xshellz.box manifest does. It's a single file in your home directory that defines every CLI tool, language, and agent you want. Every time the box starts (or reboots), it reads that file and brings your environment back to the exact state you pinned. No more apt-get install marathons every time you spin up a sandbox.

How the manifest works

Every xshellz.box comes with a hardened, always-on Ubuntu 24.04 environment. Preinstalled are git, Node 22, Python 3, ripgrep, tmux, build-essential, and the AI coding agents borg, claude, codex, and gemini. The root filesystem is ephemeral: it gets wiped on every reboot. Only /home survives. That's where your manifest lives.

Create a file named xshellz.box in your home directory. Each line declares a package you want. The box will install it automatically at boot so your shell is ready the moment you SSH in. Use the prefix apt:, pip:, or npm: to target the right package manager. A bare name (no prefix) is treated as an apt package.

Here's a real manifest that gives you a coding environment with a few extra niceties:

vim
htop
apt: tree
pip: flask
pip: mypy
npm: typescript

Drop that file into ~/xshellz.box on your box, reboot, and you'll have everything waiting. Add more lines as your stack evolves. The box is always-on, so you can just leave it running and know your setup is preserved.

Pinning AI agents and custom toolchains

Because borg and the other agents are already baked in, you don't need to list them. But if you're using a Python package that an agent relies on, or a CLI tool you want to invoke from a coding agent, put it in the manifest. For example, if you use borg with a project that needs uvicorn, add pip: uvicorn and every fresh box will have it.

This is also handy for throwing away sandboxes. Spin up an ephemeral box via the SDK, drop your manifest in /home/user/xshellz.box before the first boot, and you'll get a clean, reproducible environment every time. No more "works on my machine" because your machine is defined in a file.

When it helps (and when it doesn't)

This manifest is perfect for pinning your CLI tools, language runtimes, and shell utilities. It's not a replacement for a full Docker image or a complex Nix flake, but it covers the 90% case where you just need a predictable terminal with your favorite tools. For anything deeper, you can still layer Docker on top. The manifest gets you from zero to a working shell in seconds, and that's the point.