Run Agent Code in a Sandbox

A sandbox is a disposable environment your code creates, uses, and throws away. 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. For a persistent machine that keeps its disk between sessions, start with the VM quickstart.

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. Block outbound traffic or allow only specific hostnames, wildcard domains, IPs or CIDRs:

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=["api.openai.com"]).create()             # or allow only this API
sb.terminate()

To give the agent credentials, use brokered secrets. The guest receives placeholders; the worker supplies the real values only in HTTPS headers to approved hosts. With block_network=True and secrets, only their approved hosts are reachable. The guest has no automatic Beam workspace token.

Next Steps

Give an Agent a Dev Box

Create a persistent VM that pauses when idle.

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

Virtual Machines

Sandboxes

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

Run Agent Code in a Sandbox

Run Code, Serve a URL, and Fork

Add a GPU

Control Outbound Traffic

Next Steps

Give an Agent a Dev Box

Snapshots

Networking

TypeScript SDK

Install and Sign In

Run Code, Serve a URL, and Fork

Add a GPU

Control Outbound Traffic

Next Steps

Give an Agent a Dev Box

Snapshots

Networking

TypeScript SDK