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

# OpenCode on boxd

> Pre-installed. Open-source agent harness on real Linux.

Type `opencode` from any directory on any boxd VM. The CLI is already on the image, reads the standard `AGENTS.md`, and runs against the same in-VM `boxd` CLI the other agents use. Real kernel, full root, persistent disk, public URL.

## How it works

OpenCode is pulled in at image build time, so every fresh VM and every fork has it. The image ships an `AGENTS.md` at `~/.config/opencode/AGENTS.md` covering the boxd environment: how to create siblings with `boxd new`, manage proxies, exec across VMs, and clean up. OpenCode picks it up by default from any working directory.

The in-VM `boxd` CLI is pre-authenticated, so the agent can drive the platform without a token. JSON output is on by default with `--json`, so the agent can parse what it ran.

Auth for the model itself is not yet persisted across resets, so first run on a fresh VM means signing in. Claude Code on boxd already persists auth across resets and forks ([how](/agents/claude-code#how-it-works)); the same UX is on the roadmap for OpenCode.

## Use it

Interactive session:

```bash theme={"theme":"github-dark"}
ssh myapp.boxd
cd my-project
opencode
```

Non-interactive delegation through `boxd machine exec`:

```bash theme={"theme":"github-dark"}
boxd machine exec myvm 'opencode run "Add a /health endpoint to the Flask app"'
```

The same sandbox patterns documented for the other agents apply: fork before risky ops, fan out across VMs, destroy when done. See [Agent sandboxes](/agents/agent-sandboxes).

## Patterns

### Fan-out across VMs

```bash theme={"theme":"github-dark"}
for i in 1 2 3; do boxd machine new try-$i --json & done; wait

boxd machine exec try-1 'opencode run "Use FastAPI" &'
boxd machine exec try-2 'opencode run "Use Flask" &'
boxd machine exec try-3 'opencode run "Use Starlette" &'

# Results: https://try-1.boxd.sh, try-2, try-3
```

### Fork before risky ops

Snapshot a working VM before a destructive change. If the run goes wrong, destroy the fork, fork again from the parent.

```bash theme={"theme":"github-dark"}
boxd machine fork myvm myvm-refactor --json
boxd machine exec myvm-refactor 'opencode run "Refactor the auth module"'
```

### Bias with project-level AGENTS.md

Drop an `AGENTS.md` in your repo. OpenCode merges it with the boxd-provided one, so you keep the platform context for free and add your conventions on top.

<Note color="#E05A6D">
  Auth doesn't persist across resets for OpenCode yet. Plan to sign in once per VM, or use Claude Code on boxd for the persistent-auth UX.
</Note>

## FAQ

<AccordionGroup>
  <Accordion title="Where is AGENTS.md picked up from?">
    `~/.config/opencode/AGENTS.md` is the global file the image ships with. A repo-level `AGENTS.md` is merged on top when you run `opencode` in that directory.
  </Accordion>

  <Accordion title="Can OpenCode drive other boxd VMs?">
    Yes. The in-VM `boxd` CLI works from any agent. OpenCode can `boxd new` siblings, `boxd machine exec` into them, and `boxd machine remove` when done.
  </Accordion>

  <Accordion title="Is there an OpenCode version of the fix-on-issue skill?">
    Not yet. The slash-command skill targets Claude Code today. Email `contact@boxd.sh` and we'll prioritize.
  </Accordion>

  <Accordion title="Can I run Docker, install kernel modules, run systemd?">
    Yes. The VM is a real KVM microVM with its own kernel. Anything you'd do on a Linux laptop, OpenCode can do here.
  </Accordion>
</AccordionGroup>

## Next

<Columns cols={2}>
  <Card title="Agent sandboxes" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/robot.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=e91e744c2d3cd5da053167486b6834bf" href="/agents/agent-sandboxes" width="16" height="16" data-path="images/icons/robot.svg">
    Give OpenCode its own VM. Fork to recover.
  </Card>

  <Card title="Claude Code on boxd" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/claude.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=03286da259893b6993db73a8e038c20b" href="/agents/claude-code" width="16" height="16" data-path="images/icons/claude.svg">
    Same primitives, persistent auth, ships with slash-command skills.
  </Card>
</Columns>