Sandbox Python SDK

Import the sandbox Python SDK package beadrun for synchronous objects and native async equivalents. Begin with the quickstart.

Machines and options

Method or property	Purpose
`Sandbox.create(...)`	Create a machine.
`Sandbox.connect(id, **client)`	Connect to an existing machine.
`Sandbox.from_golden(golden, **client)`	Create from a ready snapshot object or template ID.
`sb.id`, `sb.sandbox_id`, `sb.info`	Resource identity and machine metadata.
`sb.pause()`, `sb.resume(timeout=300)`	Pause or resume.
`sb.kill()`	Delete the machine.
`sb.cost()`	Read observed cost.
`sb.snapshot(name="snapshot", retention_seconds=None, inherit_credentials=False)`	Capture a snapshot and wait for publication.
`sb.fork(n=1, timeout=300)`	Create independent memory copies.

Creation options include template (default base), size, timeout (default 300), env, region, credential_profile, kind, idle_timeout, auto_pause and idempotency_key. Size can be a name or a resource object with vcpus and memory_mib. Memory restores require the source shape. Client overrides include api_key, api_url, sandbox_url, request_timeout, operation_timeout, retries, retry_delay and poll_interval. Poll interval defaults to one second. Region validates the deployment catalog; use the appropriate API origin to select deployment.

Commands and files

from beadrun import Sandbox

with Sandbox.create(size="small") as sb:
    result = sb.run("pwd", cwd="/tmp", env={"GREETING": "hi"}, timeout=30)
    print(result.exit_code, result.stdout, result.stderr)
    for event in sb.run("echo stream", stream=True):
        print(event.type, event.data, event.exit_code)
    sb.files.write("/tmp/hello.txt", "hi")
    print(sb.files.read("/tmp/hello.txt"))
    print(sb.files.list("/tmp"))

sb.commands.run is also available. Callbacks use on_stdout and on_stderr. The command timeout defaults to 60 seconds. files.read_bytes(path) reads binary bytes. files.upload(local_path, remote_path) and files.download(remote_path, local_path) transfer local files. files.write accepts text or bytes. sb.ports.url(3000) constructs an application URL. The URL alone grants no access; the application route may require sb.info["trafficAccessToken"] in e2b-traffic-access-token. Reserved ports are rejected. See application URLs.

Snapshots, fleets and swarms

A snapshot returns a Golden with info, id, wait() and delete(). Snapshot storage has its own lifetime; deleting a source machine does not delete its snapshots.

from beadrun import Fleet, Swarm

with Fleet.create(2, size="small") as fleet:
    for member in fleet:
        print(member.run("echo fleet").stdout)

swarm = Swarm.run(cmd="echo swarm", inputs=[1, 2], size="small")
try:
    for result in swarm:
        print(result)
finally:
    swarm.close()

Fleet.kill() deletes fleet members. Swarm.status() inspects the submitted job and Swarm.cancel() requests cancellation. Closing a swarm client keeps the job inspectable. BatchError.results retains successful sandbox objects and per-member errors; clean up successes explicitly.

Account and agent resources

beadrun.pricing.estimate(...) estimates cost; beadrun.limits() reads limits. Bead().profiles provides list(), put(id, name, material), revoke(id) and delete(id). Close an account client after use. sb.agent.prompt(...) yields cursor-paged runner events. status() reads conversation state; interrupt(turn_id) interrupts a turn. sb.desktop.screenshot() returns bytes and sb.browser.command(args) runs the browser helper. These require supported templates and configured credentials; see runners.

Async and errors

Use AsyncSandbox, AsyncFleet, AsyncSwarm and AsyncBead for async work. Await operations and use async with or async for where appropriate. BeadError subclasses include AuthenticationError, NotFoundError, TimeoutError, ProtocolError, LimitError, RateLimitError, PaymentRequiredError and BatchError. Errors retain status, code and request_id; limit errors expose limit, and payment errors expose purchase_url. Creates, connects, pauses, resumes, sandbox deletions, snapshots, fleets and forks generate idempotency keys and retry selected transient failures. Reads also retry with bounded backoff. Snapshot deletion through Golden.delete() does not generate an idempotency key or automatically retry. Commands and prompts are not automatically replayed. Keep explicit create idempotency keys for cross-process recovery.

​Machines and options

​Commands and files

​Snapshots, fleets and swarms

​Account and agent resources

​Async and errors

Machines and options

Commands and files

Snapshots, fleets and swarms

Account and agent resources

Async and errors