Create a sandbox

Sandbox.create() boots a fresh VM and returns when it’s ready to use. There’s no readiness check or polling - the returned instance is already active.

import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({ name: "data-analyzer" })

from superserve import Sandbox

sandbox = Sandbox.create(name="data-analyzer")

With options

Attach metadata tags, inject environment variables, cap the active lifetime, or lock down network egress at creation time.

import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({
  name: "data-analyzer",
  timeoutSeconds: 3600,
  metadata: { env: "prod", owner: "agent-7" },
  envVars: { LOG_LEVEL: "debug" },
  secrets: { OPENAI_API_KEY: "openai-prod" },
  network: {
    allowOut: ["api.openai.com", "*.github.com"],
    denyOut: ["0.0.0.0/0"],
  },
})

from superserve import Sandbox, NetworkConfig

sandbox = Sandbox.create(
    name="data-analyzer",
    timeout_seconds=3600,
    metadata={"env": "prod", "owner": "agent-7"},
    env_vars={"LOG_LEVEL": "debug"},
    secrets={"OPENAI_API_KEY": "openai-prod"},
    network=NetworkConfig(
        allow_out=["api.openai.com", "*.github.com"],
        deny_out=["0.0.0.0/0"],
    ),
)

Use secrets for credentials, not envVars. A secret binds an env var to a stored credential and attaches the real value to outbound requests — the real credential never enters the sandbox. See Secrets.

Common options

Option	Type	Description
`name`	`string`	Required. Human-readable sandbox name.
`timeoutSeconds` / `timeout_seconds`	`number`	Auto-pause after this many seconds of active time (per session; re-armed on resume). See Lifecycle.
`autoDeleteSeconds` / `auto_delete_seconds`	`number`	Delete the sandbox once continuously paused for this many seconds. See Lifecycle.
`metadata`	`Record<string, string>`	String tags. See Metadata.
`envVars` / `env_vars`	`Record<string, string>`	Env vars applied to every process. See Environment variables.
`network`	`NetworkConfig`	Egress allow/deny rules. See Networking.

See the Sandbox reference for every option including apiKey, baseUrl, and signal.

Create from a template

Boot a sandbox from a system or team template via fromTemplate (name, UUID, or Template instance).

const sandbox = await Sandbox.create({
  name: "my-sandbox",
  fromTemplate: "superserve/python-3.11",  // name
})

sandbox = Sandbox.create(
    name="my-sandbox",
    from_template="superserve/python-3.11",
)

The sandbox’s vCPU, memory, and disk size are inherited from the template; they cannot be overridden. See Templates overview for how to build your own. Next: run commands, write files, or pause the sandbox to save costs between runs.

Get Started

Sandbox

Secrets & env vars

Templates

Commands

Filesystem

Storage

Errors

With options

Common options

Create from a template

​With options

​Common options

​Create from a template

With options

Common options

Create from a template