> ## 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.

# Claude Code on boxd

> Pre-installed. Persistent auth. Reads your CLAUDE.md by default.

Type `claude` from any directory on any boxd VM. The CLI is already installed, already authenticated against your subscription, and already briefed on the environment via a built-in `CLAUDE.md`. Reset the VM, fork it, spin up ten more, the auth follows.

## How it works

Claude Code ships on the default image. Auth is keyed to your boxd account, not the VM, so credentials survive resets, destroys, and forks. There's nothing to copy between machines.

Every VM also ships with a `CLAUDE.md` at `~/.claude/CLAUDE.md` that teaches the agent the boxd environment: how to use the in-VM `boxd` CLI to create siblings, manage proxies, exec across VMs, and clean up. Plus a `boxd-cli` skill at `~/.claude/skills/boxd-cli/SKILL.md` that loads automatically when the agent is asked anything boxd-shaped.

The result: you don't have to re-brief the agent on what platform it's on. It already knows.

## Use it

Interactive session, the obvious way:

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

Non-interactive delegation, for when you want the agent to do a job and return a session you can resume later:

```bash theme={"theme":"github-dark"}
RESULT=$(boxd machine exec myvm --json \
  'claude -p --output-format json "Build a Flask API on port 8000" \
   --dangerously-skip-permissions 2>/dev/null')

SESSION_ID=$(echo "$RESULT" | jq -r '.output' | jq -r .session_id)

boxd machine exec myvm "claude -p --resume $SESSION_ID \
  \"Add a /health endpoint\" --dangerously-skip-permissions"
```

Take over interactively from your laptop whenever you want:

```bash theme={"theme":"github-dark"}
ssh myvm.boxd
claude --resume <session_id>
```

## Patterns

### Fan-out across VMs

Spin up three VMs, hand each a variant of the task, pick the winner. Each result is live at its own URL.

```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 'claude -p "Use FastAPI" --dangerously-skip-permissions &'
boxd machine exec try-2 'claude -p "Use Flask" --dangerously-skip-permissions &'
boxd machine exec try-3 'claude -p "Use Starlette" --dangerously-skip-permissions &'

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

### Slash-command setup workflows

The CLI installer drops Claude Code skills on your laptop. Inside a repo, run `/boxd-setup-golden`, `/boxd-setup-deploy`, or `/boxd-setup-fix` and the agent wires up the workflow end-to-end — golden VM, webhooks, and any repo changes land in reviewable PRs. See [Skills](/reference/skills).

<Note color="#E05A6D">
  Claude Code only for now — [reach out](mailto:contact@boxd.sh) for Codex, OpenCode, or any other agent.
</Note>

### Authenticate once

First time you run `claude` on any boxd VM, sign in. After that, every machine on your boxd account already has you logged in. No env var, no config file copy.

## FAQ

<AccordionGroup>
  <Accordion title="Where does the auth live?">
    On your boxd account, encrypted, injected into the VM at boot. You can revoke it from the dashboard.
  </Accordion>

  <Accordion title="Can I bring an API key instead of a subscription?">
    Yes. Set `ANTHROPIC_API_KEY` in the VM. Same `claude` binary, same `CLAUDE.md`.
  </Accordion>

  <Accordion title="What's in CLAUDE.md by default?">
    A short tour of the boxd environment, the in-VM `boxd` CLI, the default proxy on port 8000, and how to manage other VMs from this one. Add your project conventions on top.
  </Accordion>

  <Accordion title="Does the session survive a reboot?">
    Yes. Session state lives on the persistent disk. Resume after a reboot with `claude --resume <session_id>`.
  </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 Claude its own VM. Fork before risky ops.
  </Card>

  <Card title="Fix-on-issue loop" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/bug.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=793936d309dacb75c015231f4754aa3e" href="/agents/fix-on-issue" width="16" height="16" data-path="images/icons/bug.svg">
    Label an issue, get a PR with a live preview URL.
  </Card>
</Columns>