@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

Run without installing via npx:

npx @tangle-network/sandbox-cli --help
npx @tangle-network/sandbox-cli sandbox list

Always reference the full package name with npx. An unrelated package named tangle exists on public npm, so npx tangle would resolve to it from a fresh working directory — not to this CLI.

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_... (or set TANGLE_API_KEY / SANDBOX_API_KEY).

Credential lookup precedence:

1. --api-key flag
2. TANGLE_API_KEY or SANDBOX_API_KEY environment variable
3. ~/.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
• 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"

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

Provisioning Coverage

tangle sandbox create exposes the full SDK provisioning surface, including image/environment, resources (CPU, memory, disk), lifetime and idle timeout, driver and backend selection, 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.