> ## Documentation Index
> Fetch the complete documentation index at: https://instabox.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Coding agents

> Run Claude Code, Codex, or OpenCode in a machine of its own.

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**

```bash theme={null}
instabox secrets set ANTHROPIC_API_KEY --ai anthropic
```

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**

```bash theme={null}
instabox create --name agent --secrets ANTHROPIC_API_KEY
```

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.

```bash theme={null}
cd my-repo
instabox push agent .            # tracked files only; --all adds untracked ones
```

`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:

```bash theme={null}
instabox ssh agent
cd my-repo && claude
```

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:

```bash theme={null}
instabox agent prompt agent --cwd /data/home/my-repo -f "fix the failing test"
instabox agent steer agent "use the existing helper instead"
instabox agent events agent -f
```

`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**

```bash theme={null}
instabox suspend agent           # files, memory and processes kept
instabox resume agent            # later: carry on where it left off
```

A machine also pauses by itself when idle. It wakes on the next command or SSH connection.

> [!TIP]
>
> 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`.

> [accordion] Let the agent manage machines itself
>
> `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](https://instabox.sh/docs/integrations/mcp.md).

> [accordion] Login files and other credentials
>
> 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](https://instabox.sh/docs/security/secrets.md).

> [card] [Org Secrets](https://instabox.sh/docs/security/secrets.md)
>
> Proxy and direct Secrets, hosts, and updating a running machine.

> [card] [SSH](https://instabox.sh/docs/access/ssh.md)
>
> Sessions, port forwarding, mosh, and large file copies.

> [card] [Auto-pause and max-run](https://instabox.sh/docs/machines/auto-pause.md)
>
> What counts as idle and what wakes a machine.

> [card] [Parallel forks](https://instabox.sh/docs/use-cases/parallel-forks.md)
>
> Run several agents on copies of the same machine.