Novita Sandbox offers isolated, stateful execution environments designed for AI agents. It enables running code, installing dependencies, accessing files, using browsers, and preserving state across sessions without infrastructure management.
The platform is built on the following core concepts:
Core Concepts
Sandbox
An isolated execution environment where agents perform tasks. Each has its own filesystem and runtime, allowing agents to run commands, manage files, install dependencies, and handle browser-based workflows.Lifecycle
- Running — the sandbox is active and can execute commands and serve connections.
- Paused — the sandbox is suspended; its filesystem and memory state are preserved and billing for compute stops. It can be resumed back to Running (typically in about a second).
- Killed — the sandbox is terminated and its resources are released. A killed sandbox cannot be resumed.
- Timeout — the maximum lifetime of the sandbox. It counts down from creation regardless of activity; when it expires the sandbox is stopped by default, or paused if you configure the lifecycle accordingly. See Timeout Handle.
- Idle timeout — fires only when no client has been connected for the configured duration, automatically killing or pausing the sandbox. See Idle Timeout Handle.
Template
Defines the starting environment for a Sandbox. Templates ensure consistency across multiple Sandboxes with predefined dependencies, configuration, and setup steps.Snapshot
A Snapshot saves the current state of a Sandbox as a reusable environment. Snapshots are useful after you have configured a Sandbox, installed dependencies, or generated files that you want to reuse. New Sandboxes can be created from a Snapshot without repeating the same setup steps.Secret
Secrets are a secure way to store and use sensitive values — such as API keys, tokens, and passwords — inside a Novita Sandbox. They are encrypted and managed within the scope of the current team, letting code running in a sandbox authenticate to external services without hardcoding credentials in source code, snapshots, templates, or sandbox environment variables.Regions
Novita Sandbox currently provides access through the following regions:
The v2 region (us-phx-1) is the default used by the current SDK and CLI. It adds capabilities such as Secrets and Snapshots on top of v1 and provides a more complete feature set, so it is recommended to use v2 first.
The SDK and CLI documented here are compatible with both v1 and v2 regions. To use the v1 legacy region instead, configure the environment variable
NOVITA_DOMAIN:
When to use Novita Sandbox
Intended for workloads requiring isolated environments to execute tasks, maintain state, or reuse prepared setups. Common use cases include:- Coding agents that run code, install packages, and execute tests
- Browser agents that automate web workflows
- Data analysis agents that process files and generate reports
- Research or RL workloads that need many isolated environments