Run an agent in a sandbox
A cheap Linux box, a Pi 5, or an Apple Silicon Mac can run several of your own agents without giving each one your host. Give each agent a separate bhatti user/key, choose a rootfs tier for its job, and let its sandbox reach only the services it needs. Start with the Quickstart on the host.
Give the agent its own key
Section titled “Give the agent its own key”On the server, create an owner with caps rather than handing your agent the installer-created admin key:
sudo bhatti user create --name coding-agent \ --max-sandboxes 5 --max-cpus 4 --max-memory 4096# Save the bht_... key printed once and supply it to the agent securely.The agent can run the local CLI using its key via BHATTI_TOKEN (which overrides the admin token in the host’s CLI config). Don’t put the key into a repository or publish it in a URL. If the agent’s CLI runs off-host, first set up a TLS API domain; alternatively SSH into the server to use its Unix socket. See Users & Auth and Self-hosting → Remote access.
Choose a VM and a narrow network policy
Section titled “Choose a VM and a narrow network policy”minimal is good for CLI-first jobs; choose browser for Playwright or docker for builds. A sandbox normally has no network device. This one can reach its model API and git host without general internet access:
# Commands below run as coding-agent (with its BHATTI_TOKEN set).bhatti create --name coder --image minimal --keep-hot \ --allow-host api.openai.com --allow-host github.com--keep-hot prevents idle pause for an agent maintaining long-lived connections. For short jobs, omit it so the VM can cool; a cold VM keeps disk but not processes or /tmp. If your git workflow needs additional hosts, add their exact hostnames intentionally. --net is the public-egress alternative, not a prerequisite for the host CLI to talk to the VM. Sibling sandboxes stay isolated unless created with --allow-siblings. See Networking for the policy details and Tiers for workload choices.
Grant the model key, don’t inject its value
Section titled “Grant the model key, don’t inject its value”Store the model key under the agent owner’s account, then bind a grant to this sandbox and this HTTPS host:
bhatti secret set OPENAI_API_KEY "$MODEL_KEY"bhatti secret grant OPENAI_API_KEY --sandbox coder --host api.openai.comsecret grant prints a placeholder. Have the agent use that placeholder in its outbound HTTPS Authorization header, for example by exporting OPENAI_API_KEY=<printed-placeholder> in the guest before starting its client. The network gateway substitutes the real key only on approved HTTPS requests to api.openai.com; the guest never receives the plaintext from this grant. A plain create --secret OPENAI_API_KEY instead injects the real value into the guest environment. New sandboxes can combine creation and grant with --secret-grant OPENAI_API_KEY@api.openai.com when the secret already exists; that creates the placeholder environment variable at boot. Avoid typing a real secret literal into shell history; secret set takes the value as a positional argument, so also consider local process visibility. See Credentials for exact header and revocation behavior.
Branch before a risky step
Section titled “Branch before a risky step”Once the agent has a useful working state, fork it before trying an untrusted install or code change:
bhatti create --name coder-experiment --from coderThe fork carries the source’s network policy — you cannot override it during the fork. It gets its own disk and memory state, so you can keep the original while testing. Active grants are inherited as independent copies: their existing placeholders still work in the fork, with the same hosts and expiry. Before untrusted work, inspect bhatti secret grants and revoke any unwanted inherited grant by its fork-specific ID. Revoking the source’s grant does not revoke the fork’s copy; a new secret grant adds access rather than replacing inherited access. For a named checkpoint, use bhatti snapshot create coder --name before-change; a default snapshot includes memory and disk, while --type filesystem is disk-only. See Fork and branch and Durability.
Finish
Section titled “Finish”bhatti destroy coder-experimentbhatti destroy coderDestroy releases the VM and its overlay; preserve anything you need in a snapshot or volume first. Rotate the agent’s API key if it leaks, and revoke grants you no longer need. Move between hosts covers portable snapshot archives if you’re shifting a job to another compatible box.