Novita Sandbox

Novita Agent Sandbox CLI

novita-sandbox-cli wraps the Novita Agent Sandbox platform. Use it to build templates from Dockerfiles, manage sandbox lifecycles, and deploy agents.

---

Installation

If this skill is not yet installed locally, [AGENT] follow these steps to install it.

Detect agent platform

# Claude Code
if [ -d "$HOME/.claude/skills" ]; then
  echo "CLAUDE_CODE"
# Gemini CLI
elif [ -d "$HOME/.gemini/skills" ]; then
  echo "GEMINI_CLI"
# OpenClaw
elif command -v openclaw >/dev/null 2>&1; then
  echo "OPENCLAW"
else
  echo "UNKNOWN"
fi

Install by platform

Claude Code:

SKILL_DIR="$HOME/.claude/skills/novita-sandbox"
mkdir -p "$SKILL_DIR/references"
curl -sL "https://raw.githubusercontent.com/novitalabs/novita-skills/main/skills/novita-sandbox/SKILL.md" \
  -o "$SKILL_DIR/SKILL.md"
curl -sL "https://raw.githubusercontent.com/novitalabs/novita-skills/main/skills/novita-sandbox/references/cli-reference.md" \
  -o "$SKILL_DIR/references/cli-reference.md"
echo "Installed to $SKILL_DIR"

Gemini CLI:

SKILL_DIR="$HOME/.gemini/skills/novita-sandbox"
mkdir -p "$SKILL_DIR/references"
curl -sL "https://raw.githubusercontent.com/novitalabs/novita-skills/main/skills/novita-sandbox/SKILL.md" \
  -o "$SKILL_DIR/SKILL.md"
curl -sL "https://raw.githubusercontent.com/novitalabs/novita-skills/main/skills/novita-sandbox/references/cli-reference.md" \
  -o "$SKILL_DIR/references/cli-reference.md"
echo "Installed to $SKILL_DIR"

Other agents / manual install:

SKILL_DIR="<your-agent-skills-directory>/novita-sandbox"
mkdir -p "$SKILL_DIR/references"
curl -sL "https://raw.githubusercontent.com/novitalabs/novita-skills/main/skills/novita-sandbox/SKILL.md" \
  -o "$SKILL_DIR/SKILL.md"
curl -sL "https://raw.githubusercontent.com/novitalabs/novita-skills/main/skills/novita-sandbox/references/cli-reference.md" \
  -o "$SKILL_DIR/references/cli-reference.md"

Definition of Done (Installation)

Installation is NOT complete until all of the following are true:

1. SKILL.md is saved to the local skill directory 2. references/cli-reference.md is saved alongside it 3. The CLI is installed and up-to-date (Step 0 below passes) 4. Authentication is verified 5. [AGENT] sends the user a confirmation message:

✅ novita-sandbox skill installed.

What you can do now:
- "create a sandbox" — spin up a sandbox from a template
- "build a template" — build from Dockerfile
- "deploy an agent" — deploy and invoke agents
- "list sandboxes" — see running sandboxes

CLI version: <version>
Docs: https://novita.ai/docs/guides/sandbox-overview

---

Step 0: Ensure CLI is installed and up-to-date

Run this check every time the skill is triggered.

if ! command -v node >/dev/null 2>&1; then
  echo "NO_NODE"
elif ! command -v novita-sandbox-cli >/dev/null 2>&1; then
  echo "NOT_INSTALLED"
else
  _LOCAL=$(novita-sandbox-cli --version)
  _LATEST=$(npm view novita-sandbox-cli@beta version 2>/dev/null)
  if [ -n "$_LATEST" ] && [ "$_LOCAL" != "$_LATEST" ]; then
    echo "OUTDATED local=$_LOCAL latest=$_LATEST"
  else
    echo "OK $_LOCAL"
  fi
fi

Act on result:

• NO_NODE → Install Node.js first:
• macOS: brew install node
• Linux: curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs
• NOT_INSTALLED → npm install -g novita-sandbox-cli@beta
• OUTDATED → npm install -g novita-sandbox-cli@beta
• OK → Proceed.

After install or upgrade, verify authentication:

novita-sandbox-cli auth info 2>&1 || echo "NOT_LOGGED_IN"

