Quickstart: Give an Agent a Computer

A sandbox is a computer for your agent: a machine in the cloud it drives from code. In about five minutes you’ll create one, run code in it, serve a URL, fork it from a memory snapshot, and attach a GPU.

Using Cursor, Claude Code, or Codex? Run beam setup agent to connect your coding agent to your workspace. See agent setup.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade beam-client
beam login

Finish signing in through your browser, then run beam whoami to check your workspace.

Run Code, Serve a URL, and Fork

Save this as sandbox.py and run python sandbox.py:

sandbox.py

from beam import Sandbox

# Create a sandbox and run code
sb = Sandbox(cpu=1, memory="1Gi", keep_warm_seconds=600).create()
print(sb.process.run_code("print(sum(range(10)))").stdout)  # 45

# Start a web server and get a URL
sb.fs.write_text("/workspace/index.html", "Hello from a Beam sandbox")
sb.process.exec(
    "python3", "-m", "http.server", "8000", "--bind", "0.0.0.0",
    cwd="/workspace",
)
print(sb.expose_port(8000))

# Snapshot memory, including the running server, then fork it
snapshot_id = sb.snapshot_memory()
sb.terminate()

forks = [Sandbox().create_from_memory_snapshot(snapshot_id) for _ in range(3)]
for fork in forks:
    print(fork.list_urls())  # each fork serves its own copy
    fork.terminate()

Preview URLs are public. Add authentication in your app before serving anything sensitive.

Add a GPU

Attach a GPU with one argument:

from beam import Sandbox

sb = Sandbox(gpu="RTX4090", memory="8Gi").create()
p = sb.process.exec("nvidia-smi")
p.wait()
print(p.logs.read())
sb.terminate()

Requesting a GPU doesn’t install CUDA libraries. Add packages such as torch to the sandbox image.

Control Outbound Traffic

Each sandbox is isolated from your app and other workloads. To control what an agent’s computer can reach, block outbound traffic or allow only specific CIDR ranges:

from beam import Sandbox

sb = Sandbox(block_network=True).create()                        # no outbound traffic
sb.update_network_permissions(block_network=False, allow_list=[])  # reopen it at runtime
sb.terminate()

sb = Sandbox(allow_list=["10.0.0.0/8"]).create()                 # or allow only these ranges
sb.terminate()

Next Steps

Run Your First App

Run a function and deploy a web endpoint.

Snapshots

Save filesystem or memory state and fork it.

Networking

Preview URLs and outbound rules.

TypeScript SDK

Create and operate sandboxes from Node.js.

Start Here

Sandboxes

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

Quickstart: Give an Agent a Computer

Run Code, Serve a URL, and Fork

Add a GPU

Control Outbound Traffic

Next Steps

Run Your First App

Snapshots

Networking

TypeScript SDK

​Install and Sign In

​Run Code, Serve a URL, and Fork

​Add a GPU

​Control Outbound Traffic

​Next Steps

Run Your First App

Snapshots

Networking

TypeScript SDK

Install and Sign In

Run Code, Serve a URL, and Fork

Add a GPU

Control Outbound Traffic

Next Steps