Create Sandbox

The simplest way to create a sandbox is to call novita.sandbox.create() without any arguments.

import 'dotenv/config'
import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create()

await sandbox.kill()

from dotenv import load_dotenv
from novita_sandbox import Novita

load_dotenv()

novita = Novita()
sandbox = novita.sandbox.create()

sandbox.kill()

# Create a sandbox from the base template and connect a terminal (alias: sandbox cr)
novita-sandbox-cli sandbox create base

# Create without connecting a terminal (detached), returns the sandbox ID
novita-sandbox-cli sandbox create base -d

From Template

You can create a sandbox from a template by passing the template name or ID.

Python

from dotenv import load_dotenv
from novita_sandbox import Novita

load_dotenv()

novita = Novita()

# Create a sandbox from a template name or template ID.
sandbox = novita.sandbox.create(
    "my-python-app",   # template name or ID
    timeout=300,        # seconds, optional
    metadata={"env": "demo"},
    envs={"KEY": "value"},
)

print("Sandbox ID:", sandbox.sandbox_id)

# Use it.
result = sandbox.commands.run("python3 --version")
print(result.stdout)

sandbox.kill()

Use a context manager for automatic cleanup:

from novita_sandbox import Novita

novita = Novita()

with novita.sandbox.create("my-python-app") as sandbox:
    print(sandbox.commands.run("echo hello").stdout)
# Automatically killed when exiting the with block.

import 'dotenv/config'
import { Novita } from 'novita-sandbox'

const novita = new Novita()

// Create a sandbox from a template name or template ID.
const sandbox = await novita.sandbox.create('my-python-app', {
  timeoutMs: 300_000, // milliseconds, optional
  metadata: { env: 'demo' },
  envs: { KEY: 'value' },
})

console.log('Sandbox ID:', sandbox.sandboxId)

// Use it.
const result = await sandbox.commands.run('python3 --version')
console.log(result.stdout)

await sandbox.kill()

# Create a sandbox from a specific template (by name or template ID)
novita-sandbox-cli sandbox create <template>

# Detached (no terminal), prints the new sandbox ID
novita-sandbox-cli sandbox create <template> -d

Environment Variables

You can set environment variables when creating a sandbox, and override or append them on a single command.

from dotenv import load_dotenv
from novita_sandbox import Novita

load_dotenv()

novita = Novita()

# Set environment variables when creating the sandbox.
sandbox = novita.sandbox.create(
    "my-python-app",
    envs={
        "API_KEY": "secret-123",
        "LOG_LEVEL": "debug",
        "PORT": "8000",
    },
)

# Verify.
result = sandbox.commands.run("echo $API_KEY")
print(result.stdout)   # secret-123

# You can also override/append envs on a single command.
result = sandbox.commands.run(
    "echo $LOG_LEVEL",
    envs={"LOG_LEVEL": "info"},
)
print(result.stdout)   # info

sandbox.kill()

import 'dotenv/config'
import { Novita } from 'novita-sandbox'

const novita = new Novita()

// Set environment variables when creating the sandbox.
const sandbox = await novita.sandbox.create('my-python-app', {
  envs: {
    API_KEY: 'secret-123',
    LOG_LEVEL: 'debug',
    PORT: '8000',
  },
})

// Verify.
let result = await sandbox.commands.run('echo $API_KEY')
console.log(result.stdout) // secret-123

// You can also override/append envs on a single command.
result = await sandbox.commands.run('echo $LOG_LEVEL', {
  envs: { LOG_LEVEL: 'info' },
})
console.log(result.stdout) // info

await sandbox.kill()

Metadata

Sandbox metadata lets you attach custom key-value information to a sandbox. Common uses include:

Connecting a sandbox to a user session.
Saving custom user-related data for a sandbox, such as API keys.
Linking a sandbox to a user ID so it can be reconnected later.

Metadata is provided when the sandbox is created. Later, it can be read when listing active sandboxes with novita.sandbox.list(). Sandboxes can also be filtered using metadata when listing.

import { Novita, SandboxState } from 'novita-sandbox'

const novita = new Novita()

// Start a sandbox and attach custom metadata.
const sbx = await novita.sandbox.create({
  metadata: {
    userId: '123',
  },
})

// Retrieve active sandboxes and inspect their metadata.
const page = await novita.sandbox.list()
const active = await page.nextItems()

console.log(active[0].metadata)
// Example output:
// { userId: '123' }

// Filter by metadata.
let sandboxes = await novita.sandbox.list({
  query: { metadata: { env: 'demo' } },
})

// Combine metadata and state filters (multiple conditions are AND).
sandboxes = await novita.sandbox.list({
  query: {
    metadata: { env: 'demo' },
    state: [SandboxState.RUNNING],
  },
})

for (const sandbox of sandboxes) {
  console.log(sandbox.sandboxId, sandbox.state, sandbox.metadata)
}

from novita_sandbox import Novita, SandboxQuery, SandboxState

novita = Novita()

# Start a sandbox and attach custom metadata.
sbx = novita.sandbox.create(
    metadata={
        "userId": "123",
    },
)

# Retrieve active sandboxes and inspect their metadata.
page = novita.sandbox.list()
active = page.next_items()

print(active[0].metadata)
# Example output:
# {"userId": "123"}

# Filter by metadata.
sandboxes = novita.sandbox.list(
    query=SandboxQuery(metadata={"env": "demo"})
)

# Combine metadata and state filters (multiple conditions are AND).
sandboxes = novita.sandbox.list(
    query=SandboxQuery(
        metadata={"env": "demo"},
        state=[SandboxState.RUNNING],
    )
)

for sandbox in sandboxes:
    print(sandbox.sandbox_id, sandbox.state, sandbox.metadata)

Get started

Model APIs

Novita Sandbox

GPUs

Observability

Resources

Create Sandbox

Create Sandbox

From Template

Environment Variables

Metadata

​Create Sandbox

​From Template

​Environment Variables

​Metadata

Create Sandbox

From Template

Environment Variables

Metadata