JSPM

@tangle-network/sandbox-cli

0.9.4-develop.20260627212650.d82a250
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 3895
  • Score
    100M100P100Q135909F
  • License MIT

CLI for Tangle Sandbox operations

Package Exports

  • @tangle-network/sandbox-cli
  • @tangle-network/sandbox-cli/dist/index.mjs
  • @tangle-network/sandbox-cli/package.json

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@tangle-network/sandbox-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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
  • 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"

# 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

# 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.

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 (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.