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

# Novita Sandbox Overview

> Isolated cloud sandboxes for AI agents: lifecycle, timeouts, commands, files, templates, secrets, snapshots, networking, regions, pricing, and limits.

Novita Sandbox is a managed, isolated cloud execution environment for AI agents. Use it to run code and shell commands, install dependencies, manage files, automate browsers, and preserve filesystem and memory state across sessions without managing infrastructure. It fits coding agents that run tests, browser agents that complete web tasks, data analysis agents that process files, and research or reinforcement learning workflows that need multiple isolated environments. For product features, use cases, and pricing, see the [Novita Agent Sandbox](https://novita.ai/sandbox) page.

Every example on this page uses the `novita-sandbox` SDK ([installation](https://docs.novita.ai/guides/sandbox-installation.md)) and reads your API key from `NOVITA_API_KEY`:

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

novita = Novita()
```

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

const novita = new Novita()
```

## Capabilities

### Configuration

A sandbox is an isolated Linux environment with its own filesystem, processes, and network. You create one from a [template](#templates-and-custom-images) and can set its lifetime, environment variables, and metadata for filtering. CPU and memory come from the template.

```python Python icon="python" theme={"system"}
sandbox = novita.sandbox.create(
    "base",
    timeout=300,               # seconds
    envs={"LOG_LEVEL": "debug"},
    metadata={"user_id": "u-123"},
)
print(sandbox.sandbox_id)
```

```js JavaScript & TypeScript icon="js" theme={"system"}
const sandbox = await novita.sandbox.create('base', {
  timeoutMs: 300_000, // milliseconds
  envs: { LOG_LEVEL: 'debug' },
  metadata: { user_id: 'u-123' },
})
console.log(sandbox.sandboxId)
```

Learn more: [Create a sandbox](https://docs.novita.ai/guides/sandbox-create.md) · [List sandboxes](https://docs.novita.ai/guides/sandbox-list.md)

### Lifecycle

![Sandbox lifecycle: transitions between running, paused, and killed](https://mintcdn.com/novitaai/hZqyJG6PLY7-jrrZ/images/sandbox/sandbox-lifecycle.png?fit=max\&auto=format\&n=hZqyJG6PLY7-jrrZ\&q=85\&s=8b59e3060ddaa2eae6467a8028f010f5)

A sandbox is **Running**, **Paused**, or **Killed**. Pausing preserves the filesystem and memory — including running processes — and stops CPU and RAM billing; resuming typically takes about a second. A killed sandbox releases its resources and cannot be resumed.

```python Python icon="python" theme={"system"}
sandbox.pause()
sandbox = novita.sandbox.connect(sandbox.sandbox_id)  # resumes a paused sandbox
sandbox.kill()
```

```js JavaScript & TypeScript icon="js" theme={"system"}
await sandbox.pause()
const resumed = await novita.sandbox.connect(sandbox.sandboxId) // resumes a paused sandbox
await resumed.kill()
```

Learn more: [Pause and resume](https://docs.novita.ai/guides/sandbox-pause-resume.md) · [Connect](https://docs.novita.ai/guides/sandbox-connect.md) · [Kill](https://docs.novita.ai/guides/sandbox-kill.md)

### Timeouts

The **timeout** is a sandbox's maximum lifetime (5 minutes by default), counted from creation regardless of activity, while the **idle timeout** fires only when no client has been connected for the configured duration. Either one kills the sandbox by default; to pause instead, set `lifecycle.on_timeout` to `pause` (optionally with auto-resume) for the timeout, or `auto_pause` for the idle timeout.

```python Python icon="python" theme={"system"}
sandbox = novita.sandbox.create(
    timeout=10 * 60,
    lifecycle={"on_timeout": "pause", "auto_resume": True},
)
sandbox.set_timeout(30 * 60)  # extend while work is in progress
```

```js JavaScript & TypeScript icon="js" theme={"system"}
const sandbox = await novita.sandbox.create({
  timeoutMs: 10 * 60 * 1000,
  lifecycle: { onTimeout: 'pause', autoResume: true },
})
await sandbox.setTimeout(30 * 60 * 1000) // extend while work is in progress
```

Learn more: [Timeout handling](https://docs.novita.ai/guides/sandbox-timeout-handle.md) · [Idle timeout](https://docs.novita.ai/guides/sandbox-idle-timeout.md) · [Long-running sandboxes](https://docs.novita.ai/guides/sandbox-long-running.md)

### Commands

Run any shell command and get its stdout, stderr, and exit code back, stream output as it is produced, or start long-lived processes such as servers in the background. Pass `cwd`, `envs`, or `user` to control where and how a command runs.

```python Python icon="python" theme={"system"}
result = sandbox.commands.run("python3 --version")
print(result.stdout, result.exit_code)

sandbox.commands.run("for i in 1 2 3; do echo line $i; sleep 1; done", on_stdout=lambda d: print(d, end=""))
sandbox.commands.run("python3 -m http.server 3000", background=True)
```

```js JavaScript & TypeScript icon="js" theme={"system"}
const result = await sandbox.commands.run('python3 --version')
console.log(result.stdout, result.exitCode)

await sandbox.commands.run('for i in 1 2 3; do echo line $i; sleep 1; done', { onStdout: (d) => process.stdout.write(d) })
await sandbox.commands.run('python3 -m http.server 3000', { background: true })
```

Learn more: [Run commands](https://docs.novita.ai/guides/sandbox-run-command.md) · [Interactive terminal](https://docs.novita.ai/guides/sandbox-interactive-terminal.md)

### Filesystem

Each sandbox has 20 GB of disk. Read and write files, upload and download them, inspect metadata, and watch directories for changes.

```python Python icon="python" theme={"system"}
sandbox.files.write("/home/user/data.csv", "id,value\n1,42\n")
print(sandbox.files.read("/home/user/data.csv"))
```

```js JavaScript & TypeScript icon="js" theme={"system"}
await sandbox.files.write('/home/user/data.csv', 'id,value\n1,42\n')
console.log(await sandbox.files.read('/home/user/data.csv'))
```

Learn more: [Filesystem](https://docs.novita.ai/guides/sandbox-filesystem.md) · [Read and write](https://docs.novita.ai/guides/sandbox-filesystem-read-write.md) · [Upload](https://docs.novita.ai/guides/sandbox-filesystem-upload.md) · [Download](https://docs.novita.ai/guides/sandbox-filesystem-download.md) · [Watch](https://docs.novita.ai/guides/sandbox-filesystem-watch.md)

### Templates and custom images

A template defines a sandbox's starting environment — base image, packages, files, and CPU and memory — so every sandbox starts identical and fast. Build one from a base image, a Dockerfile, or a private registry image, then create sandboxes from it by name or ID.

```python Python icon="python" theme={"system"}
template = novita.template.new().from_python_image("3.12").pip_install(["pandas", "requests"])
build = novita.template.build(template, "my-data-agent", cpu_count=2, memory_mb=2048)

sandbox = novita.sandbox.create(build.template_id)
```

```js JavaScript & TypeScript icon="js" theme={"system"}
const template = novita.template.new().fromPythonImage('3.12').pipInstall(['pandas', 'requests'])
const build = await novita.template.build(template, 'my-data-agent', { cpuCount: 2, memoryMB: 2048 })

const sandbox = await novita.sandbox.create(build.templateId)
```

Learn more: [Build templates](https://docs.novita.ai/guides/sandbox-template-build-operations.md) · [Template authoring](https://docs.novita.ai/guides/sandbox-template-authoring.md) · [Template examples](https://docs.novita.ai/guides/sandbox-template-examples.md)

### Environment variables

Set environment variables for the whole sandbox when you create it, or for a single command. Per-command values override sandbox-wide ones for that command only.

```python Python icon="python" theme={"system"}
sandbox = novita.sandbox.create("base", envs={"LOG_LEVEL": "debug"})
result = sandbox.commands.run("echo $LOG_LEVEL", envs={"LOG_LEVEL": "info"})  # prints "info"
```

```js JavaScript & TypeScript icon="js" theme={"system"}
const sandbox = await novita.sandbox.create('base', { envs: { LOG_LEVEL: 'debug' } })
const result = await sandbox.commands.run('echo $LOG_LEVEL', { envs: { LOG_LEVEL: 'info' } }) // prints "info"
```

Learn more: [Create a sandbox](https://docs.novita.ai/guides/sandbox-create.md) · [Run commands](https://docs.novita.ai/guides/sandbox-run-command.md)

### Secrets

Secrets store API keys, tokens, and passwords encrypted at the team level. Code in the sandbox only ever sees a placeholder; the real value is injected into HTTPS request headers sent to the hosts you allow, so credentials never appear in your code, templates, snapshots, or environment.

```python Python icon="python" theme={"system"}
novita.secret.create(name="openai-key", value="sk-...", hosts=["api.openai.com"])
sandbox = novita.sandbox.create(secret_envs={"OPENAI_API_KEY": "openai-key"})
```

```js JavaScript & TypeScript icon="js" theme={"system"}
await novita.secret.create({ name: 'openai-key', value: 'sk-...', hosts: ['api.openai.com'] })
const sandbox = await novita.sandbox.create({ secretEnvs: { OPENAI_API_KEY: 'openai-key' } })
```

Learn more: [Secrets](https://docs.novita.ai/guides/sandbox-secret.md) · [Use secrets in a sandbox](https://docs.novita.ai/guides/sandbox-secret-sandbox-use.md)

### Snapshots

A snapshot saves a sandbox's current state — installed dependencies, generated files, configuration — as a reusable starting point. New sandboxes created from it skip the setup, and the snapshot persists after the original sandbox is deleted.

```python Python icon="python" theme={"system"}
sandbox.commands.run("pip install requests")
snapshot = sandbox.create_snapshot()

new_sandbox = novita.sandbox.create(snapshot.snapshot_id)
```

```js JavaScript & TypeScript icon="js" theme={"system"}
await sandbox.commands.run('pip install requests')
const snapshot = await sandbox.createSnapshot()

const newSandbox = await novita.sandbox.create(snapshot.snapshotId)
```

Learn more: [Snapshots](https://docs.novita.ai/guides/sandbox-snapshot.md) · [Create a snapshot](https://docs.novita.ai/guides/sandbox-snapshot-create.md) · [Start from a snapshot](https://docs.novita.ai/guides/sandbox-snapshot-sandbox-use.md)

### Networking and ports

Sandboxes have internet access by default. Expose any port as a public HTTPS URL, turn outbound access off, or restrict it to an allowlist of domains and CIDRs.

```python Python icon="python" theme={"system"}
sandbox.commands.run("python3 -m http.server 3000", background=True)
print(f"https://{sandbox.get_host(3000)}")

locked = novita.sandbox.create(network={"allow_out": ["api.example.com"], "deny_out": ["0.0.0.0/0"]})
```

```js JavaScript & TypeScript icon="js" theme={"system"}
await sandbox.commands.run('python3 -m http.server 3000', { background: true })
console.log(`https://${sandbox.getHost(3000)}`)

const locked = await novita.sandbox.create({ network: { allowOut: ['api.example.com'], denyOut: ['0.0.0.0/0'] } })
```

Learn more: [Internet access](https://docs.novita.ai/guides/sandbox-internet-access.md) · [Secured access](https://docs.novita.ai/guides/sandbox-secured-access.md) · [SSH access](https://docs.novita.ai/guides/sandbox-ssh-access.md)

### Regions

Novita Sandbox currently provides access through the following regions:

| Name | Version | Domain | Description |
| - | - | - | - |
| us-phx-1 | v2 | `us-phx-1.sandbox.novita.ai` | Default region (used by the current SDK / CLI) |
| us-virginia-1 | v1 | `sandbox.novita.ai` | Specified via environment variable |

The **v2** region (us-phx-1) is the default used by the current SDK and CLI. It adds Secrets and Snapshots on top of v1 and is the recommended choice. To use the **v1** legacy region instead, set `NOVITA_DOMAIN`:

```bash theme={"system"}
export NOVITA_DOMAIN=sandbox.novita.ai
```

Learn more: [Which regions does Novita Sandbox run in?](https://docs.novita.ai/guides/sandbox-faq-regions.md)

## Pricing

Sandboxes are billed **per second** for CPU and RAM while running, and stop accruing CPU and RAM charges when paused or killed. Templates, snapshots, and paused sandboxes are kept in persistent storage, with 60 GB free per account.

| Resource | Price |
| - | - |
| CPU | \$0.0000098 per vCPU per second |
| RAM | \$0.0000032 per GiB per second |
| Disk while running | Free (20 GB per sandbox) |
| Persistent storage | 60 GB free, then \$0.00009/GB/h |

**Example:** a coding agent runs for 10 minutes in a 2 vCPU / 2 GiB sandbox.

```text theme={"system"}
CPU  2 × $0.0000098 × 600 s = $0.01176
RAM  2 × $0.0000032 × 600 s = $0.00384
Total                         ≈ $0.0156
```

Running the same sandbox for a full hour costs about \$0.094. New users can claim \$100 in promotional credits ([free tier](https://docs.novita.ai/guides/sandbox-faq-free-tier.md)). See [Pricing](https://docs.novita.ai/guides/sandbox-pricing.md) for details and the [pricing page](https://novita.ai/pricing?sandbox=1) for current rates.

## Limits

Default quotas depend on your account tier:

| Limit | Free | Paid | Enterprise |
| - | - | - | - |
| Concurrent sandboxes | 5 | 100 | 500, adjustable |
| Maximum session duration (without long-running mode) | 1 hour | 3 hours | 4 hours, adjustable |
| Maximum vCPU per sandbox | 2 | 8 | 8, adjustable |
| Maximum memory per sandbox | 4 GiB | 8 GiB | 8 GiB, adjustable |
| Disk per sandbox | 20 GB | 20 GB | 20 GB, adjustable |

Memory is set in 512 MiB increments, at 0.5–4 GiB per vCPU. See [Quota Limits](https://docs.novita.ai/guides/sandbox-quota-limit.md) for the full rules, [long-running sandboxes](https://docs.novita.ai/guides/sandbox-long-running.md) for sessions beyond your tier's cap, and the FAQ on [raising concurrency](https://docs.novita.ai/guides/sandbox-faq-concurrency-limit.md) and [how long a sandbox can run](https://docs.novita.ai/guides/sandbox-faq-max-runtime.md).

## Next steps

> [card] [Quickstart](https://docs.novita.ai/guides/sandbox-your-first-agent-sandbox.md)
>
> Create your first sandbox and run code in it.

> [card] [Install the SDK and CLI](https://docs.novita.ai/guides/sandbox-installation.md)
>
> Python, JavaScript, and command-line setup.

> [card] [Claude Code Sandbox](https://docs.novita.ai/guides/sandbox-claude-code.md)
>
> Run Anthropic's coding agent headless in a sandbox.

> [card] [Codex Sandbox](https://docs.novita.ai/guides/sandbox-codex.md)
>
> Run OpenAI Codex on a cloned repo in a sandbox.

> [card] [OpenCode Sandbox](https://docs.novita.ai/guides/sandbox-opencode.md)
>
> Run OpenCode on Novita models in a sandbox.

> [card] [OpenClaw Sandbox](https://docs.novita.ai/guides/sandbox-openclaw.md)
>
> Run OpenClaw agents programmatically in a sandbox.

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


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