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

# OpenClaw Sandbox: Run AI Agents with Novita

> Learn how to set up an OpenClaw sandbox with Novita AI. Configure your agent and run OpenClaw in an isolated environment with this step-by-step guide.

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

> [!TIP]
>
> **Want a persistent OpenClaw assistant, not a script?** [NovitaClaw](https://docs.novita.ai/guides/novitaclaw.md) deploys OpenClaw on Novita Sandbox with one command — `novitaclaw launch` — and gives you a Web UI, Gateway, Web Terminal, and Telegram / Slack channels that run 24/7. See [Always-on OpenClaw with NovitaClaw](#always-on-openclaw-with-novitaclaw) below. This guide is for running OpenClaw programmatically from your own code.

## What you'll build

You will build a reusable sandbox template with OpenClaw and its Novita model provider pre-installed, then start a sandbox from it and give the agent a task with `openclaw agent exec`. The agent's tools — shell, file edits, code execution — run inside the isolated sandbox, and a Novita-hosted model does the reasoning. Your app only sends the task and reads back the result.

```mermaid theme={"system"}
flowchart TB
  App["Your app<br/>(novita-sandbox SDK)"] -- "create sandbox,<br/>openclaw agent exec" --> Sandbox
  subgraph Sandbox["Novita Sandbox (isolated runtime)"]
    OpenClaw["OpenClaw agent"] --> Tools["Files · Shell · Code"]
  end
  OpenClaw -- "@openclaw/novita-provider" --> Model["Novita LLM API<br/>api.novita.ai/openai/v1"]
```

## Prerequisites

* **Novita API key** — create one in [Key Management](https://novita.ai/settings/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+:

```bash Python icon="python" theme={"system"}
pip install novita-sandbox
```

```bash JavaScript & TypeScript icon="js" theme={"system"}
npm install novita-sandbox
```

* **OpenClaw version** — this guide installs the `openclaw` npm package and was written against OpenClaw **2026.11**. OpenClaw requires Node.js 24.16 or later; the template below uses the `node:24` image, which tracks the latest 24.x release. Models come from the official [`@openclaw/novita-provider`](https://www.npmjs.com/package/@openclaw/novita-provider) plugin.

```bash theme={"system"}
export NOVITA_API_KEY=sk_your_api_key
```

## Quickstart

### 1. Build an OpenClaw sandbox template (one time)

A [template](https://docs.novita.ai/guides/sandbox-template-build-operations.md) bakes OpenClaw and the Novita provider into the sandbox image, so each new sandbox starts in seconds instead of reinstalling them. Build it once; reuse it for every run.

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()
template = (
    novita.template.new()
    .from_node_image("24")
    .npm_install("openclaw", g=True)
    .set_user("user")
    .run_cmd("openclaw plugins install @openclaw/novita-provider --accept-capabilities")
)

build = novita.template.build(template, "openclaw-agent", cpu_count=2, memory_mb=4096)
print("Template ID:", build.template_id)
```

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()
const template = novita.template
  .new()
  .fromNodeImage('24')
  .npmInstall('openclaw', { g: true })
  .setUser('user')
  .runCmd('openclaw plugins install @openclaw/novita-provider --accept-capabilities')

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

### 2. Run OpenClaw in a sandbox

`openclaw agent exec` runs one headless agent turn and exits — OpenClaw's recommended entry point for scripts and CI. The provider plugin reads `NOVITA_API_KEY` from the environment.

```python Python icon="python" theme={"system"}
import os
from novita_sandbox import Novita

sandbox = Novita().sandbox.create(
    "openclaw-agent", timeout=1800, envs={"NOVITA_API_KEY": os.environ["NOVITA_API_KEY"]}
)
try:
    sandbox.commands.run(
        'openclaw agent exec "Write fizzbuzz.js, run it with node, and show the output" '
        "--model novita/deepseek/deepseek-v4-pro --cwd /home/user",
        on_stdout=lambda d: print(d, end=""),
        timeout=0,
    )
finally:
    sandbox.kill()
```

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const sandbox = await new Novita().sandbox.create('openclaw-agent', {
  timeoutMs: 1_800_000,
  envs: { NOVITA_API_KEY: process.env.NOVITA_API_KEY },
})
try {
  await sandbox.commands.run(
    'openclaw agent exec "Write fizzbuzz.js, run it with node, and show the output" ' +
      '--model novita/deepseek/deepseek-v4-pro --cwd /home/user',
    { onStdout: (d) => process.stdout.write(d), timeoutMs: 0 }
  )
} finally {
  await sandbox.kill()
}
```

> [!NOTE]
>
> **`agent exec`** runs with the full execution policy a headless turn needs, scoped to `--cwd`: the agent can edit files and run commands there without asking. That is safe here because everything happens inside a disposable sandbox. It exits `0` on success, `1` on a model or result error, and `2` on timeout.

## How it works

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

### Execute generated code

The agent writes code and runs it in the sandbox's shell. Add `--json` to get a stable JSON envelope with the final text and run metadata instead of plain output.

```python Python icon="python" theme={"system"}
import json

result = sandbox.commands.run(
    'openclaw agent exec "Create server.js with a /health route using Node\'s http module, start it, and test it with curl" '
    "--model novita/deepseek/deepseek-v4-pro --cwd /home/user --json",
    timeout=0,
)
print(json.dumps(json.loads(result.stdout), indent=2))
```

```js JavaScript & TypeScript icon="js" theme={"system"}
const result = await sandbox.commands.run(
  'openclaw agent exec "Create server.js with a /health route using Node\'s http module, start it, and test it with curl" ' +
    '--model novita/deepseek/deepseek-v4-pro --cwd /home/user --json',
  { timeoutMs: 0 }
)
console.log(JSON.stringify(JSON.parse(result.stdout), null, 2))
```

### Read and write files

Write long instructions and inputs to files, point the agent at them with `--message-file`, and read the results afterwards. For whole repositories, use [`sandbox.git.clone`](https://docs.novita.ai/guides/sandbox-git-integration).

```python Python icon="python" theme={"system"}
sandbox.files.write("/home/user/data/sales.csv", open("sales.csv").read())
sandbox.files.write("/home/user/task.md", "Summarize data/sales.csv by region into report.md.")

sandbox.commands.run(
    "openclaw agent exec --message-file task.md --model novita/deepseek/deepseek-v4-pro --cwd /home/user",
    cwd="/home/user",
    timeout=0,
)
print(sandbox.files.read("/home/user/report.md"))
```

```js JavaScript & TypeScript icon="js" theme={"system"}
import { readFile } from 'node:fs/promises'

await sandbox.files.write('/home/user/data/sales.csv', await readFile('sales.csv', 'utf8'))
await sandbox.files.write('/home/user/task.md', 'Summarize data/sales.csv by region into report.md.')

await sandbox.commands.run(
  'openclaw agent exec --message-file task.md --model novita/deepseek/deepseek-v4-pro --cwd /home/user',
  { 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.

```python Python icon="python" theme={"system"}
sandbox.commands.run("npm init -y && npm install --save-dev jest", cwd="/home/user", timeout=300)
sandbox.commands.run(
    'openclaw agent exec "Add Jest unit tests for server.js" --model novita/deepseek/deepseek-v4-pro --cwd /home/user',
    timeout=0,
)

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

```js JavaScript & TypeScript icon="js" theme={"system"}
await sandbox.commands.run('npm init -y && npm install --save-dev jest', { cwd: '/home/user', timeoutMs: 300_000 })
await sandbox.commands.run(
  'openclaw agent exec "Add Jest unit tests for server.js" --model novita/deepseek/deepseek-v4-pro --cwd /home/user',
  { timeoutMs: 0 }
)

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

> [!TIP]
>
> A command that exits non-zero raises `CommandExitException` (Python) or `CommandExitError` (JavaScript). Catch it when a failing run is an expected outcome.

## Use Novita models

The Novita provider is already installed in the template, so switching models is a one-line change to `--model`. Use `novita/<model ID>` with any model from the [Novita model library](https://novita.ai/models), for example:

```bash theme={"system"}
openclaw agent exec "..." --model novita/moonshotai/kimi-k3
```

The plugin's starting catalog includes `novita/moonshotai/kimi-k3`, `novita/moonshotai/kimi-k2.7-code`, `novita/minimax/minimax-m3`, `novita/zai-org/glm-5.2`, `novita/deepseek/deepseek-v4-pro`, and `novita/qwen/qwen3.7-max`. Run `openclaw models list --provider novita` inside the sandbox to see what your account can use. Add `--fallback <provider/model>` (repeatable) for an ordered fallback chain. Model usage is billed separately from sandbox runtime, at the model's own per-token rate.

## Always-on OpenClaw with NovitaClaw

`agent exec` is one task per call. If you want a long-lived OpenClaw assistant you chat with — through a Web UI, Telegram, or Slack — use [NovitaClaw](https://docs.novita.ai/guides/novitaclaw.md). It creates the sandbox, configures OpenClaw with Novita models, and starts the Gateway for you:

```bash theme={"system"}
pip install novitaclaw
export NOVITA_API_KEY=sk_your_api_key
novitaclaw launch
```

The command returns a Web UI URL, a Gateway WebSocket URL and token, a Web Terminal, and a File Manager. Manage the instance with [NovitaClaw commands](https://docs.novita.ai/guides/novitaclaw-commands.md) and tune it with [NovitaClaw configuration](https://docs.novita.ai/guides/novitaclaw-configuration.md).

## Production tips

* **Timeouts** — two clocks apply. `agent exec` stops each model attempt after 600 seconds by default; change it with `--timeout <seconds>` (`0` disables it). The sandbox's `timeout` (seconds; `timeoutMs` in JavaScript) is its maximum lifetime — extend it while the agent works with [`set_timeout`](https://docs.novita.ai/guides/sandbox-timeout-handle). Pass `timeout=0` to `commands.run` so the SDK doesn't cut off a long agent turn.
* **Pause and resume** — for multi-step jobs, [pause](https://docs.novita.ai/guides/sandbox-pause-resume.md) the sandbox between steps instead of killing it. Files and installed packages survive, and CPU and RAM billing stops while it is paused. Each `agent exec` call is a new one-shot turn; to keep its transcripts and run state for inspection, pass an existing directory with `--state-dir`.
* **Concurrency** — each sandbox is isolated, so you can run one OpenClaw task per sandbox in parallel. Concurrent sandboxes are capped by your account tier (5 on Free, 100 on Paid); see [Quota Limits](https://docs.novita.ai/guides/sandbox-quota-limit.md).
* **Cost** — sandboxes are billed per second while running. A 2 vCPU / 4 GiB sandbox costs about \$0.0000324/s, so a 10-minute task is roughly **\$0.019** in sandbox time, plus model tokens. See [Pricing](https://docs.novita.ai/guides/sandbox-pricing.md).
* **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

> [accordion] 402: insufficient balance when creating a sandbox
>
> Your account balance can't cover a new sandbox. Top up on the [Billing](https://novita.ai/billing) page or claim the new-user credits described in [Pricing](https://docs.novita.ai/guides/sandbox-pricing.md), then retry.

> [accordion] Unknown provider or model: novita/...
>
> The Novita provider plugin isn't installed for the sandbox user, or the model ID is wrong. Check with `openclaw plugins inspect novita` and `openclaw models list --provider novita` inside the sandbox. If the plugin is missing, rebuild the template and keep `set_user("user")` before the `plugins install` step so the plugin lands in `/home/user/.openclaw`, the same user the sandbox runs commands as.

> [accordion] agent exec exits with code 2
>
> Exit code `2` means the run hit its deadline. Raise `--timeout`, split the task into smaller steps, and make sure the sandbox `timeout` is longer than the agent run.

## Next steps

> [card] [NovitaClaw](https://docs.novita.ai/guides/novitaclaw.md)
>
> One-command, always-on OpenClaw on Novita Sandbox.

> [card] [Sandbox SDK reference](https://docs.novita.ai/guides/sandbox-create.md)
>
> Every option for creating and managing sandboxes.

> [card] [Sandbox cookbook](https://github.com/novitalabs/sandbox-cookbook)
>
> Runnable Novita Sandbox examples on GitHub.

> [card] [More agent integrations](https://docs.novita.ai/guides/sandbox-opencode.md)
>
> Run OpenCode, Claude Code, or Codex in a sandbox.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.