Package Exports

@tangle-network/sandbox-cli
@tangle-network/sandbox-cli/dist/index.mjs

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

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-tan-... (or set TANGLE_API_KEY; SANDBOX_API_KEY accepted as deprecated alias).

Credential lookup precedence:

--api-key flag
TANGLE_API_KEY environment variable (preferred)
SANDBOX_API_KEY environment variable (deprecated alias, accepted for backwards compatibility)
~/.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 (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.