A Sandbox object lets you interact with a running sandbox. This API is similar to Python’s asyncio.subprocess.Process.
Refer to the sandbox guide on how to spawn and use sandboxes.
Methods
Sandbox.create
modal.Sandbox.create(
*args: str,
app: Optional[App] = None,
name: Optional[str] = None,
image: Optional[Image] = None,
env: Optional[dict[str, Optional[str]]] = None,
secrets: Optional[Collection[Secret]] = None,
network_file_systems: dict[Union[str, os.PathLike], NetworkFileSystem] = {},
timeout: int = 300,
idle_timeout: Optional[int] = None,
workdir: Optional[str] = None,
gpu: GPU_T = None,
cloud: Optional[str] = None,
region: Optional[Union[str, Sequence[str]]] = None,
cpu: Optional[Union[float, tuple[float, float]]] = None,
memory: Optional[Union[int, tuple[int, int]]] = None,
block_network: bool = False,
cidr_allowlist: Optional[Sequence[str]] = None,
volumes: dict[Union[str, os.PathLike], Union[Volume, CloudBucketMount]] = {},
pty: bool = False,
encrypted_ports: Sequence[int] = [],
h2_ports: Sequence[int] = [],
unencrypted_ports: Sequence[int] = [],
custom_domain: Optional[str] = None,
proxy: Optional[Proxy] = None,
verbose: bool = False,
client: Optional[Client] = None,
environment_name: Optional[str] = None,
) -> Sandbox
Command and arguments to run in the sandbox (sets the CMD).
Associate the sandbox with an app. Required unless creating from a container.
Optional name for the sandbox. Unique within an app.
Image to run as the container for the sandbox.
Environment variables to set in the Sandbox.
Secrets to inject into the Sandbox as environment variables.
Maximum lifetime of the sandbox in seconds.
Idle time in seconds before termination.
Working directory of the sandbox.
GPU configuration (e.g., “A100”, “T4”).
cpu
Union[float, tuple[float, float]]
CPU cores (request) or (request, limit).
memory
Union[int, tuple[int, int]]
Memory in MiB (request) or (request, limit).
Whether to block network access.
Mount points for Modal Volumes and CloudBucketMounts.
Enable a PTY for the Sandbox.
List of ports to tunnel with TLS encryption.
The created Sandbox instance.
app = modal.App.lookup('sandbox-hello-world', create_if_missing=True)
sandbox = modal.Sandbox.create("echo", "hello world", app=app)
print(sandbox.stdout.read())
sandbox.wait()
sandbox.wait
Wait for the sandbox to finish and return its exit code.
Exit code of the sandbox process.
sandbox.terminate
Terminate the sandbox.
sandbox.poll
sandbox.poll() -> Optional[int]
Exit code if finished, None if still running.
sandbox.exec
sandbox.exec(
*args: str,
pty: bool = False,
) -> ContainerProcess
Command and arguments to execute.
Enable PTY for the exec session.
Process handle for the executed command.
sb = modal.Sandbox.create("sleep", "infinity", app=app)
process = sb.exec("echo", "hello")
stdout = process.stdout.read()
print(stdout) # "hello"
Properties
sandbox.stdin
sandbox.stdin -> StreamWriter
sandbox.stdout
sandbox.stdout -> StreamReader
sandbox.stderr
sandbox.stderr -> StreamReader
sandbox.returncode
sandbox.returncode -> Optional[int]