OpenCode Sandbox: Run Coding Agents

This guide shows you how to set up an OpenCode sandbox using Novita Sandbox. You’ll configure the environment, launch OpenCode, and run your coding agent in an isolated runtime.

What you’ll build

You will build a reusable sandbox template with OpenCode pre-installed, then start a sandbox from it and hand OpenCode a coding task. OpenCode runs entirely inside the sandbox: it writes files, runs shell commands, and executes the code it generates there, while a Novita-hosted model does the reasoning. Your machine only sends the task and reads back the result.

Prerequisites

Novita API key — create one in Key Management and export it as NOVITA_API_KEY. The same key authenticates both the sandbox and the model calls.
Novita Sandbox SDK — Python 3.10+ or Node.js 20+:

pip install novita-sandbox

npm install novita-sandbox

OpenCode version — this guide installs the opencode-ai npm package and was written against OpenCode 1.19. The configuration uses the provider / permission format that OpenCode 1.19 reads. The providers / permissions format in the newer published schema is not supported by 1.19 and is silently ignored or rejected.

export NOVITA_API_KEY=sk_your_api_key

Quickstart

1. Build an OpenCode sandbox template (one time)

A template bakes OpenCode into the sandbox image, so each new sandbox starts in seconds instead of reinstalling it. Build it once; reuse it for every run.

from novita_sandbox import Novita

novita = Novita()
template = novita.template.new().from_node_image("22").npm_install("opencode-ai", g=True)

build = novita.template.build(template, "opencode-agent", cpu_count=2, memory_mb=2048)
print("Template ID:", build.template_id)

import { Novita } from 'novita-sandbox'

const novita = new Novita()
const template = novita.template.new().fromNodeImage('22').npmInstall('opencode-ai', { g: true })

const build = await novita.template.build(template, 'opencode-agent', { cpuCount: 2, memoryMB: 2048 })
console.log('Template ID:', build.templateId)

2. Run OpenCode in a sandbox

The script below writes an OpenCode config that points at the Novita LLM API, runs one non-interactive task with opencode run, and kills the sandbox.

import json, os
from novita_sandbox import Novita

MODEL = "deepseek/deepseek-v4.1-flash"
config = {
    "model": f"novita/{MODEL}",
    "provider": {"novita": {
        "name": "Novita AI", "npm": "@ai-sdk/openai-compatible",
        "options": {"baseURL": "https://api.novita.ai/openai/v1", "apiKey": "{env:NOVITA_API_KEY}"},
        "models": {MODEL: {"name": MODEL}}}},
    "permission": {"edit": "allow", "bash": "allow"},
}

sandbox = Novita().sandbox.create("opencode-agent", timeout=1800, envs={"NOVITA_API_KEY": os.environ["NOVITA_API_KEY"]})
try:
    sandbox.files.write("/home/user/.config/opencode/opencode.json", json.dumps(config))
    sandbox.commands.run('opencode run "Write fizzbuzz.js, run it with node, and show the output"',
                         cwd="/home/user", on_stdout=lambda d: print(d, end=""), timeout=0)
finally:
    sandbox.kill()

import { Novita } from 'novita-sandbox'

const MODEL = 'deepseek/deepseek-v4.1-flash'
const config = {
  model: `novita/${MODEL}`,
  provider: { novita: {
    name: 'Novita AI', npm: '@ai-sdk/openai-compatible',
    options: { baseURL: 'https://api.novita.ai/openai/v1', apiKey: '{env:NOVITA_API_KEY}' },
    models: { [MODEL]: { name: MODEL } } } },
  permission: { edit: 'allow', bash: 'allow' },
}

const sandbox = await new Novita().sandbox.create('opencode-agent', { timeoutMs: 1_800_000, envs: { NOVITA_API_KEY: process.env.NOVITA_API_KEY } })
try {
  await sandbox.files.write('/home/user/.config/opencode/opencode.json', JSON.stringify(config))
  await sandbox.commands.run('opencode run "Write fizzbuzz.js, run it with node, and show the output"',
    { cwd: '/home/user', onStdout: (d) => process.stdout.write(d), timeoutMs: 0 })
} finally {
  await sandbox.kill()
}

opencode run "<prompt>" runs OpenCode without its terminal UI: it processes the prompt, prints the result, and exits, which makes it scriptable. OpenCode already allows most tool use by default; the explicit permission settings pin file edits (edit) and shell commands (bash) to allow, so a project-level config in a cloned repo can’t switch them to prompting and stall a headless run. That is safe here because everything happens inside a disposable sandbox.

How it works

OpenCode gets a full Linux environment inside the sandbox. You drive it with the SDK: files to move data in and out, commands to run OpenCode and anything else. The snippets below assume a sandbox created and configured as in the Quickstart.

Execute generated code

OpenCode writes code and runs it in the sandbox’s shell. Its stdout and stderr stream back to you through on_stdout / on_stderr, and the call returns the exit code.

result = sandbox.commands.run(
    'opencode run "Create server.js with a /health route using Node\'s http module, start it, and test it with curl"',
    cwd="/home/user",
    on_stdout=lambda d: print(d, end=""),
    on_stderr=lambda d: print(d, end=""),
    timeout=0,
)
print("exit code:", result.exit_code)

const result = await sandbox.commands.run(
  'opencode run "Create server.js with a /health route using Node\'s http module, start it, and test it with curl"',
  {
    cwd: '/home/user',
    onStdout: (d) => process.stdout.write(d),
    onStderr: (d) => process.stderr.write(d),
    timeoutMs: 0,
  }
)
console.log('exit code:', result.exitCode)

