OpenCode

OpenCode is an open-source coding agent that works with many model providers. In an Archil sandbox it gets a Linux VM of its own, so you can let it work without approving each step. Its workspace and session history live on an Archil disk, so the work outlives the sandbox, and a new sandbox can continue the same session.

Prerequisites

Export your Archil API key, a region where sandboxes are available (aws-us-east-1, aws-us-west-2, or aws-eu-west-1), and an Anthropic API key, then install the SDK:

export ARCHIL_API_KEY=key-...
export ARCHIL_REGION=aws-us-east-1
export ANTHROPIC_API_KEY=sk-ant-...

npm init -y && npm pkg set type=module
npm install disk tsx

pip install archil

Run OpenCode in a sandbox

This script creates a disk, starts a sandbox with the disk mounted at /workspace, installs OpenCode, and gives it a task with opencode run, which works until the task is done, prints the result, and exits. Then it deletes the sandbox; everything the agent made is on the disk.

import * as archil from "disk";

const env = {
  ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
  XDG_DATA_HOME: "/workspace/.local/share", // keep sessions on the disk
};

const { disk } = await archil.createDisk({ name: "opencode-workspace" });
const sandbox = await archil.createSandbox({ name: "opencode", mounts: [{ disk, path: "/workspace" }] });
await sandbox.exec("npm install -g opencode-ai");

// --auto approves every permission request; < /dev/null: no more prompt text is coming on stdin.
const result = await sandbox.exec(
  "opencode run --model anthropic/claude-sonnet-5 --auto " +
    '"Create a hello-world Express app with a test, and run the test. Reply in two sentences." < /dev/null',
  { cwd: "/workspace", env },
);
console.log(result.stdout);

await sandbox.stop();
await sandbox.delete();

import os

import archil

env = {
    "ANTHROPIC_API_KEY": os.environ["ANTHROPIC_API_KEY"],
    "XDG_DATA_HOME": "/workspace/.local/share",  # keep sessions on the disk
}

disk = archil.create_disk(name="opencode-workspace").disk
sandbox = archil.create_sandbox(
    name="opencode", mounts=[archil.SandboxMountSpec(disk=disk, path="/workspace")]
)
sandbox.exec("npm install -g opencode-ai")

# --auto approves every permission request; < /dev/null: no more prompt text is coming on stdin.
result = sandbox.exec(
    "opencode run --model anthropic/claude-sonnet-5 --auto "
    '"Create a hello-world Express app with a test, and run the test. Reply in two sentences." < /dev/null',
    cwd="/workspace",
    env=env,
)
print(result.stdout)

sandbox.stop()
sandbox.delete()

Run it with npx tsx start.ts or python start.py. The agent’s wording varies from run to run. One run printed:

I created a hello-world Express app at `/workspace/hello-world-express` (app.js, server.js, app.test.js) with a Jest/Supertest test verifying `GET /` returns "Hello, World!". The test ran successfully: 1 passed, 1 total.

Pick up where you left off

OpenCode’s project and session history are on the disk, so any sandbox that mounts it can continue the session. This script starts a new sandbox on the same disk and runs opencode run --continue, which continues the most recent session.

import * as archil from "disk";

const env = {
  ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
  XDG_DATA_HOME: "/workspace/.local/share",
};

const [disk] = await archil.listDisks({ name: "opencode-workspace" });
const sandbox = await archil.createSandbox({ name: "opencode", mounts: [{ disk, path: "/workspace" }] });
await sandbox.exec("npm install -g opencode-ai");

const result = await sandbox.exec(
  "opencode run --continue --model anthropic/claude-sonnet-5 --auto " +
    '"Add a /health route with a test and run all the tests. Reply in two sentences." < /dev/null',
  { cwd: "/workspace", env },
);
console.log(result.stdout);

await sandbox.stop();
await sandbox.delete();

import os

import archil

env = {
    "ANTHROPIC_API_KEY": os.environ["ANTHROPIC_API_KEY"],
    "XDG_DATA_HOME": "/workspace/.local/share",
}

[disk] = archil.list_disks(name="opencode-workspace")
sandbox = archil.create_sandbox(
    name="opencode", mounts=[archil.SandboxMountSpec(disk=disk, path="/workspace")]
)
sandbox.exec("npm install -g opencode-ai")

result = sandbox.exec(
    "opencode run --continue --model anthropic/claude-sonnet-5 --auto "
    '"Add a /health route with a test and run all the tests. Reply in two sentences." < /dev/null',
    cwd="/workspace",
    env=env,
)
print(result.stdout)

sandbox.stop()
sandbox.delete()

I added a `/health` route to app.js:9-11 that returns `{ status: 'ok' }` with a 200 status, along with a corresponding Jest test in app.test.js. All tests pass: 2 passed, 2 total.

Going further

Stream output. Pass onOutput: ({ data }) => process.stdout.write(data) to exec (in Python, on_output=lambda out: sys.stdout.buffer.write(out.data)) to watch the agent as it works. Add --format json to opencode run to get one JSON event per line.
Work interactively. Start opencode in a pseudo-terminal with sandbox.run; see Opening interactive shells.
Run the OpenCode server. opencode serve runs OpenCode as an HTTP server that the OpenCode terminal UI (opencode attach) and the OpenCode SDK connect to. Run it as a sandbox service so it keeps running and restarts with the sandbox. Set OPENCODE_SERVER_PASSWORD on the server, and reach it with a port token, or with a public port if you use opencode attach, which can’t send the token header.

Use Vercel AI Gateway instead of an Anthropic key

OpenCode has a built-in Vercel AI Gateway provider, vercel, that reads AI_GATEWAY_API_KEY. Export AI_GATEWAY_API_KEY instead of ANTHROPIC_API_KEY, replace the ANTHROPIC_API_KEY line in env with this one, and change --model anthropic/claude-sonnet-5 to --model vercel/anthropic/claude-sonnet-5 in both scripts. On the Developer plan, sandboxes can’t reach the gateway, because it isn’t on the managed allowlist; use your provider key instead.

AI_GATEWAY_API_KEY: process.env.AI_GATEWAY_API_KEY!,

"AI_GATEWAY_API_KEY": os.environ["AI_GATEWAY_API_KEY"],

Clean up

Each script deletes its sandbox when it finishes, so only the disk is left. Delete it:

import * as archil from "disk";

const [disk] = await archil.listDisks({ name: "opencode-workspace" });
await disk.delete();

import archil

[disk] = archil.list_disks(name="opencode-workspace")
disk.delete()

Next steps

Claude Code

Run Claude Code headlessly in a sandbox.

OpenAI Codex

Run the Codex CLI headlessly in a sandbox.

Coding agent in a sandbox

Build your own coding agent with the AI SDK instead.

Persistent sandboxes

Lifecycle, services, network access, and forking in detail.

Agents

Analytics

Training

Apps & databases

Use Archil on other platforms

Prerequisites

Run OpenCode in a sandbox

Pick up where you left off

Going further

Clean up

Next steps

Claude Code

OpenAI Codex

Coding agent in a sandbox

Persistent sandboxes

​Prerequisites

​Run OpenCode in a sandbox

​Pick up where you left off

​Going further

​Clean up

​Next steps

Claude Code

OpenAI Codex

Coding agent in a sandbox

Persistent sandboxes

Prerequisites

Run OpenCode in a sandbox

Pick up where you left off

Going further

Clean up

Next steps