# @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](#limitations) for open gaps.

## Install

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

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

Run without installing via npx:

```bash
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:

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

tangle --help
tangle sandbox list
```

Build from this monorepo:

```bash
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`).

Credential lookup precedence:

1. `--api-key` flag
2. `TANGLE_API_KEY` environment variable
3. `~/.tangle/credentials` (populated by `tangle auth login`)

Common commands:

```bash
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`
- `batch`
- `process`
- `fs`

Examples:

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

# sandbox lifecycle
tangle sandbox create --name my-box --environment 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 prompt 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 prompt sbx_123 "triage issues" \
  --connection github:github.issues.search,github.issues.create
tangle agent prompt 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, with no separate
key needed. See [`hub-reference.md`](./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.

```bash
# 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:

```bash
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:

```bash
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.

## Batch Runs

Run each task against one explicitly named backend:

```bash
tangle batch run --tasks tasks.json --backend primary=opencode
```

`tasks.json` is an array of `{ "id": "...", "message": "..." }` objects or an object with a `tasks` array.
At least one `--backend <id=type>` is required with `--tasks` or `--task`.

Repeat `--backend <id=type>` to run every task against multiple backends:

```bash
tangle batch run --tasks tasks.json \
  --backend writer=opencode \
  --backend reviewer=claude-code \
  --stream
```

Backend IDs must be unique and use 1 to 128 letters, numbers, dots, underscores, or hyphens.
Use `--model provider/model` only when one backend is selected.
Each result is identified by both `taskId` and `backendId`.
JSON output reports `totalTasks`, `totalBackends`, `totalExecutions`, `totalSuccess`, `totalFailure`, `totalRetries`, and `successRate`.

Use `--request <file.json>` when each backend needs its own model, profile, server, or lifecycle configuration.
The file uses the same complete request shape as the TypeScript SDK and cannot be combined with inline task or backend flags.

## Provisioning Coverage

`tangle sandbox create` supports environments or container images, resources, temporary GPU leases, lifecycle limits, driver and backend selection, SSH and web terminal, environment variables, secrets, metadata, git clone, BYOS3 storage, and snapshot restore.
Use the `tools`, `permissions`, `network`, and `expose` commands after creation.
Run `tangle sandbox create --help` for the current flag list.

## Limitations

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