Getting Started

What is opencode-sandbox?

opencode-sandbox is a launcher that runs opencode inside an isolated microsandbox VM powered by microsandbox. Each project gets a persistent VM identified by its git remote URL — first boot creates a fresh VM, subsequent runs connect to or start the existing one. The VM has your project bound as /workspace, a persistent home directory volume, and access to a curated toolchain.

Prerequisites

opencode-sandbox requires platform-specific prerequisites depending on your operating system:

Linux (KVM)

  • Docker running with rootless or rootful daemon
  • KVM available (check with kvm-ok or /dev/kvm existence)

macOS (Apple Silicon)

  • Apple Silicon (arm64) — Intel (x86_64) Macs are not supported.
  • Docker Desktop or colima — ensure the Docker socket is accessible (docker info succeeds)

OS independent

  • msb CLI — the microsandbox runtime — opencode-sandbox tries to install it automatically
  • Git — for branch sessions

If you’re unsure your system fulfills the prerequisites, you can verify your setup:

opencode-sandbox doctor

Installation

  • Download the latest binary:

    Linux (x86_64):

    curl -L -o opencode-sandbox https://github.com/inoio/opencode-sandbox/releases/latest/download/opencode-sandbox-linux-amd64

    macOS (Apple Silicon):

    curl -L -o opencode-sandbox https://github.com/inoio/opencode-sandbox/releases/latest/download/opencode-sandbox-darwin-arm64

    Linux (arm64):

    curl -L -o opencode-sandbox https://github.com/inoio/opencode-sandbox/releases/latest/download/opencode-sandbox-linux-arm64

  • Install:

    chmod u+x opencode-sandbox
mv opencode-sandbox ~/.local/bin # or any other directory in your PATH

Quick Start

Navigate to any directory and run:

opencode-sandbox

This starts a microsandbox VM (or connects to the existing project VM), mounts the working directory into the VM , and launches opencode.

To start an isolated session for a different branch (only works in git repositories):

opencode-sandbox -w bugfix-my-fix

Adding Providers & Configuration

If you have been using opencode, start by copying your existing opencode.json:

cp ~/.config/opencode/opencode.json ~/.config/opencode-sandbox/opencode/opencode.json

Then, replace any API keys and secrets with a reference to an environment variable, e.g.:

{
  "provider": {
    "...": {
      "options": {
        "apiKey": "{env:YOUR_PROVIDER_API_KEY}"
      }
    }
  }
}

All that’s left to do is to define a secret in ~/.config/opencode-sandbox/env.secret.yaml:

YOUR_PROVIDER_API_KEY:
  value: <your-api-key>
  host: provider.example

See Configuration for more details.

How It Works

  1. Image build — Builds a Docker image from .opencode-sandbox/Dockerfile if present, or uses the base image. The image contains opencode, Node.js 26, and common CLI tools.
  2. Volume setup — Creates a persistent home volume (managed by msb, name: opencode-sandbox-home-<project-slug>-<timestamp>) for the project, preserving editor state, caches, and config across sessions.
  3. VM creation or reuse — Creates a new project VM on first boot; subsequent runs connect to the existing VM (or restart it if it stopped).
  4. Provisioning — Merges your opencode config snippets into a single opencode.json in the VM home, provisions home.yaml mappings, and syncs them into the VM.
  5. Opencode — Runs opencode attach inside the VM, forwarding any arguments after -- to the AI agent.
  6. Cleanup — On exit, the session detaches. The VM-internal worktree is managed by opencode; on subsequent runs it is reused. The host repo is untouched.

See the Commands reference for the full API and Configuration for tuning behavior.

Agent Context (AGENTS.md)

An AGENTS.md in the working directory can orient the agent on being in a sandbox VM, available tooling etc. Here is a minimal, self-explanatory example you can copy and adapt:

## Environment

You are running inside a sandbox VM, not on the host. Filesystem layout:

- `/workspace` bind mount of the host CWD, mounted rw.
- `~/.local/share/opencode/worktree/` git worktrees of `/workspace`, created by opencode

## Toolchain

Common CLI tools are preinstalled: git, node, npm, jq, yq etc. Don't install additional tools yourself without permission.

No SSH keys in the VM, git cmds against remotes won't work.

Example: Permissions

Opencode permissions are configured through opencode config snippets, which opencode-sandbox merges (user-first, then project; see Configuration). Place a snippet in your project, e.g. .opencode-sandbox/opencode/permission.json5.

Quasi-auto: allow everything except what is explicitly denied:

{
  // .opencode-sandbox/opencode/permission.json5
  permission: {
    "*": "allow",
  },
}

Protect secrets: deny reads of .env and .envrc files:

{
  // .opencode-sandbox/opencode/permission.json5
  permission: {
    denylist: [
      { tool: "read", files: [".env", ".envrc"] },
    ],
  },
}

Caveat: these rules are advisory for opencode’s own Q&A tools. The bash tool executes arbitrary commands inside the VM and can read any file regardless of these deny rules, so they are not a security boundary — keep secrets out of the VM or rely on the secret mechanism instead.

Next Steps