Sandweave

Sandweave runs Linux sandboxes for agent training and evaluation. Use Python or the CLI to run code, control a desktop, or interact with a VR game. Sandboxes run on your own workers without host sudo or KVM.

A template defines the installed software, startup services and controls. A sandbox is a running instance of that template. You can use a built-in template, provide a setup script, or write your own template. You can also use a Docker image as its filesystem base.

Install

Inside a Python 3.11+ environment on a Linux x86-64 worker (kernel 5.4 or newer):

uv pip install sandweave

You can also use pip install sandweave.

Creating a local sandbox installs its template on first use. Each project uses its own .sandweave directory unless you choose another storage path. Setup checks your machine and downloads a compatible prebuilt runtime from GitHub Releases. If no matching binary is available, it builds from source. The first installation also downloads the selected template's software, so it needs internet access.

Storage settings belong to the project where you run Sandweave. A different project starts with its own installation. Setup does not search your home or parent directories for runtimes. To share an installation explicitly, set SANDWEAVE_HOME to its storage directory.

Worker-local runtime files honor SANDWEAVE_LOCAL_DIR, then TMPDIR. Set SANDWEAVE_LOCAL_DIR=/scratch/sandweave on the worker to use a disk directory when its default temporary filesystem is RAM-backed. Checkpoint staging is removed after its published copy passes background verification.

To choose storage and prepare a template ahead of time:

sandweave setup

Setup asks what you want to start with and where to store files. The directory can be empty. It installs the template and checks a temporary sandbox. Downloads, installed runtimes and caches stay in the selected directory. Other templates are installed when you first use them. Setup shows live progress, elapsed time and the latest build output. Downloads show byte progress when the server provides a size. Full logs are saved in logs/setup inside your selected directory. See installation details.

To check your installation or fix a problem:

sandweave doctor

Doctor shows the checks for your workload. Select a repair in the terminal menu to apply it, then see the updated results. For scripts and CI, use sandweave doctor --check or sandweave doctor --json without interactive fixes.

Connect sandboxes

from sandweave import Sandbox, create_service_network, delete_service_network

group = create_service_network(target="lab")
api = Sandbox(target="lab", service_network=group, aliases=["api"])
desktop = Sandbox(target="lab", template="gnome", service_network=group,
                  aliases=["desktop"])

Both sandboxes run on the network's worker and can reach each other by alias. networks=["private"] restricts communication to members sharing that name; network="offline" disables internet access while retaining these private links. Any gVisor template can join. Terminate the members before calling delete_service_network(group, target="lab"). See service networks for a complete example and cleanup.

Process visibility and audit

Optional Sandbox(hidepid=2, audit=True) restricts cross-user /proc visibility and records runtime events outside the guest. Both options default off. Export with env.audit_log("episode.jsonl") and check its completeness status. See coverage and privilege requirements.

Run commands

from sandweave import Sandbox

with Sandbox() as env:
    result = env.run("python -c 'print(2 + 2)'")
    print(result.stdout)

This prints 4. The default coding template provides Python, a shell and basic tools, with one virtual CPU and 1 GiB of guest memory. Sandbox(...) waits for the template's services and controls to be ready. Leaving the with block terminates the sandbox and discards unsaved state.

By default, a sandbox also terminates when its creating Python process exits, including a crash or an IPython kernel shutdown. The SDK sends heartbeats automatically every five seconds; remote ownership expires after ten minutes without a successful renewal. To keep an environment running after Python exits, pass detached=True:

env = Sandbox(template="gnome", detached=True)
print(env.id)  # Reconnect later with Sandbox.connect(id).

Detached environments still respect ttl and explicit termination. A with block still terminates a sandbox it creates, including a detached one.

run takes one command string, runs it through /bin/sh -c inside the sandbox by default, and waits for completion. Pipes, redirects, variable expansion and && use the guest shell. The result contains stdout, stderr and returncode. By default, a nonzero exit returns a result. Pass check=True to raise a CommandError instead. Timeouts and sandbox connection failures still raise.

Each call starts a new process. Set command options when you need them:

with Sandbox() as env:
    # Set the working directory and environment for one command.
    result = env.run("echo $MODE", cwd="/workspace", env={"MODE": "eval"})
    print(result.stdout)

    # Read the guest's traceback and exit code.
    result = env.run("python -c 'print(2 / 0)'")
    print(result.stderr)
    print(result.returncode)  # 1

    # Require a command to succeed.
    env.run("python -c 'print(2 + 2)'", check=True)

See command options for shells, timeouts and terminals.

To stream output, use exec:

This is the beginning of the README. Read the rest at the original. Read the full README ↗