modal.Sandbox

A Sandbox object lets you interact with a running sandbox. This API is similar to Python’s asyncio.subprocess.Process.

Refer to the guide on how to spawn and use sandboxes.

hydrate 

Synchronize the local object with its identity on the Modal server.

It is rarely necessary to call this method explicitly, as most operations will lazily hydrate when needed. The main use case is when you need to access object metadata, such as its ID.

Added in v0.72.39: This method replaces the deprecated .resolve() method.

create 

Create a new Sandbox to run untrusted, arbitrary code.

The Sandbox’s corresponding container will be created asynchronously.

Usage

from_name 

Get a running Sandbox by name from a deployed App.

Raises a modal.exception.NotFoundError if no running sandbox is found with the given name. A Sandbox’s name is the name argument passed to Sandbox.create.

from_id 

Construct a Sandbox from an id and look up the Sandbox result.

The ID of a Sandbox object can be accessed using .object_id.

get_tags 

Fetches any tags (key-value pairs) currently attached to this Sandbox from the server.

set_tags 

Set tags (key-value pairs) on the Sandbox. Tags can be used to filter results in Sandbox.list.

snapshot_filesystem 

Snapshot the filesystem of the Sandbox.

Returns an Image object which can be used to spawn a new Sandbox with the same filesystem.

wait 

Wait for the Sandbox to finish running.

tunnels 

Get Tunnel metadata for the sandbox.

Raises SandboxTimeoutError if the tunnels are not available after the timeout.

Returns a dictionary of Tunnel objects which are keyed by the container port.

NOTE: Previous to client v0.64.153, this returned a list of TunnelData objects.

create_connect_token 

[Alpha] Create a token for making HTTP connections to the Sandbox.

Also accepts an optional user_metadata string or dict to associate with the token. This metadata will be added to the headers by the proxy when forwarding requests to the Sandbox.

reload_volumes 

Reload all Volumes mounted in the Sandbox.

Added in v1.1.0.

terminate 

Terminate Sandbox execution.

This is a no-op if the Sandbox has already finished running.

poll 

Check if the Sandbox has finished running.

Returns None if the Sandbox is still running, else returns the exit code.

exec 

Execute a command in the Sandbox and return a ContainerProcess handle.

See the ContainerProcess docs for more information.

Usage

open 

[Alpha] Open a file in the Sandbox and return a FileIO handle.

See the FileIO docs for more information.

Usage

ls 

[Alpha] List the contents of a directory in the Sandbox.

mkdir 

[Alpha] Create a new directory in the Sandbox.

rm 

[Alpha] Remove a file or directory in the Sandbox.

watch 

[Alpha] Watch a file or directory in the Sandbox for changes.

stdout 

StreamReader for the sandbox’s stdout stream.

stderr 

StreamReader for the Sandbox’s stderr stream.

stdin 

StreamWriter for the Sandbox’s stdin stream.

returncode 

Return code of the Sandbox process if it has finished running, else None.

list 

List all Sandboxes for the current Environment or App ID (if specified). If tags are specified, only Sandboxes that have at least those tags are returned. Returns an iterator over Sandbox objects.