Sandboxes

Ephemeral isolated containers for running untrusted code, multi-step scripts, or snapshotted workflows.

Create a sandbox

A Sandbox is an ephemeral container that runs a command. Unlike a task, it has no gworker App — it is created on demand from any task or local script.

python
1import gworker_client as gw2 3sb = gw.Sandbox.create(4    cmd=["python", "-c", "print('hello from sandbox')"],5    image=gw.Image.base("python:3.12-slim").pip_install("numpy"),6    timeout=60.0,7)8exit_code = sb.wait()9print(exit_code)  # 0

Run multiple commands

exec() starts another command inside the same running sandbox. All exec() calls share the same filesystem and process namespace.

python
1sb = gw.Sandbox.create(2    cmd=["bash"],3    image=gw.Image.base("ubuntu:22.04"),4)5proc = sb.exec(["pip", "install", "httpx"])6proc.wait()7 8proc2 = sb.exec(["python", "-c", "import httpx; print(httpx.get('https://httpbin.org/ip').json())"])9proc2.wait()10sb.terminate()

Snapshots

Capture the container's memory state with snapshot(). Restore from it later with Sandbox.create(snapshot=...) to skip cold-start setup — useful for workflows that repeat the same expensive initialisation.

python
1# Build once, snapshot2sb = gw.Sandbox.create(cmd=["bash"], image=my_image)3proc = sb.exec(["python", "setup_env.py"])4proc.wait()5snap = sb.snapshot()  # capture memory state6 7# Restore multiple times from the snapshot8for item in batch:9    worker = gw.Sandbox.create(snapshot=snap)10    proc = worker.exec(["python", "process.py", item])11    proc.wait()12    worker.terminate()

Secrets and volumes

Inject secrets and mount volumes into a sandbox the same way as tasks.

python
1sb = gw.Sandbox.create(2    cmd=["python", "train.py"],3    secrets=[gw.Secret.from_name("hf-token")],4    volumes={"/data": gw.Volume.from_name("training-data")},5    timeout=3600.0,6)7sb.wait()