> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox Python SDK

> Find sync and async methods in the sandbox Python SDK for machines, commands, files, snapshots, fleets, and swarms.

Import the sandbox Python SDK package `beadrun` for synchronous objects and native async equivalents. Begin with the [quickstart](https://docs.bead.run/sdks/python/quickstart.md).

## 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

```python theme={null}
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](https://docs.bead.run/connect/public-urls.md).

## 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.

```python theme={null}
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](https://docs.bead.run/agents/runners.md).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.