If NOT_LOGGED_IN, run novita-sandbox-cli auth login (opens browser).

Set NOVITA_API_KEY environment variable for SDK usage.

Quick Reference

Command Overview

novita-sandbox-cli
├── auth          # login, logout, info, configure (switch team)
├── template      # build, list, init, delete, publish, unpublish, version
├── sandbox       # create, list, connect, kill, logs, metrics, clone, commit
└── agent         # configure, launch (deploy), invoke

Common Workflows

1. Build a Template from Dockerfile

# Initialize a starter Dockerfile
novita-sandbox-cli template init

# Build and push (auto-detects novita.Dockerfile)
novita-sandbox-cli template build -n my-template

# Rebuild an existing template
novita-sandbox-cli template build <template-id>

2. Create and Use a Sandbox

# Create sandbox without connecting terminal (for non-interactive / agent use)
novita-sandbox-cli sandbox create <template-id> --detach

# Create sandbox and connect interactive terminal (TTY required)
novita-sandbox-cli sandbox create <template-id>

# List running sandboxes
novita-sandbox-cli sandbox list

# Connect to an existing sandbox
novita-sandbox-cli sandbox connect <sandbox-id>

# View logs (streaming)
novita-sandbox-cli sandbox logs <sandbox-id> -f

# View metrics (CPU, memory, disk)
novita-sandbox-cli sandbox metrics <sandbox-id> -f

# Kill a sandbox
novita-sandbox-cli sandbox kill <sandbox-id>

# Kill all running sandboxes
novita-sandbox-cli sandbox kill --all

Important: When running inside an AI agent (Claude Code, Gemini CLI, etc.), always use --detach (-d) with sandbox create. These environments do not have a real TTY, so the interactive terminal will fail. Create with --detach, then use sandbox connect from a real terminal if needed.

3. Clone and Snapshot

# Clone a sandbox (create identical copies)
novita-sandbox-cli sandbox clone <sandbox-id> --count 3

# Commit sandbox state as a snapshot template
novita-sandbox-cli sandbox commit <sandbox-id> --alias my-snapshot

4. Deploy an Agent

# Configure agent project (creates Dockerfile + config)
novita-sandbox-cli agent configure -n my-agent -e app.py

# Deploy to Novita Sandbox
novita-sandbox-cli agent launch

# Invoke deployed agent (pass env vars the sandbox needs)
novita-sandbox-cli agent invoke '{"prompt": "hello"}' --stream --env NOVITA_API_KEY=$NOVITA_API_KEY

5. Template Management

# List templates
novita-sandbox-cli template list

# Publish (make public)
novita-sandbox-cli template publish <template-id>

# Unpublish (make private)
novita-sandbox-cli template unpublish <template-id>

# List versions and rollback
novita-sandbox-cli template version <template-id>
novita-sandbox-cli template version <template-id> --rollback <build-id>

# Delete
novita-sandbox-cli template delete <template-id>

Security

• API Key: Set NOVITA_API_KEY env var for SDK usage. When invoking agents, pass it explicitly with --env NOVITA_API_KEY=$NOVITA_API_KEY — sandbox environments do not inherit local env vars. Never commit it to git — use .env or your shell profile.
• Auth tokens: Stored locally by novita-sandbox-cli auth login. Run auth logout to revoke.
• Registry credentials: -u/-w flags in template build are for private Docker registries. Prefer env vars over CLI flags to avoid leaking secrets in shell history.

Understanding Output

Gotchas

• Template names: lowercase letters, numbers, dashes, and underscores only.
• --memory-mb must be an even number (default: 512).
• --cpu-count default is 2.
• sandbox create without --detach auto-connects a terminal session — use Ctrl+D or exit to detach.
• In non-TTY environments (AI agents, CI/CD), always use sandbox create --detach.
• agent invoke runs in a fresh sandbox — local environment variables are NOT available. Use --env KEY=VALUE to pass them explicitly.
• agent launch timeout defaults to 300s; increase with --timeout for large images.
• Config is stored in novita.toml in the project root after template build.

Troubleshooting

Full CLI Reference

For complete options on every command, see cli-reference.md.

If raw GitHub fetch is unavailable, fall back to local references/cli-reference.md in this skill.

