@tangle-network/sandbox-cli

CLI for provisioning and operating Tangle sandboxes.

Status

Published to the public npm registry as @tangle-network/sandbox-cli.

• Binary: tangle
• Package path: products/sandbox/cli
• Auth: browser login (default), device-code (--no-browser), and API key
• Test coverage: unit and integration tests run via pnpm --filter @tangle-network/sandbox-cli test

See Limitations for open gaps.

Install

One-liner (requires Node 20+ on PATH):

curl -fsSL https://sandbox.tangle.tools/install.sh | sh

Run without installing via npx:

npx @tangle-network/sandbox-cli --help
npx @tangle-network/sandbox-cli sandbox list
# or the shorter official alias
npx tangle-sandbox --help

Never run bare npx tangle (or npx tangle-cli) — those npm names belong to unrelated third-party packages and would execute someone else's code. The official names are @tangle-network/sandbox-cli and its forwarding alias tangle-sandbox.

Install globally to expose the short tangle binary on PATH:

npm install -g @tangle-network/sandbox-cli
# or
pnpm add -g @tangle-network/sandbox-cli

tangle --help
tangle sandbox list

Build from this monorepo:

pnpm --filter @tangle-network/sandbox-cli build
node products/sandbox/cli/bin/tangle.js --help

Authentication

Three flows are supported:

• Browser login (default): tangle auth login opens a browser to complete OAuth with github, google, or microsoft identity providers.
• Device code: tangle auth login --no-browser for headless environments.
• API key: tangle auth login --api-key sk-tan-... (or set TANGLE_API_KEY; SANDBOX_API_KEY accepted as deprecated alias).

Credential lookup precedence:

1. --api-key flag
2. TANGLE_API_KEY environment variable (preferred)
3. SANDBOX_API_KEY environment variable (deprecated alias, accepted for backwards compatibility)
4. ~/.tangle/credentials (populated by tangle auth login)

Common commands:

tangle auth login
tangle auth status
tangle auth logout
tangle auth profiles

tangle auth login validates the supplied credential against /v1/account/me, which requires a valid token.

Command Surface

Top-level command groups:

• auth
• sandbox
• secret
• exec
• ssh
• agent
• fleet
• snapshot
• usage
• permissions
• backend
• process
• fs

Examples:

# auth
tangle auth login --api-key sk_...

# sandbox lifecycle
tangle sandbox create --name my-box --image node:20 --ssh
tangle sandbox list
tangle sandbox get sbx_123
tangle sandbox stop sbx_123
tangle sandbox resume sbx_123
tangle sandbox delete sbx_123

# execution
tangle exec sbx_123 "npm test"
tangle ssh sbx_123
tangle agent prompt sbx_123 "Summarize this repo"
tangle agent task sbx_123 "Fix the failing tests"
tangle fleet create --count 4 --coordinator

# grant hub connections to the agent (see hub-reference.md for the 3 modes).
# the connection is an id or a provider name (resolved via `tangle hub connections`).
tangle agent task sbx_123 "triage issues" \
  --connection github:github.issues.search,github.issues.create
tangle agent task sbx_123 "file the report" --connection github:* --allow-writes

# temporary GPU for an eval; omitted provider picks the cheapest configured cloud
tangle sandbox gpu run sbx_123 \
  --accelerator-kind nvidia-3090 \
  --accelerator-memory 24000 \
  --max-spend-usd 1 \
  --max-lifetime 900 \
  --idle-timeout 120 \
  -- python eval.py

# state and operations
tangle secret list
tangle snapshot list sbx_123
tangle process list sbx_123
tangle fs ls sbx_123 /workspace

Hub commands (tangle hub …) and tangle agent --connection auto-mint a short-lived platform Hub key from your tangle auth login session — no separate key needed. See hub-reference.md for the --connection grant modes, --allow-writes, and permissions revert-writes.

Temporary GPUs

Keep the base sandbox cheap and attach a GPU only while the accelerated command runs. Omit --provider to let Tangle choose the cheapest configured GPU cloud. Always set a spend cap and lifetime.

# Attach, run one command, and destroy the lease.
tangle sandbox gpu run sbx_123 \
  --accelerator-kind nvidia-3090 \
  --accelerator-memory 24000 \
  --max-spend-usd 1 \
  --max-lifetime 900 \
  --idle-timeout 120 \
  -- python eval.py

For multiple GPU commands, use the manual lifecycle:

tangle sandbox gpu attach sbx_123 \
  --accelerator-kind nvidia-3090 \
  --accelerator-memory 24000 \
  --max-spend-usd 1 \
  --max-lifetime 900 \
  --idle-timeout 120

tangle sandbox gpu list sbx_123
tangle sandbox gpu exec sbx_123 gpu_abc -- python eval.py
tangle sandbox gpu detach sbx_123 gpu_abc

Create-time GPU flags are a shortcut over the same lease lifecycle:

tangle sandbox create --name gpu-eval \
  --accelerator-kind nvidia-3090 \
  --accelerator-memory 24000 \
  --gpu-max-spend-usd 1 \
  --gpu-max-lifetime 900 \
  --gpu-idle-timeout 120

The final detach output includes billed seconds and customer cost. Use tangle usage to inspect account-level GPU seconds and GPU spend.

Provisioning Coverage

tangle sandbox create exposes the full SDK provisioning surface, including image/environment, resources (CPU, memory, disk), temporary GPU leases, lifetime and idle timeout, driver and backend selection (opencode, claude-code, codex, cursor, amp, and other registry backends), SSH and web terminal, env and secret injection, metadata, initial permissions, git clone, tool pre-install, BYOS3 storage, snapshot restore, and outbound network controls. Run tangle sandbox create --help for the canonical flag list.

Limitations

• snapshot restore creates a new sandbox from a snapshot; the command signature suggests in-place restore.

Design Follow-Up

For the architecture review, parity checklist, and auth flow spec, see CHECKLIST.md.