Create an AI sandbox with Python - bead

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

pip install beadrun

Set BEAD_API_KEY through your secret manager or private environment. Get an account through agent signup. The SDK defaults to https://api.bead.run; set BEAD_API_URL for another deployment.

Run a command

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

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 for files, snapshots, fleets, swarms and error handling.