Your first agent

This page takes you from a fresh install to a coding agent running in a sandbox, with your project mounted at /workspace.

If you already use a coding agent on this host, the same command also brings your existing setup — see Switch from your existing agent. If you have not set up OpenCode 2 on this host yet, do that once first: the sandbox copies its host configuration and credentials, so OpenCode 2 starts without a separate login. Other agents may require a separate login inside the sandbox.

Install agents-sandbox

Install it with Homebrew, or download a release binary. Installation covers both.

Run an agent

Change into a project and start the default agent, OpenCode 2:

cd ~/my-project
agents-sandbox

The first run builds the runner image and creates the sandbox; later runs reuse it. To start a different agent, pass --agent: agents-sandbox --agent opencode, agents-sandbox --agent pi, agents-sandbox --agent claude-code, agents-sandbox --agent codex, agents-sandbox --agent hermes, or agents-sandbox --agent oh-my-pi.

What you see

The agent’s own interface opens inside the sandbox. The project is mounted at /workspace, and those are the same files as your host checkout, so edits the agent makes are visible on the host.

Detach with the agent’s own exit key (for example Ctrl-D). The sandbox keeps running and stops on its own when idle; to stop it manually, run agents-sandbox stop, passing the same --agent value you started with (for example agents-sandbox stop --agent pi).

Next steps:

• Switch from your existing agent — bring your existing agent config and credentials into the sandbox.
• Manage config in the sandbox — self-contained, reproducible configuration with secrets kept on the host.
• Sandboxes — how sandboxes are named, stored, and reclaimed.