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

# Create an AI sandbox with Python

> Create an AI sandbox with Python after installing beadrun, then authenticate, run a command, and delete the machine.

Create an AI sandbox with Python, run a command on its Linux machine and delete it with `beadrun`. Python 3.11 or later is supported.

## Install and authenticate

```bash theme={null}
pip install beadrun
```

Set `BEAD_API_KEY` through your secret manager or private environment. Get an account through [agent signup](https://docs.bead.run/agent-signup.md). The SDK defaults to `https://api.bead.run`; set `BEAD_API_URL` for another deployment.

## Run a command

```python theme={null}
from beadrun import Sandbox

with Sandbox.create(template="base", size="small", timeout=300) as sb:
    result = sb.run("echo hi", timeout=30)
    print(result.stdout)
    print(result.exit_code)
```

The context manager deletes the machine on normal exit and exceptions. The machine lifetime defaults to 300 seconds; all SDK timeouts use seconds. A disconnected process does not stop remote compute.

A nonzero command exit is a result, with `exit_code`, `stdout` and `stderr`. Inspect it before starting dependent work.

## Use async

```python theme={null}
import asyncio
from beadrun import AsyncSandbox

async def main():
    async with await AsyncSandbox.create(template="base", size="small") as sb:
        result = await sb.run("echo hi")
        print(result.stdout)
        async for event in sb.run("echo stream", stream=True):
            print(event.type, event.data)

asyncio.run(main())
```

Breaking output iteration stops reading; it does not guarantee the remote process stopped. Use machine cleanup when work is finished.

See [Python SDK reference](https://docs.bead.run/sdks/python/reference.md) for files, snapshots, fleets, swarms and error handling.


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