---

Update

To update this skill to the latest version:

curl -sL "https://raw.githubusercontent.com/novitalabs/novita-skills/main/skills/novita-sandbox/SKILL.md" \
  -o "$(dirname "$0")/SKILL.md" 2>/dev/null || echo "Update manually from https://github.com/novitalabs/novita-skills"

Only update when the user explicitly requests it.

Novita Sandbox CLI — Full Command Reference

auth

auth login

Log in via browser OAuth. Stores credentials locally.

auth logout

Delete stored credentials.

auth info

Show current user email, team name, and team ID.

auth configure

Interactive prompt to switch between available teams.

---

template (alias: tpl)

template build [template-id] (alias: bd)

Build sandbox template from Dockerfile.

If [template-id] is provided, rebuilds that template. Otherwise creates a new one.

template list (alias: ls)

template init (alias: it)

Create starter novita.Dockerfile in current or specified directory.

template delete [template-id] (alias: dl)

template publish [template-id] (alias: pb)

Make template public. Same options as delete.

template unpublish [template-id] (alias: upb)

Make template private. Same options as delete.

template version [template-id] (alias: vn)

List all builds or rollback to a specific version.

---

sandbox (alias: sbx)

sandbox create [template-id] (alias: cr)

Create sandbox and connect terminal.

Uses novita.toml if template ID not specified.

sandbox list (alias: ls)

sandbox connect <sandboxID> (alias: cn)

sandbox kill [sandboxID] (alias: kl)

Mutually exclusive: specify sandbox ID or use --all.

sandbox logs <sandboxID> (alias: lg)

sandbox metrics <sandboxID> (alias: mt)

Reports CPU, memory, and disk usage.

sandbox clone <sandboxID> (alias: cl)

sandbox commit <sandboxID> (alias: cm)

Create snapshot template from current sandbox state.

---

agent

agent configure

Set up agent project configuration, creates Dockerfile and docker-ignore.

agent launch (alias: deploy)

Build and deploy agent to Novita Sandbox.

agent invoke <payload>

Invoke deployed agent with JSON payload or prompt text.

Agent Sandbox Guide

Novita Agent Sandbox is a secure, isolated cloud environment for executing AI-generated code.

Table of Contents

• Agent Sandbox Guide
• Table of Contents
• Features
• Use Cases
• Quick Start
• 1. Install SDK
• 2. Set API Key
• 3. Create and Run Sandbox
• Core Operations
• Run Code
• File Operations
• Background Commands
• Lifecycle Management
• Pause and Resume
• Clone
• Idle Timeout
• Templates
• Create Template
• Use Template
• CLI Usage
• Install CLI
• Commands
• Pricing
• Framework Integrations
• LangChain
• OpenAI Agents SDK
• E2B Compatibility
• Quota and Template Limits
• Resources

Features

• Secure: System-level isolation for safe code execution
• Fast: Startup latency depends on template, region, and workload
• Multi-language: Python, JavaScript, TypeScript, C++, and more
• Persistent: Pause/resume with state preserved
• Scalable: Supports large-scale concurrent sandboxes

Use Cases

• AI data analysis and visualization
• Code execution for AI agents
• Computer Use agents
• Safe code testing environment

---

Quick Start

1. Install SDK

JavaScript/TypeScript:

npm i novita-sandbox

Python:

pip install novita-sandbox

2. Set API Key

export NOVITA_API_KEY=sk_***

Or in .env file:

NOVITA_API_KEY=sk_***

3. Create and Run Sandbox

Python (original baseline):

# main.py
from dotenv import load_dotenv
from novita_sandbox.code_interpreter import Sandbox


# The .env file should be located in the project root directory
# dotenv will automatically look for .env in the current working directory
load_dotenv()

# Or
# You can set the environment variable in the command line
# export NOVITA_API_KEY=sk_***

sandbox = Sandbox.create()
execution = sandbox.run_code("print('hello world')")
print(execution.logs)

files = sandbox.files.list("/")
print(files)

# Close sandbox when no longer needed
sandbox.kill()

For JavaScript/TypeScript, generate equivalent code from this Python baseline.

---

Core Operations

For JavaScript snippets below, run in an async context (top-level await in ESM, or wrap in async function main()).

