Modal logo
Changelog API Reference modal.Appmodal.Clientmodal.CloudBucketMountmodal.Clsmodal.Cronmodal.Dictmodal.Errormodal.FilePatternMatchermodal.Functionmodal.FunctionCallmodal.Imagemodal.Periodmodal.Probemodal.Proxymodal.Queuemodal.Retriesmodal.Sandboxmodal.SandboxSnapshotmodal.Secretmodal.Tunnelmodal.Volumemodal.asgi_appmodal.batchedmodal.billingmodal.call_graphmodal.concurrentmodal.container_processmodal.current_function_call_idmodal.current_input_idmodal.enable_outputmodal.entermodal.exitmodal.fastapi_endpointmodal.file_iomodal.forwardmodal.interactmodal.io_streamsmodal.is_localmodal.methodmodal.parametermodal.web_servermodal.wsgi_appmodal.exceptionmodal.config CLI Reference modal appmodal billingmodal bootstrapmodal changelogmodal configmodal containermodal dashboardmodal deploymodal dictmodal environmentmodal profilemodal queuemodal runmodal secretmodal servemodal setupmodal shellmodal tokenmodal volume

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

detach 

Disconnects your client from the sandbox and cleans up resources assoicated with the connection.

Be sure to only call detach when you are done interacting with the sandbox. After calling detach, any operation using the Sandbox object is not guaranteed to work anymore. If you want to continue interacting with a running sandbox, use Sandbox.from_id to get a new Sandbox object.

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.

mount_image 

Mount an Image at a specified path in a running Sandbox.

path should be a directory that is not the root path (/). If the path doesn’t exist it will be created. If it exists and contains data, the previous directory will be replaced by the mount.

The image argument supports any Image that has an object ID, including:

  • Images built using image.build()
  • Images referenced by ID, e.g. Image.from_id(...)
  • Filesystem/directory snapshots, e.g. created by .snapshot_directory() or .snapshot_filesystem()
  • Empty images created with Image.from_scratch()

Usage:

unmount_image 

Unmount a previously mounted Image from a running Sandbox.

path must be the exact mount point that was passed to .mount_image(). After unmounting, the underlying Sandbox filesystem at that path becomes visible again.

snapshot_directory 

Snapshot a directory in a running Sandbox, creating a new Image with its content.

Directory snapshots are currently persisted for 30 days after they were last created or used.

Usage:

wait 

Wait for the Sandbox to finish running.

wait_until_ready 

Wait for the Sandbox readiness probe to report that the Sandbox is ready.

The Sandbox must be configured with a readiness_probe in order to use this method.

Usage:

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 

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

filesystem 

Namespace for Sandbox filesystem APIs.

filesystem.read_bytes 

Read a file from the Sandbox and return its contents as bytes.

remote_path must be an absolute path to a file in the Sandbox.

Raises

  • SandboxFilesystemNotFoundError: the path does not exist.
  • SandboxFilesystemIsADirectoryError: the path points to a directory.
  • SandboxFilesystemPermissionError: read permission is denied.
  • SandboxFilesystemError: the command fails for any other reason.

Usage

filesystem.read_text 

Read a file from the Sandbox and return its contents as a UTF-8 string.

remote_path must be an absolute path to a file in the Sandbox.

Raises

  • SandboxFilesystemNotFoundError: the path does not exist.
  • SandboxFilesystemIsADirectoryError: the path points to a directory.
  • SandboxFilesystemPermissionError: read permission is denied.
  • SandboxFilesystemError: the command fails for any other reason.

Usage

filesystem.copy_to_local 

Copy a file from the Sandbox to a local path.

remote_path must be an absolute path to a file in the Sandbox. Parent directories for local_path are created if needed. The local file is overwritten if it already exists.

