SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsnovita-sandbox

novita-sandbox

Agents & models

View repository

Updated 10-16 02:33

About this skill

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

Key Value
CLI name novita-sandbox-cli
Docs https://novita.ai/docs/guides/sandbox-overview
Console https://novita.ai/console
NPM https://www.npmjs.com/package/novita-sandbox-cli

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

Command Output Key fields
template build Build progress → template ID Template ID (use for sandbox create)
template list Table of templates ID, Name, Status, Type
sandbox create Sandbox ID (with --detach) or interactive terminal Sandbox ID (use for connect/kill/logs)
sandbox list Table of running sandboxes ID, Template, State, Created
sandbox logs Streaming log lines Timestamp, level, message
sandbox metrics CPU/memory/disk stats Percentage and absolute values
sandbox clone List of new sandbox IDs One ID per clone
sandbox commit New snapshot template ID Template ID (reusable like build templates)
agent launch Build progress → deployment URL Agent ID (agent_name-template_id)
agent invoke Agent response (JSON or stream) Depends on agent implementation

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

Error Cause Fix
Error: not logged in No auth token Run novita-sandbox-cli auth login
Error: template not found Wrong ID or deleted Run template list to verify; check --team flag
Error: sandbox not found Sandbox killed or expired Run sandbox list to check; sandboxes auto-expire after timeout
setRawMode is not a function Running sandbox create without --detach in a non-TTY environment Use sandbox create <template-id> --detach
EACCES on npm install -g No global npm permission Use sudo npm install -g or fix npm prefix (npm config set prefix ~/.npm-global)
Build timeout Large image or slow network Increase --timeout; use --no-cache to skip stale layers
--memory-mb validation error Odd number provided Use an even number (e.g., 512, 1024, 2048)
connect hangs Sandbox still starting Wait for readiness; check sandbox logs for startup errors
agent invoke returns 404 Agent not deployed or wrong ID Verify with agent launch --dry-run; check agent ID format: name-templateId

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.