Read and write files

Upload inputs before the run and read the agent’s output afterwards. For whole repositories, use sandbox.git.clone; for large files, see Upload and Download.

sandbox.files.write("/home/user/data/sales.csv", open("sales.csv").read())
sandbox.commands.run('opencode run "Summarize data/sales.csv into report.md"', cwd="/home/user", timeout=0)

print(sandbox.files.read("/home/user/report.md"))

import { readFile } from 'node:fs/promises'

await sandbox.files.write('/home/user/data/sales.csv', await readFile('sales.csv', 'utf8'))
await sandbox.commands.run('opencode run "Summarize data/sales.csv into report.md"', { cwd: '/home/user', timeoutMs: 0 })

console.log(await sandbox.files.read('/home/user/report.md'))

Run commands yourself

You can run any command next to the agent — install dependencies before it starts, or verify its work afterwards without trusting its own report.

sandbox.commands.run("npm init -y && npm install --save-dev jest", cwd="/home/user", timeout=300)
sandbox.commands.run('opencode run "Add Jest unit tests for server.js"', cwd="/home/user", timeout=0)

check = sandbox.commands.run("npx jest", cwd="/home/user")
print(check.stdout)

await sandbox.commands.run('npm init -y && npm install --save-dev jest', { cwd: '/home/user', timeoutMs: 300_000 })
await sandbox.commands.run('opencode run "Add Jest unit tests for server.js"', { cwd: '/home/user', timeoutMs: 0 })

const check = await sandbox.commands.run('npx jest', { cwd: '/home/user' })
console.log(check.stdout)

A command that exits non-zero raises CommandExitException (Python) or CommandExitError (JavaScript). Catch it when a failing test run is an expected outcome.

Use Novita models

The Quickstart already routes OpenCode through Novita’s OpenAI-compatible API. To switch models, change one line — MODEL — to any model ID from the Novita model library, for example moonshotai/kimi-k2.7-code or zai-org/glm-5.3.

MODEL = "moonshotai/kimi-k2.7-code"

The model ID must match the Model Hub value exactly. Model usage is billed separately from sandbox runtime, at the model’s own per-token rate.

Production tips

Timeouts — timeout (seconds; timeoutMs in JavaScript) on sandbox.create is the sandbox’s maximum lifetime; extend it while the agent works with set_timeout. Pass timeout=0 to commands.run so a long agent turn isn’t cut off at the SDK’s default command timeout.
Pause and resume — for multi-step jobs, pause the sandbox between steps instead of killing it. Files, installed packages and OpenCode’s session state survive, and CPU and RAM billing stops while it is paused.
Concurrency — each sandbox is isolated, so you can run one OpenCode task per sandbox in parallel. Concurrent sandboxes are capped by your account tier (5 on Free, 100 on Paid); see Quota Limits.
Cost — sandboxes are billed per second while running. A 2 vCPU / 2 GiB sandbox costs about $0.0000260/s, so a 10-minute task is roughly $0.016 in sandbox time, plus model tokens. See Pricing.
Always clean up — kill sandboxes in a finally block (as above) so a crash in your script doesn’t leave one running until its timeout.

Troubleshooting

402: insufficient balance when creating a sandbox

Your account balance can’t cover a new sandbox. Top up on the Billing page or claim the new-user credits described in Pricing, then retry.

Template not found when creating the sandbox

The name passed to sandbox.create must match the name you built (opencode-agent above) in the same team as your API key. Run novita.template.list() to see your templates, or pass build.template_id directly.

OpenCode exits with a model or provider error

Check that the model value is novita/<model ID>, that the same ID is a key under provider.novita.models, and that NOVITA_API_KEY was passed in envs — run echo $NOVITA_API_KEY in the sandbox to check it isn’t empty, because an unset variable becomes an empty key and shows up as Unauthorized. Run opencode debug config in the sandbox — it prints the resolved configuration and reports an invalid file — and opencode models to check that novita/<model ID> is listed.

Next steps

Sandbox SDK reference

Every option for creating and managing sandboxes.

Build templates

Add your own tools and dependencies to the OpenCode image.

Sandbox cookbook

Runnable Novita Sandbox examples on GitHub.

More agent integrations

Run Claude Code, Codex, or OpenClaw in a sandbox.

Get started

Model APIs

Novita Sandbox

GPUs

Observability

Resources

OpenCode Sandbox: Run Coding Agents with Novita

What you’ll build

Prerequisites

Quickstart

1. Build an OpenCode sandbox template (one time)

2. Run OpenCode in a sandbox

How it works

Execute generated code

Read and write files

Run commands yourself

Use Novita models

Production tips

Troubleshooting

Next steps

Sandbox SDK reference

Build templates

Sandbox cookbook

More agent integrations

​What you’ll build

​Prerequisites

​Quickstart

​1. Build an OpenCode sandbox template (one time)

​2. Run OpenCode in a sandbox

​How it works

​Execute generated code

​Read and write files

​Run commands yourself

​Use Novita models

​Production tips

​Troubleshooting

​Next steps

Sandbox SDK reference

Build templates

Sandbox cookbook

More agent integrations

What you’ll build

Prerequisites

Quickstart

1. Build an OpenCode sandbox template (one time)

2. Run OpenCode in a sandbox

How it works

Execute generated code

Read and write files

Run commands yourself

Use Novita models

Production tips

Troubleshooting

Next steps