Sandbox

class

gworker_client.sandbox.Sandbox

An ephemeral, isolated execution environment. Useful for running untrusted code, one-shot scripts, or multi-step workflows with shared state between exec() calls. Destroyed automatically after terminate() or context exit.

Class

python
1class Sandbox

Methods

create

python
1create(cmd: object = (), image: Image | None = None, secrets: Sequence[Secret] = (), volumes: Mapping[str, Volume] | None = None, timeout: float = 300.0, env: Mapping[str, str] | None = None, workdir: str | None = None, snapshot: SandboxSnapshot | None = None) -> Sandbox

Start a sandbox running cmd. If snapshot= is provided, the container is restored from that checkpoint instead of a cold start. Returns immediately; use wait() or poll() to block.

exec

python
1exec(cmd: object = (), env: Mapping[str, str] | None = None, workdir: str | None = None) -> SandboxProcess

Run another command inside this sandbox and return its process handle. The sandbox must still be alive. Multiple exec() calls share the same filesystem and process namespace.

wait

python
1wait(timeout: float | None = None) -> int

Block until the entry command exits. Returns the exit code. Raises TimeoutError if timeout elapses before the process exits.

poll

python
1poll() -> int | None

Non-blocking check. Returns the exit code if the entry command has finished, or None if it is still running.

terminate

python
1terminate() -> None

Stop the sandbox immediately and remove it from the registry. Releases all resources. Idempotent — safe to call on an already-stopped sandbox.

snapshot

python
1snapshot() -> SandboxSnapshot

Capture a memory checkpoint of the running sandbox. The snapshot can be passed as snapshot= to Sandbox.create() to restore the container state on the next invocation, skipping cold-start setup.

lookup

python
1lookup(sandbox_id: str) -> Sandbox

Resolve a sandbox by its ID, e.g. to reconnect after a network interruption. Raises NotFoundError if the sandbox ID is unknown or has already been terminated.

← Back to docs