Skip to main content
At the end of this page, a coding agent works on your repo in a Linux machine of its own. It can install anything, run Docker, and break things without touching your laptop, and its work stays on the machine’s disk between sessions. The agent-browser template (the default) comes with Claude Code, Codex, and OpenCode installed. Org Secrets keep the model provider’s key out of the machine.
1

Save your provider key as a Secret

The command reads the value from a hidden prompt and confirms that the Secret is saved in your workspace. The machine only ever sees a placeholder. The outbound proxy puts the real key into requests to api.anthropic.com. --ai also takes openai, gemini, and openrouter.
2

Create the machine

The command waits until the machine runs, then prints its row as instabox ls shows it.
3

Push your repo

my-repo stands for your own repo’s folder.
push with no destination puts the folder in the machine’s home, /data/home/my-repo, and reports how many files it pushed.To clone private repos from inside the machine instead, save a GitHub token as a Secret for github.com and api.github.com. Then run gh auth setup-git in the machine.
4

Run the agent

To work with the agent interactively, connect over SSH and start Claude Code in your repo:
In instabox ssh, Ctrl+V with a PNG on your clipboard uploads the image and pastes its path. Claude Code can attach screenshots this way.To run the agent headless, from your own terminal or script:
agent prompt runs Claude Code (or --provider codex) as a background job in the machine. It prints the turn and job it started, and -f follows the agent’s events in your terminal.For any other long command, run instabox exec --background agent -- .... Follow its output with instabox jobs logs agent <job> -f.
5

Pause the machine when you are done

A machine also pauses by itself when idle. It wakes on the next command or SSH connection.
Set a machine up once with your repos, tools, and sign-ins. Save it with instabox snapshot save agent --name agent-base. Start every new agent machine from it with instabox create --name agent2 --snapshot agent-base.
npx instabox@latest adds the instabox skills to your coding agent. You can then ask it to “create an instabox machine and run the tests there”. A client without a CLI can use the MCP server instead: MCP.
Some tools need a login file rather than an HTTPS header, such as an OpenCode auth.json or an SSH key. Such a tool takes a direct Secret delivered as a file: instabox create --name agent --secret-file .local/share/opencode/auth.json=OPENCODE_AUTH. The real value of a direct Secret is readable inside the machine. See Org Secrets.

Org Secrets

Proxy and direct Secrets, hosts, and updating a running machine.

SSH

Sessions, port forwarding, mosh, and large file copies.

Auto-pause and max-run

What counts as idle and what wakes a machine.

Parallel forks

Run several agents on copies of the same machine.