Sandboxes

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()

uv run python sandbox_demo.py prints exit code 0 and the sandbox’s Python version. A sandbox is a container in the cloud that your code starts, drives, and terminates, for running generated code, testing a patch, or giving an agent a development environment. It 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.

Run 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().

Read and write 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")

Give a sandbox the 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.

Snapshot and restore

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(...).

Call it from async code

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

Configure a sandbox

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.

Run 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 a sandbox

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.

Set what every workload shares

Images and resources.

Getting started

Core concepts

CLI reference

Examples

Account