Run Code

// JavaScript
const result = await sandbox.runCode(`
import pandas as pd
df = pd.DataFrame({'a': [1, 2, 3]})
print(df.describe())
`);
console.log(result.logs);

File Operations

// Write file
await sandbox.files.write('/tmp/data.txt', 'Hello World');

// Read file
const content = await sandbox.files.read('/tmp/data.txt');

// List directory
const files = await sandbox.files.list('/tmp');

// Upload file
await sandbox.files.upload('/local/file.txt', '/sandbox/file.txt');

// Download file
await sandbox.files.download('/sandbox/output.txt', '/local/output.txt');

Background Commands

// Run command in background
const proc = await sandbox.commands.run('python long_task.py', {
  background: true
});

// Check status later
const status = await proc.status();

// Get output
const output = await proc.output();

---

Lifecycle Management

Pause and Resume

// Pause sandbox (preserves state)
await sandbox.pause();

// Resume later
const resumed = await Sandbox.resume(sandbox.id);

Clone

// Clone a sandbox
const clone = await sandbox.clone();

Idle Timeout

Sandboxes auto-pause after idle timeout (current default can change by product policy and configuration).

// Keep alive for long-running tasks
const sandbox = await Sandbox.create({
  keepAlive: true,
  timeout: 3600  // 1 hour
});

---

Templates

Create reusable sandbox configurations with pre-installed packages.

Create Template

// Create sandbox and install packages
const sandbox = await Sandbox.create();
await sandbox.runCode('pip install pandas numpy matplotlib');

// Save as template
const template = await sandbox.saveAsTemplate('data-science');

Use Template

// Create sandbox from template
const sandbox = await Sandbox.create({
  template: 'data-science'
});

---

CLI Usage

Install CLI

npm i -g novita-sandbox-cli

Commands

Run these commands in order:

novita-sandbox auth login

novita-sandbox spawn

novita-sandbox list

novita-sandbox shutdown <sandbox-id>

---

Pricing

• CPU: Per-second billing
• RAM: Per-second billing
• Storage: Daily charges (templates, snapshots)

See https://novita.ai/docs/guides/sandbox-pricing for details.

---

Framework Integrations

LangChain

from langchain_community.tools import NovitaSandboxTool

tool = NovitaSandboxTool()
result = tool.run("print('Hello from LangChain')")

OpenAI Agents SDK

from agents import Agent
from novita_sandbox import Sandbox

sandbox = Sandbox()
agent = Agent(tools=[sandbox.as_tool()])

---

E2B Compatibility

Use this only when users are migrating existing E2B workflows to Novita Sandbox.

• Compatibility domain: E2B_DOMAIN=sandbox.novita.ai
• Auth variable: E2B_API_KEY=<NOVITA_API_KEY>
• Recommended for full feature access: Novita Sandbox SDK

Minimal E2B Python example:

from e2b_code_interpreter import Sandbox

sbx = Sandbox.create()
execution = sbx.commands.run("ls -l")
print(execution)
sbx.kill()

E2B CLI flow:

e2b auth login
e2b sandbox spawn <template-id>
e2b sandbox list
e2b sandbox kill <sandbox-id>

---

Quota and Template Limits

Current policy highlights (verify live before answering):

• Concurrent sandbox quota can be limited by account plan (source material baseline mentions 100).
• Template CPU range: 1-8 vCPU (integer values).
• Template memory maximum: 8192 MiB, in 512 MiB steps.
• CPU:Memory ratio rules:
• Minimum: 1:0.5
• Maximum: 1:4
• Template constraints apply when creating templates and are inherited by sandboxes launched from those templates.

If users need exact current limits or higher quota, route to official docs/support before giving hard numbers.

---

Resources

• Console: https://novita.ai/sandbox/console
• Full Docs: https://novita.ai/docs/guides/sandbox-overview
• SDK Reference: https://novita.ai/docs/guides/sandbox-sdk-and-cli
• E2B Compatibility Docs: https://novita.ai/docs/guides/sandbox-integrations-e2b-compatible
• Template Docs: https://novita.ai/docs/guides/sandbox-template
• Docs Index: https://novita.ai/docs/llms.txt

Last verified: 2026-02-09