CLI

The CLI uses the same sandbox lifecycle and command semantics as Python. Use sandweave --help or add --help to a subcommand for its complete options.

Installation

sandweave setup
sandweave doctor
sandweave doctor --check

setup chooses storage and prepares templates. doctor checks the installation and offers interactive repairs. --check only runs checks.

Run one command

sandweave run --template coding -- "python -c 'print(2 + 2)'"
sandweave run --image docker://python:3.12-slim -- "python --version"

This creates a sandbox, runs the command, and terminates the sandbox. Output and exit status pass through to your terminal. Supply one quoted command string after --; the guest shell interprets it.

For a cluster sandbox, select direct worker traffic with --connection direct:

sandweave run --target lab --connection direct -- "python --version"
sandweave exec --target lab --connection direct SANDBOX_ID -- "python --version"
sandweave desktop screenshot SANDBOX_ID --target lab --connection direct --output screen.png

This also works with create, shell, desktop action/step, and pool exec. The default is cluster. See direct connections for worker reachability and reconnect behavior.

Add disk-backed memory with its own directory on the worker:

sandweave run --memory 4GiB --disk-memory 16GiB --disk-path /scratch/my-memory -- "free -h"

See disk-backed memory for host requirements.

To count less guest RAM for admission while retaining a higher allocation limit:

sandweave run --memory 16GiB --memory-reservation 4GiB --experimental-memory-sharing -- "free -h"

This explicitly opts into experimental memory sharing and possible host out-of-memory failures when combined usage exceeds available RAM.

Use one proxy from a private JSON list of proxy URLs:

sandweave run --proxy-file ./proxies.json -- "curl -s https://api.ipify.org"

This also works with create and pool create. See proxy networking for the file format and routing behavior.

For a region-grouped proxy file, distribute one region's proxies across a pool:

sandweave pool create --name research --size 8 --proxy-file ./proxies.json --proxy-policy same_region

--proxy-policy accepts random, round_robin, same_proxy, or same_region. Add --proxy-region uk to restrict that policy to the supplied uk group. These options also work with standalone create and run, which select one eligible proxy. See proxy policies.

Create a persistent desktop

sandweave create --template gnome --name workbench
sandweave info workbench
sandweave desktop screenshot workbench --output screen.png

CLI create uses detached=True. It leaves the sandbox running until its TTL expires or you stop or terminate it.

Runtime heap profiles

Create a diagnostic sandbox with --profiling, then save its heap on this client:

sandweave create --template docker --profiling
sandweave profile SANDBOX_ID --output heap.pprof

Use --target as usual for remote sandboxes. See runtime memory diagnosis.

Pause, save, or terminate

sandweave pause workbench
sandweave resume workbench
sandweave cache save workbench my-workbench
sandweave terminate workbench

To save a checkpoint before stopping, use sandweave stop workbench instead of terminate. Restore a named filesystem cache with:

sandweave create --cache my-workbench --name restored

Sandbox IDs also work wherever these examples use a name.

Clusters

sandweave cluster start lab --no-worker
sandweave cluster instructions lab
sandweave cluster workers lab
sandweave cluster status lab

Startup prints the complete worker join commands and dashboard link. Copy a printed join command onto each worker. See connect a cluster.

sandweave dashboard lab
sandweave cluster stop lab

Cluster pools

sandweave pool create --target lab --name coding --size 16 --warm 4
sandweave pool status coding --target lab
sandweave pool exec coding --target lab -- "python --version"
sandweave pool update coding --target lab --size 32 --warm 8
sandweave pool close coding --target lab

Jobs

sandweave job submit --target lab -- "python -c 'print(2 + 2)'"

The command prints the job ID. Substitute that ID in these commands:

sandweave job status JOB_ID --target lab
sandweave job result JOB_ID --target lab

Desktop recording

sandweave create --template gnome --record
sandweave recording status SANDBOX_ID
sandweave terminate SANDBOX_ID
sandweave recording download SANDBOX_ID --output ./episode
sandweave recording delete SANDBOX_ID

Replace SANDBOX_ID with the ID printed by create. Add --target lab to each command for a cluster. --record also works with run and pool create. Recordings remain available after termination until explicitly deleted. Use sandweave recording stop SANDBOX_ID to finish recording and keep the desktop. See desktop recording for timing and recovery.

Stereo recording

sandweave create --template vr/gunspinning --gpu auto --name gunspin
sandweave vr record gunspin --duration 30 --output ./episode
sandweave terminate gunspin

The VR template needs prepared game files and an available GPU. Recording exports both eyes and a synchronized side-by-side preview. See VR games.

Writable storage

New sandboxes use disk-backed writable files. Choose their directory on the worker:

sandweave run --storage-path /data/sandbox-disks -- "python --version"

Use --storage memory to retain RAM-backed writable files. This is independent of --disk-memory and --disk-path, which configure application memory.

Process visibility and audit

Use sandweave create --hidepid 2 --audit to opt into hidden cross-user process entries and protected runtime audit. --hidepid 0 --no-audit explicitly disables template defaults. Export records through Sandbox.connect(id).audit_log(path). See process visibility and audit for privilege requirements, coverage, and snapshot support.