Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Novita Agent Sandbox SDK for Python

A Python SDK for Novita Agent Sandbox environments that provides code execution, desktop automation, and cloud computing capabilities..

📖 Documentation • 🔑 Get API Key

Features

  • Code Interpreter: Execute Python, JavaScript, and other languages in isolated environments
  • Desktop Automation: Control desktop applications and GUI interactions
  • Cloud Computing: Scalable sandbox environments for various computing tasks
  • Data Visualization: Built-in charting and visualization capabilities
  • File System Operations: Complete file system management and monitoring

Installation

pip install novita-sandbox
pip install novita-sandbox[runtime]
pip install novita-sandbox[code-interpreter]
pip install novita-sandbox[desktop]
pip install novita-sandbox[all]

runtime is for users who only need Agent Runtime-related features; all includes every optional dependency.

Quick Start

Authentication

Get your Novita API key from the key management page.

Core Sandbox

Use the high-level Novita client to share one set of credentials across namespaces.

import os
from novita_sandbox import Novita

novita = Novita(api_key=os.getenv("NOVITA_API_KEY", ""))

# Using the official template `base` by default
sandbox = novita.sandbox.create("base")

# File operations
sandbox.files.write('/tmp/test.txt', 'Hello, World!')
content = sandbox.files.read('/tmp/test.txt')

# Command execution
result = sandbox.commands.run('ls -la /tmp')
print(result.stdout)

sandbox.kill()

Code Interpreter

The Code Interpreter sandbox is available through the same client.

import os
from novita_sandbox import Novita

novita = Novita(api_key=os.getenv("NOVITA_API_KEY", ""))

sandbox = novita.code_interpreter.create()

# Execute Python code
result = sandbox.run_code('print("Hello, World!")')
print(result.logs)

sandbox.kill()

Desktop Automation

The Desktop sandbox is available through the same client.

import os
from novita_sandbox import Novita

novita = Novita(api_key=os.getenv("NOVITA_API_KEY", ""))

desktop = novita.desktop.create()

# Take a screenshot
screenshot = desktop.screenshot()

# Automate mouse and keyboard
desktop.left_click(100, 200)
desktop.press('Return')
desktop.write('Hello, World!')

desktop.kill()

Documentation

For comprehensive guides, API references, and examples, visit our official documentation.

Development

Install

poetry install --with dev --extras "all" 

Test

make test
make test-core
make test-code-interpreter
make test-desktop

Template environment scope

set_envs({...}) adds build-only variables. Use set_envs({...}, runtime=True) when the resolved values must also be available in the sandbox. Dockerfile ENV is persisted at runtime; Dockerfile ARG remains build-only. Declaration order is preserved, and values in one declaration group read the preceding environment. Image ENV values are literals; inherited WORKDIR applies before caller steps.

template = Template().from_image("python:3.12-slim")
template.set_envs({"BUILD_MODE": "release"})
template.set_envs({"PATH": "/app/bin:$PATH", "APP_MODE": "worker"}, runtime=True)

Mutable image tags are refreshed for each serialization/build. Only successful digest-pinned registry reads are cached; failed reads can be retried on the same builder. Explicit caller commands and settings take precedence over image defaults.

Job.wait(..., timeout=...) and AsyncJob.wait check the remaining budget before polling and before accepting completion. The remaining budget caps request timeouts; async waits also bound the overall request await. Synchronous HTTP transport timeouts apply per phase, so they cannot forcibly interrupt every blocking operation at an exact wall-clock deadline.

Sandbox security options

The SDK sends secure and public traffic settings only when explicitly supplied. Omitting these options leaves the backend defaults or existing sandbox settings in effect. The returned traffic access token is available on the sandbox instance and is refreshed by instance connect/reset when the backend returns a token. Send it in the Sandbox-Traffic-Access-Token header when accessing a custom port.

Metadata

Release files for novita-sandbox 2.1.4a4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for novita-sandbox 2.1.4a4
File Size Uploaded Provenance Actions
novita_sandbox-2.1.4a4.tar.gz 586.8 kB Without provenance Details for novita_sandbox-2.1.4a4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for novita-sandbox 2.1.4a4
File Interpreter ABI Platform Actions
novita_sandbox-2.1.4a4-py3-none-any.whl Python 3 none any Details for novita_sandbox-2.1.4a4-py3-none-any.whl

Total release size: 1.3 MB

Release files / novita_sandbox-2.1.4a4.tar.gz

Download URL novita_sandbox-2.1.4a4.tar.gz
Size 586.8 kB
Tags Source
SHA-256 checksum
How to use checksums
186efba01c6c596f330523bac67d0a7c27cb6d1512fb7a08000640317d05bd42
BLAKE2b-256 checksum
How to use checksums
43b7a2fb56399a6c6edc08593e94c01bddd8649891e538e7640b9c53ba98d556
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.1.2 CPython/3.12.16 Linux/7.0.0-1019-azure

Release files / novita_sandbox-2.1.4a4-py3-none-any.whl

Download URL novita_sandbox-2.1.4a4-py3-none-any.whl
Size 706.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9eac2c92e6e4d1e159fe4db8cae7f2764bbac4bf3e35d3868a48b1c1b6820ba1
BLAKE2b-256 checksum
How to use checksums
91d05e0a5f676d8e60971d4e4e0996ac9a046fda71c0460351d5d2f1f65070c8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.1.2 CPython/3.12.16 Linux/7.0.0-1019-azure

Security for novita-sandbox 2.1.4a4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page