Sandbox

Overview

Method	Description
`Sandbox.create()`	Create a new sandbox
`sandbox.commands.run(cmd)`	Run a command
`sandbox.commands.interrupt()`	Stop the command that is running
`sandbox.code.run(code)`	Run Python code
`sandbox.close()`	Shut down the running sandbox (suspended instances are unaffected)
`sandbox.tier`	Which engine the sandbox runs on
`sandbox.trace.collect()`	Everything the sandbox has recorded, when it was created with `trace=True`
`sandbox.suspend()`	Suspend to disk, returns an instance ID
`Sandbox.resume(id)`	Resume a suspended instance
`Sandbox.list_instances()`	List all instances
`Sandbox.destroy(id)`	Delete a suspended instance from disk

Shell commands and Python code share the same filesystem:

from vpod import Sandbox

with Sandbox.create() as sandbox:
    sandbox.commands.run("echo 'from shell' > /tmp/shared.txt")
    sandbox.code.run("print(open('/tmp/shared.txt').read().strip())")

An export inside a command doesn’t cross between shell and Python: sandbox.commands.run("export FOO=bar") is not visible in sandbox.code.run(...). Set env at creation for variables both sides should see, and use the filesystem to share data between the two afterwards.

Return values

`sandbox.commands.run(cmd)`

Returns a command result:

Field	Type	Description
`stdout`	`str`	Standard output of the command
`stderr`	`str`	Standard error of the command
`exit_code`	`int`	Exit code of the command

result = sandbox.commands.run("whoami")
print(result.stdout)    # root
print(result.exit_code)  # 0

`sandbox.code.run(code)`

Returns an execution result:

Field	Type	Description
`text`	`str`	Output of the executed code
`error`	`Optional[str]`	Error message if the execution failed, `None` otherwise
`logs`	`list[str]`	Log lines produced during execution

result = sandbox.code.run("print(sum([1, 2, 3]))")
print(result.text)   # 6
print(result.error)  # None

For commands that run long enough to bound, watch, or feed input to — timeouts, interrupts, streaming output, and stdin — see Process I/O.

`Sandbox.create()` parameters

`snapshot`

The snapshot to boot from. Defaults to alpine. See Snapshots for the full catalog.

sandbox = Sandbox.create(snapshot="alpine")

`mounts`

Mount host directories into the sandbox. Paths are read-only by default; append :rw for read-write access.

sandbox = Sandbox.create(mounts={"workspace": "/workspace:rw", "docs": "/docs"})

`env`

Environment variables the guest starts with. They reach commands, anything those commands spawn, and code.run.

sandbox = Sandbox.create(env={"TZ": "UTC", "API_BASE": "https://example.com"})

sandbox.commands.run("echo $TZ")             # UTC
sandbox.code.run("import os; print(os.environ['TZ'])")

Values are passed literally, so quotes, $, and backticks in a value are never interpreted by the shell. Names must be plain identifiers.

Values set this way are visible inside the sandbox. Anything running there can read them from the environment, so treat env as configuration rather than a place for API keys or tokens. Use secrets for those.

`secrets`

A credential the sandbox can use but never read. The guest is given a stand-in through its environment; the value itself goes only to the network gateway, which swaps it back in on the way out, and only for a host you named.

sandbox = Sandbox.create(secrets={
    "ANTHROPIC_API_KEY": {
        "value": os.environ["ANTHROPIC_API_KEY"],
        "hosts": ["api.anthropic.com"],
    },
})

Agent frameworks read credentials from the environment already, so code in the sandbox needs no changes. What it reads back is the stand-in:

sandbox.commands.run("echo $ANTHROPIC_API_KEY")
# vpod-secret-anthropic_api_key-3f9c1a04

Key	Description
`value`	The credential. Never enters the sandbox
`hosts`	Where it may be sent. A string, or a list. `*.example.com` matches one label
`placeholder`	What the guest sees. Generated when left out

Set placeholder yourself when a client library checks the shape of a key:

"secrets": {"API_KEY": {"value": key, "hosts": ["api.example.com"],
                        "placeholder": "sk-live-vpod0000"}}

The sandbox cannot read the credential, but it can spend it: any code running there can call the allowlisted host and the gateway will authenticate the request. This hides the credential, it does not restrain its use.

A request carrying a stand-in to a host that is not on its list fails rather than going out unswapped, so a mistake surfaces as an error instead of a puzzling 401 somewhere else. Substitution covers the request line and headers, which is where every API this was built for puts its key; a credential sent in a JSON body is not swapped. A client that pins certificates cannot be used this way, because the gateway terminates TLS.

`trace`

Records what the sandbox actually did, which programs ran, which files changed and where it connected. Off unless you ask for it, and chosen at creation:

with Sandbox.create(trace=True) as sandbox:
    result = sandbox.commands.run("sh -c 'cd /app && make'")

    result.trace.processes()  # what ran
    result.trace.files()      # what it touched

See Tracing.

`engine`

Some private snapshots come with their own engine, which runs the tools installed in them faster. With the default "auto", the sandbox uses that engine when it is already compiled, and otherwise starts on the engine bundled with the SDK while the snapshot’s engine is prepared in the background for next time. See Private snapshots. Pass "default" to always use the bundled engine:

sandbox = Sandbox.create(snapshot="my-snapshot", engine="default")

sandbox.tier says which engine it got: "image" for the snapshot’s own, "aot" or "base" for the bundled one.

Get Started

TypeScript SDK

Python SDK

Embedded preview (In Iframe)

CLI

Resources

Overview

Return values

`sandbox.commands.run(cmd)`

`sandbox.code.run(code)`

`Sandbox.create()` parameters

`snapshot`

`mounts`

`env`

`secrets`

`trace`

`engine`

​Overview

​Return values

​sandbox.commands.run(cmd)

​sandbox.code.run(code)

​Sandbox.create() parameters

​snapshot

​mounts

​env

​secrets

​trace

​engine

Overview

Return values

`sandbox.commands.run(cmd)`

`sandbox.code.run(code)`

`Sandbox.create()` parameters

`snapshot`

`mounts`

`env`

`secrets`

`trace`

`engine`