Sandboxes

A sandbox is a disposable computer. Create it, run code in it, and destroy it when you are done. This page is the operator's view; the API is the product.

Creating

box = af.sandboxes.create(
    image="agentforge:latest",
    cpu=2,
    memory_mb=1024,
    disk_mb=2048,
    timeout_seconds=900,
)

Public workloads always run on Firecracker. If you request another runtime the control plane decides, and the response tells you what it chose via x-agentforge-selection-reason.

Running code

result = box.exec(["python", "-c", "print(1 + 1)"])
result["stdout"]     # "2"
result["exit_code"]  # 0
result["timed_out"]  # False

Exec is bounded by wall-clock time and by output size, and a string is accepted as shorthand for a shell command.

Files

box.write_file("/workspace/main.py", "print('hi')\n")
box.read_file("/workspace/main.py")
box.make_directory("/workspace/out")
box.delete_file("/workspace/tmp")
box.list_files("/workspace")

Snapshots

snap = box.snapshot()
box.restore(snap)

A workspace snapshot is a portable archive and the unit of recovery. It does not capture running VM memory.

Inspecting

af.sandboxes.list()
af.sandboxes.get(box.id)

Each sandbox reports its state, runtime, allocated resources, the runtime owner, and when it was created and last updated.

Destroying

box.destroy()

Destroying releases the machine, the storage reservation and the quota it was holding. Sandboxes that are not destroyed are removed when their lifetime expires.

What is running right now

The dashboard lists your live sandboxes with their state, runtime, size and age. Anything that looks unfamiliar should be revoked or destroyed immediately — see security.