AI Agent Skills Reference

Machine-readable reference for AI agents using clawstainer sandboxes. All commands default to --format auto: JSON when piped (typical agent usage), table in interactive terminals. Pass --format json explicitly to guarantee JSON output. Errors go to stderr as JSON with a non-zero exit code.

Lifecycle

Create a sandbox

clawstainer create [OPTIONS]

Returns (JSON):

{
  "id": "sb-a1b2c3d4",
  "name": "bold-parrot",
  "status": "running",
  "ip": "10.0.0.2",
  "created_at": "2026-03-27T10:30:00Z"
}

The id field is used in all subsequent commands.

Destroy a sandbox

clawstainer destroy <MACHINE_ID> [--format json]
clawstainer destroy --all [--format json]

Returns (JSON):

{
  "machine_id": "sb-a1b2c3d4",
  "status": "destroyed",
  "uptime_seconds": 3600
}

Execute Commands

This is the primary agent interface. Run any shell command inside a sandbox.

clawstainer exec <MACHINE_ID> <COMMAND> [OPTIONS]

Returns (JSON):

{
  "machine_id": "sb-a1b2c3d4",
  "exit_code": 0,
  "stdout": "Hello, world!\n",
  "stderr": "",
  "duration_ms": 42,
  "timed_out": false
}

Optional fields (present when applicable):

Default environment inside sandbox:

Examples:

clawstainer exec sb-xxx "echo hello"
clawstainer exec sb-xxx --timeout 300 "apt-get update && apt-get install -y python3"
clawstainer exec sb-xxx --env API_KEY=secret "python3 app.py"
clawstainer exec sb-xxx --workdir /tmp "ls -la"

Copy Files

Copy files and directories between the host and a sandbox.

clawstainer cp <SRC> <DST>

Use MACHINE_ID:/path for sandbox paths. Plain paths are host paths.

Returns (JSON):

{
  "machine_id": "sb-a1b2c3d4",
  "direction": "pull",
  "src": "/root/output.txt",
  "dst": "./local/"
}

Handles files and directories recursively. Cannot copy between two sandboxes directly.

Provision

Install predefined software components.

clawstainer provision <MACHINE_ID> --components <LIST> [--timeout <SEC>] [--format json]

Returns (JSON):

{
  "machine_id": "sb-a1b2c3d4",
  "results": [
    {"component": "python3", "status": "ok", "duration_ms": 88300},
    {"component": "git", "status": "ok", "duration_ms": 15394}
  ]
}

Available components: python3, nodejs, git, curl, build-essential, docker-cli, ripgrep, jq, claude-code, hermes-agent, openclaw

Bundles: agent-default (python3, nodejs, git, curl, jq, ripgrep), web-dev, ml, openclaw

Each component that fails does NOT block others. Results are reported individually.

Snapshots

Capture a provisioned sandbox for reuse. Avoids re-provisioning on every create.

Create snapshot

clawstainer snapshot create <MACHINE_ID> --name <NAME>

Returns:

{
  "name": "python3-ready",
  "size_bytes": 157286400,
  "created_at": "2026-03-27T10:30:00Z"
}

List snapshots

clawstainer snapshot list [--format json]

Delete snapshot

clawstainer snapshot delete <NAME>

Use snapshot

clawstainer create --name worker --from python3-ready

Typical workflow:

# One-time setup
clawstainer create --name base
clawstainer provision sb-xxx --components python3,git
clawstainer snapshot create sb-xxx --name python3-git
clawstainer destroy sb-xxx

# Reuse (instant, no provisioning)
clawstainer create --name worker-1 --from python3-git
clawstainer create --name worker-2 --from python3-git

Monitoring

List sandboxes

clawstainer list [--format json] [--status running|stopped|all] [--watch <SEC>]

Stats

clawstainer stats                          # Global overview
clawstainer stats <MACHINE_ID>             # Per-sandbox details
clawstainer stats --format json            # JSON output

Exec logs

clawstainer logs <MACHINE_ID> [--last <N>] [--format json]

Fleet Management

Deploy multiple sandboxes from YAML.

clawstainer fleet create --file fleet.yaml [--parallel <N>] [--format json]
clawstainer fleet destroy --all [--format json]
clawstainer fleet destroy --name <GROUP> [--format json]

fleet.yaml format:

machines:
  - name: worker
    count: 5
    memory: 1024
    cpus: 2
    provision: python3
    security: strict        # optional
    cap_add: []             # optional
    cap_drop: [CAP_NET_RAW] # optional
    env_file: .env          # optional

Other

Port forwarding

clawstainer port-forward <MACHINE_ID> <HOST_PORT:SANDBOX_PORT>

Interactive shell (human use)

clawstainer shell <MACHINE_ID> [--user <USER>]

Error Codes

All errors return JSON to stderr:

{"error": "machine_not_found", "message": "No machine with ID 'sb-xyz'", "hint": "Run 'clawstainer list' to see active machines"}

Agent Workflow Pattern

1. create          → get machine ID
2. provision       → install dependencies (or use --from snapshot)
3. cp (push)       → send input files
4. exec            → run commands, read stdout/stderr/exit_code
5. exec            → iterate: write code, run tests, fix errors
6. cp (pull)       → retrieve output files
7. destroy         → clean up

For pipelines with repeated setups, snapshot after step 2 and use --from on subsequent runs.