Raises

  • SandboxFilesystemNotFoundError: the remote path does not exist.
  • SandboxFilesystemIsADirectoryError: the remote path points to a directory.
  • SandboxFilesystemPermissionError: read permission is denied in the Sandbox.
  • SandboxFilesystemError: the command fails for any other reason.
  • IsADirectoryError: local_path points to a directory.
  • NotADirectoryError: a component of the local_path parent is not a directory.
  • PermissionError: writing local_path is not permitted.

Usage

filesystem.write_bytes 

Write binary content to a file in the Sandbox.

remote_path must be an absolute path to a file in the Sandbox. Parent directories for remote_path are created if needed. The remote file is overwritten if it already exists.

Raises

  • SandboxFilesystemNotADirectoryError: a parent path component is not a directory.
  • SandboxFilesystemIsADirectoryError: remote_path points to a directory.
  • SandboxFilesystemPermissionError: write permission is denied.
  • SandboxFilesystemError: the command fails for any other reason.

Usage

filesystem.write_text 

Write UTF-8 text to a file in the Sandbox.

remote_path must be an absolute path to a file in the Sandbox. Parent directories for remote_path are created if needed. The remote file is overwritten if it already exists.

Raises

  • SandboxFilesystemNotADirectoryError: a parent path component is not a directory.
  • SandboxFilesystemIsADirectoryError: remote_path points to a directory.
  • SandboxFilesystemPermissionError: write permission is denied.
  • SandboxFilesystemError: the command fails for any other reason.

Usage

filesystem.copy_from_local 

Copy a local file into the Sandbox.

remote_path must be an absolute path to a file in the Sandbox. Parent directories for remote_path are created if needed. The remote file is overwritten if it already exists.

Raises

  • SandboxFilesystemNotADirectoryError: a parent path component of remote_path is not a directory.
  • SandboxFilesystemIsADirectoryError: remote_path points to a directory.
  • SandboxFilesystemPermissionError: write permission is denied in the Sandbox.
  • SandboxFilesystemError: the command fails for any other reason.
  • FileNotFoundError: local_path does not exist.
  • IsADirectoryError: local_path is a directory.
  • PermissionError: reading local_path is not permitted.

Usage

filesystem.remove 

Remove a file or directory in the Sandbox.

remote_path must be an absolute path in the Sandbox.

When remote_path is a directory and recursive is False (the default), removes it only if it is empty. When recursive is True, removes the directory and all its contents.

Recursive directory removal is not supported on all mounts. In particular, CloudBucketMount does not support it. An InvalidError is raised in that case.

Raises

  • SandboxFilesystemNotFoundError: the path does not exist.
  • SandboxFilesystemDirectoryNotEmptyError: recursive is False and the directory is not empty.
  • SandboxFilesystemPermissionError: removal is not permitted.
  • InvalidError: the operation is not supported by the mount.
  • SandboxFilesystemError: the command fails for any other reason.

Usage

To remove a file:

To remove a directory and all its contents:

filesystem.make_directory 

Create a new directory in the Sandbox.

remote_path must be an absolute path in the Sandbox.

When create_parents is True (the default), any missing parent directories are created and the call is idempotent (succeeds silently if the directory already exists). When create_parents is False, the immediate parent directory must already exist and the path must not already exist.

Raises

  • SandboxFilesystemNotFoundError: the parent directory does not exist and create_parents is False.
  • SandboxFilesystemPathAlreadyExistsError: the path already exists.
  • SandboxFilesystemNotADirectoryError: a path component is not a directory.
  • SandboxFilesystemPermissionError: creation is not permitted.
  • InvalidError: the operation is not supported by the mount.
  • SandboxFilesystemError: the command fails for any other reason.

Usage

open 

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

.. deprecated:: 2026-03-09 Use the Sandbox.filesystem APIs instead.

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.

.. deprecated:: 2026-04-15 Use Sandbox.filesystem.make_directory() instead.

rm 

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

.. deprecated:: 2026-04-15 Use Sandbox.filesystem.remove() instead.

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.