Skip to main content
OpenCode is an open-source coding agent runtime. The Docker Compose profile starts OpenCode alongside the LiteLLM Agent Platform and registers local-opencode automatically.

​
Prerequisites

  • Docker Desktop installed and running
  • LiteLLM Agent Platform repo cloned

​
1. Start the stack

docker compose --profile opencode up
This starts:
  • The LiteLLM Agent Platform web/API service
  • A Postgres database
  • The OpenCode runtime harness
  • Registers local-opencode in the UI automatically
Open http://localhost:4000 and sign in with your master key (sk-local by default).

​
2. Add model provider credentials

Before running an agent, add at least one model provider key in Settings → Credentials (e.g. an Anthropic or OpenAI API key). OpenCode routes model calls through your LiteLLM gateway.

​
3. Create an agent

In the UI, click New Agent, choose local-opencode as the runtime, select a model, and optionally set a system prompt. Or via the API: 
curl -X POST http://localhost:4000/api/agents \
  -H "Authorization: Bearer sk-local" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-opencode-agent",
    "owner_id": "local-user",
    "runtime": "local-opencode",
    "model": "claude-opus-4-5",
    "system": "You are a senior software engineer."
  }'

​
4. Run your agent

Select your agent in the UI and click Run. Type a message in the chat panel and OpenCode will start executing. Or via the API: 
# Start and run a session
SESSION=$(curl -s -X POST http://localhost:4000/session \
  -H "Authorization: Bearer sk-local" \
  -H "Content-Type: application/json" \
  -d '{
    "runtime": "local-opencode",
    "agent_id": "<agent-id>",
    "prompt": "Add type annotations to all functions in src/"
  }' | jq -r .id)

# Stream the response
curl -N "http://localhost:4000/v1/sessions/$SESSION/events/stream" \
  -H "Authorization: Bearer sk-local"

​
Stop the stack

docker compose --profile opencode down

​
Run alongside other runtimes

You can start multiple runtimes at once: 
docker compose --profile opencode --profile deepagents up
This registers both local-opencode and local-deepagents in the UI.

​
Configuration

OpenCode runtime configuration lives in the compose.yaml opencode service block. You can override the default model and tool settings via environment variables in that block.

​
Sandboxed execution with OpenSandbox

By default the OpenCode harness runs agent commands directly on the host container. OpenSandbox routes every command and file operation into an isolated container sandbox instead, so the agent cannot touch host state. When OpenSandbox is configured:
  • Native bash and file-edit operations are denied at the harness level.
  • A sandbox-exec MCP server is injected into OpenCode’s tool config automatically.
  • Each session creates a fresh sandbox, executes all commands there, then terminates it.

​
How it works

opencode  →  sandbox-exec MCP server
                 │
                 ├─ POST /v1/sandboxes                         (create)
                 ├─ GET  /v1/sandboxes/{id}/endpoints/44772    (resolve execd URL)
                 ├─ POST {execd}/command                       (run command, SSE stream)
                 ├─ GET  {execd}/files/download                (read file)
                 ├─ POST {execd}/files/upload                  (write file)
                 └─ DELETE /v1/sandboxes/{id}                  (terminate)
The harness talks to the OpenSandbox controller (sandbox lifecycle) and execd (command execution inside the sandbox) over plain HTTP. No SDK dependency — Node 20 built-ins only.

​
Environment variables

VariableRequiredDescription
OPENSANDBOX_API_URLYesOpenSandbox controller base URL (e.g. http://opensandbox-server.opensandbox-system.svc.cluster.local)
OPENSANDBOX_API_KEYWhen auth enabledAPI key sent as OPEN-SANDBOX-API-KEY header
OPENSANDBOX_IMAGEYesexecd container image (e.g. sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:v1.0.18)
SANDBOX_PROVIDERNoDefaults to opensandbox. Only opensandbox is supported.
Set any of these on the opencode service and the harness enables sandbox mode automatically. If OPENSANDBOX_API_URL is unset, sandbox mode is skipped and commands run on the host as normal.

​
Local Docker Compose

For local testing, point the opencode service at an external OpenSandbox instance by adding env vars to compose.yaml: 
opencode:
  environment:
    OPENSANDBOX_API_URL: http://host.docker.internal:8090
    OPENSANDBOX_API_KEY: my-local-key
    OPENSANDBOX_IMAGE: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:v1.0.18
Then run as normal: 
docker compose --profile opencode up

​
Production deployment on EKS

For production, deploy the full OpenSandbox Kubernetes operator alongside the opencode-anthropic-server. The stack runs:
  • OpenSandbox controller — manages sandbox lifecycle via BatchSandbox CRDs
  • OpenSandbox server — HTTP API gateway the harness calls
  • opencode-anthropic-server — the OpenCode harness wired to OpenSandbox
Key resources:
  • Kubernetes namespace: opensandbox-system
  • Helm charts: opensandbox-controller, opensandbox-server
  • Sandbox images: opensandbox/execd:v1.0.18, opensandbox/egress:v1.0.12
  • Default sandbox resource limits: 1 CPU, 2 GiB RAM
See the EKS deployment guide for the full step-by-step: cluster setup, EBS CSI driver, OpenSandbox Helm install, ECR push, and Kubernetes manifests. Quick-start: paste the agent prompt from that guide into any coding agent and it will walk through every step, asking for credentials as needed.