Skip to main content

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

See GS migration, image configuration, and long-running sandbox examples for the additional APIs available on this branch.

Installation

pip install novita-sandbox-gs

Quick Start

Authentication

Get your Novita API key from the key management page.

Core Sandbox

The basic package provides a way to interact with the sandbox environment.

from novita_sandbox_gs.core import Sandbox
import os

# Using the official template `base` by default
sandbox = Sandbox.create(
    template="base",
    api_key=os.getenv("NOVITA_API_KEY", "")
)

# 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 provides a Jupyter-like environment for executing code using the official code-interpreter-v1 template.

from novita_sandbox_gs.code_interpreter import Sandbox
import os

sandbox = Sandbox.create(
    api_key=os.getenv("NOVITA_API_KEY", "")
)

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

sandbox.kill()

Desktop Automation

The Desktop sandbox allows you to control desktop environments programmatically using the official desktop template.

from novita_sandbox_gs.desktop import Sandbox
import os

desktop = Sandbox.create(
    api_key=os.getenv("NOVITA_API_KEY", "")
)

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

Metadata

Release files for novita-sandbox-gs 2.0.12

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-gs 2.0.12
File Size Uploaded Provenance Actions
novita_sandbox_gs-2.0.12.tar.gz 555.8 kB Without provenance Details for novita_sandbox_gs-2.0.12.tar.gz

Built distribution (wheel)

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

Total release size: 1.2 MB

Release files / novita_sandbox_gs-2.0.12.tar.gz

Download URL novita_sandbox_gs-2.0.12.tar.gz
Size 555.8 kB
Tags Source
SHA-256 checksum
How to use checksums
f3e3683e231d608a551da899ef935b88c404db40a8b5986928052334bf1bf052
BLAKE2b-256 checksum
How to use checksums
4896680ba78f67b77ae2f96c7c233701dced9a3606d67916e6e6ce1bca9e90d2
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-1017-azure

Release files / novita_sandbox_gs-2.0.12-py3-none-any.whl

Download URL novita_sandbox_gs-2.0.12-py3-none-any.whl
Size 679.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3e043a52de3be343fce472bd5b4a18014a4b263cc3946b029114126b9f92d5f3
BLAKE2b-256 checksum
How to use checksums
1e90b5c24c174ea3c26e9e79c0673f5bb8847f2abddc8ff0d216511f828a82ed
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-1017-azure

Security for novita-sandbox-gs 2.0.12

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.

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