Overview

A sandbox is a container you control through process, filesystem, networking, and snapshot APIs. Use it for code execution, development environments, agent tools, or interactive workloads. Both Python and TypeScript SDKs support sandboxes.

Create and run code

from beam import Sandbox

sb = Sandbox(cpu=1, memory="1Gi", keep_warm_seconds=300).create()
try:
    result = sb.process.run_code("print('Hello from Beam')")
    print(result.stdout)
    print(result.exit_code)
finally:
    sb.terminate()

run_code() waits by default and returns captured stdout, stderr, and the exit code. process.exec() returns a process handle immediately; call wait() when you need its exit code.

Start a web server

from beam import Image, Sandbox

sb = Sandbox(image=Image(python_version="python3.11"), keep_warm_seconds=300).create()
sb.fs.write_text("/workspace/index.html", "Hello from a sandbox")
process = sb.process.exec(
    "python3", "-m", "http.server", "8000", "--bind", "0.0.0.0",
    cwd="/workspace",
)
print(sb.expose_port(8000))
print(sb.container_id)
# Call sb.terminate() when finished, or let the sandbox's TTL expire.

Preview URLs are public. Apply authentication in your application before exposing sensitive content. Outbound network restrictions do not make inbound preview URLs private.

Lifecycle and reconnecting

The Python sandbox defaults to 1 CPU, 128 MiB of memory, Python 3.11, and a 600-second lifetime. Set keep_warm_seconds=-1 for manual termination, or reset the remaining lifetime with sb.update_ttl(300). Save sb.container_id to reconnect while the sandbox is still alive:

from beam import Sandbox

sb = Sandbox().connect("YOUR_CONTAINER_ID")
print(sb.status())
sb.terminate()

Sandbox lifetime, a process wait timeout, and a snapshot’s saved state are separate controls. See configuration and snapshots.

Capabilities

Processes: commands, Python execution, stdin, streaming, cancellation, and async calls.
Filesystem: read/write bytes and text, transfer files, search, and replace.
Networking: preview ports and runtime egress policies.
Docker: build images and run nested containers or Compose services.
TypeScript SDK: create and operate sandboxes from Node.js.

Start Here

Customizing Container Images

Managing Data

Scaling & Performance

Sandboxes

Endpoints and Web Servers

Task Queues

One-Off Functions

Hosting Containers

Operations

Advanced Topics

Self-Hosting

Resources

Security

Create and run code

Start a web server

Lifecycle and reconnecting

Capabilities

​Create and run code

​Start a web server

​Lifecycle and reconnecting

​Capabilities

Create and run code

Start a web server

Lifecycle and reconnecting

Capabilities