Sandboxes

A sandbox fits running generated code, testing a patch, or giving an agent a development environment. Each one is a container in the cloud that your code starts, drives, and terminates.

Create a sandbox

Save this as sandbox_demo.py and run it with uv run python sandbox_demo.py:

from lazycloud import App, Image

app = App("agents")

sandbox = app.sandbox(
    image=Image(python_version="3.12"),
    cpu=1.0,
    memory=1024,
    keep_warm_seconds=600,
)

instance = sandbox.create()
try:
    result = instance.run("python --version")
    print(result.exit_code, result.stdout)
finally:
    instance.terminate()

It prints exit code 0 and the sandbox’s Python version. A sandbox bills until it stops, so the finally block terminates it even when a command fails. A plain number for memory means MiB.

Reconnect to a running sandbox

Another process can reconnect by ID before the sandbox expires:

instance = sandbox.create()
sandbox_id = instance.sandbox_id()

same = sandbox.connect(sandbox_id)   # reconnect later
instance.update_ttl(1800)            # extend the idle lifetime

sandbox.list() returns the workspace’s sandboxes, and sandbox.stats() counts them.

Use a running sandbox

Commands and processes

run waits for the command to exit, and process controls long-running ones:

result = instance.run("pytest -q", cwd="/workspace", timeout_seconds=300)

proc = instance.process.exec("python", "-m", "http.server", "8000")
print(proc.status())
proc.kill()
proc.wait(timeout=10)

instance.process.run_code("print(2 + 2)")   # a Python snippet
instance.list_processes()

A process has pid, status(), kill(), wait(), and stdout, stderr, and logs streams with read() and lines().

Files

instance.fs reads and writes the sandbox filesystem, rooted at /workspace:

instance.fs.upload_file("model.pt", "/workspace/model.pt")
instance.fs.download_file("/workspace/out.json", "out.json")
instance.fs.list_files("/workspace")
instance.fs.stat_file("/workspace/model.pt")
instance.fs.create_directory("/workspace/data")
instance.fs.delete_file("/workspace/tmp.txt")
instance.fs.find_in_files("/workspace/src", "TODO")
instance.fs.replace_in_files("/workspace/src", "old", "new")

Ports and network

url = instance.expose_port(8000)
instance.list_urls()

instance.network_permissions()
instance.update_network_permissions(block_network=True)
instance.update_network_permissions(allow_list=["203.0.113.10/32"])

An exposed URL lives as long as the container. ports=[8000] on the sandbox exposes ports at start. Outbound access is either blocked or limited to CIDR ranges.

Snapshots

snapshot_id = instance.snapshot_memory()
restored = sandbox.create_from_memory_snapshot(snapshot_id)

image_id = instance.create_image_from_filesystem()

A memory snapshot restores a running sandbox. A filesystem image captures the disk for reuse with Image.from_id(...).

Async

Each API has an async form under .aio, such as await instance.aio.run(...).

Sandbox options

Sandboxes accept env, secrets, volumes, gpu and gpu_count, sync_local_dir=True to copy your working directory in at creation, command for the initial process, ports, docker_enabled, and machine. keep_warm_seconds sets how long an idle sandbox stays up, 600 by default.

Docker inside a sandbox

image=Image().with_docker() with docker_enabled=True runs a Docker daemon in the sandbox, and instance.docker wraps run, build, ps, logs, compose_up, and the rest. Nested containers share the sandbox’s network, so each service binds its own port and instance.expose_port(port) gives its URL.

Stop and clean up

instance.terminate() stops a sandbox at once. Otherwise it stops after keep_warm_seconds idle. The dashboard shows running sandboxes with a terminal, file browser, and process list.

Shared settings

Images and resources.

Getting started

Core concepts

CLI reference

Examples

Account

Create a sandbox

Reconnect to a running sandbox

Use a running sandbox

Commands and processes

Files

Ports and network

Snapshots

Async

Sandbox options

Docker inside a sandbox

Stop and clean up

Shared settings

​Create a sandbox

​Reconnect to a running sandbox

​Use a running sandbox

​Commands and processes

​Files

​Ports and network

​Snapshots

​Async

​Sandbox options

​Docker inside a sandbox

​Stop and clean up

​Shared settings

Create a sandbox

Reconnect to a running sandbox

Use a running sandbox

Commands and processes

Files

Ports and network

Snapshots

Async

Sandbox options

Docker inside a sandbox

Stop and clean up

Shared settings