@tangle-network/sandbox-cli 0.21.1-develop.20260813074026.e3d841b → 0.21.1

package/README.md

@@ -15,7 +15,7 @@ See [Limitations](#limitations) for open gaps.
 
 ## Install
 
-One-liner (requires Node 20+ on PATH):
+One-liner (requires Node on PATH matching the package's [`engines` metadata](./package.json)):
 
 ```bash
 curl -fsSL https://sandbox.tangle.tools/install.sh | sh
@@ -52,6 +52,43 @@ pnpm --filter @tangle-network/sandbox-cli build
 node products/sandbox/cli/bin/tangle.js --help
 ```
 
+## Local graphs
+
+Save a graph in a repository's `.tangle/graphs/<name>.yaml` or in
+`~/.tangle/graphs/<name>.yaml`. Repository graphs take precedence. The packaged
+[`haiku-review.yaml`](./examples/haiku-review.yaml) contains a writer, an independent
+critic and a declared completion check.
+
+```bash
+tangle graph new "Write and independently judge a haiku" --name haiku-review
+tangle graph run haiku-review --dry-run
+tangle graph run haiku-review
+```
+
+Graphs use the selected harness's native subscription login. Set `seat` in
+`~/.tangle/config.json` to keep a default; `--seat` overrides it for every node.
+A graph with no integration needs requires no Tangle login. Validation resolves
+seats and needs before starting agents. Missing connections name the provider
+and its `tangle hub connect <provider>` command.
+
+Progress goes to stderr; `--json` returns the result or the shared error contract
+on stdout. Run journals live under `~/.tangle/runs/<run-id>`, and graph history
+lives in `~/.tangle/graph-registry`. Unknown token and cost totals remain `null`.
+
+## Supervisor accounting
+
+`tangle supervise` reports measured tokens and cost for successful and failed runs.
+A run without a winner can still incur cost.
+Unknown totals display as `Unavailable` and appear as `null` in JSON output.
+
+## Workflow inputs
+
+Use `tangle workflows run <id> --input-file ~/.tangle/params/code-fix.json --wait`
+to run a stored preset. The file is a flat JSON object of string values, such as
+`{"repo":"o/r","base":"develop","change":"fix the parser"}`. Repeatable
+`--input key=value` flags override matching file keys. Invalid files fail before
+authentication or run admission; `--json` errors include `code`, `cause`, and `fix`.
+
 ## Authentication
 
 Three flows are supported:
@@ -63,8 +100,14 @@ Three flows are supported:
 Credential lookup precedence:
 
 1. `--api-key` flag
-2. `TANGLE_API_KEY` environment variable
-3. `~/.tangle/credentials` (populated by `tangle auth login`)
+2. `TANGLE_API_KEY_FILE` managed credential file
+3. `TANGLE_API_KEY` environment variable
+4. `~/.tangle/credentials` (populated by `tangle auth login`)
+
+The sidecar publishes refreshed delegated credentials through `TANGLE_API_KEY_FILE`.
+The CLI reads this file for each request, including requests from an existing client.
+A configured file that is missing, unreadable, or malformed fails without falling back to an older key.
+A verified Sandbox request can install a new source credential; an expired source cannot renew itself unattended.
 
 Common commands:
 
@@ -77,6 +120,50 @@ tangle auth profiles
 
 `tangle auth login` validates the supplied credential against `/v1/account/me`, which requires a valid token.
 
+### The two surfaces
+
+Commands address one of two services, and the two accept different credentials.
+
+| Surface | Command families | Credential |
+|---|---|---|
+| Sandbox API | `sandbox`, `exec`, `ssh`, `fs`, `process`, `snapshot`, `secret`, `agent`, `fleet`, `batch`, `usage` | the session `tangle auth login` stores, or an `sk-tan-*` key |
+| Platform control plane (`id.tangle.tools`) | `keys`, `workflows`, `hub` | an `sk-tan-*` key only |
+
+The platform does not accept the sandbox session: it belongs to a different
+audience. After a browser login the CLI therefore mints a short-lived platform
+key from that session on the first platform command, caches it in the same
+credential store, and replaces it before it expires. Nothing durable is written
+for a surface you never use, and no long-lived key sits on disk.
+
+An `sk-tan-*` key is used exactly as supplied on both surfaces, whether it
+arrives through `--api-key`, `TANGLE_API_KEY`, or `tangle auth login --api-key`,
+so a spawned sandbox and a CI job keep the credential they were given and no
+mint replaces it. `TANGLE_HUB_CAPABILITY_TOKEN` serves the `hub` commands only.
+
+### What the minted credential may do
+
+The minted key lives for minutes, so the platform refuses key creation and
+revocation through it: a credential that short must not add or destroy authority
+that outlasts it.
+
+- `tangle keys list` works after `tangle auth login`.
+- `tangle keys create` and `tangle keys revoke` need a key you minted yourself:
+  set `TANGLE_API_KEY`, run `tangle auth login --api-key sk-tan-…`, or mint the
+  key in the web console.
+
+Everything else on the control plane — `tangle workflows`, `tangle hub` — works
+from the login alone.
+
+`tangle auth status` reports both surfaces. It exits non-zero when either one
+REFUSES the stored credential — a behaviour change for a script that gated on
+the old sandbox-only check, and the point of it: the platform rejecting the
+credential used to be reported as success. An unreachable platform is a
+different answer and exits zero, because an outage says nothing about the
+credential; read `platform.reachable` in `--json` to gate platform work.
+`--base-url` names the sandbox host for BOTH halves: the session is checked
+there, and the platform credential is minted there, so the two lines of the
+answer always describe one deployment.
+
 ## Command Surface
 
 Top-level command groups:
@@ -90,7 +177,6 @@ Top-level command groups:
 - `fleet`
 - `snapshot`
 - `usage`
-- `permissions`
 - `backend`
 - `batch`
 - `process`
@@ -221,9 +307,19 @@ The file uses the same complete request shape as the TypeScript SDK and cannot b
 ## 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.
+Use the `sandbox network` and `sandbox 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.
+
+## Compliance posture is not a flag
+
+No CLI command takes a `--compliance` / HIPAA / PHI option, by design: a
+caller-asserted flag could dodge the platform's observability gates or
+claim a protection it never granted. The platform derives the posture from
+the credential's verified attribution and pins it server-side. Reads
+(`sandbox list`, `sandbox get`) surface it as the read-only `compliance:
+{ hipaa: true }` echo field — absent means the platform made no claim, and
+`hipaa: false` never appears.

package/SKILL.md

@@ -12,7 +12,12 @@ All commands support `--help` for inline reference.
 
 ## Auth
 
-Generic command auth modes, resolved in order:
+Commands address one of two services. Sandbox commands (`sandbox`, `exec`,
+`ssh`, `fs`, `snapshot`, `secret`, `agent`, …) address the sandbox API. Platform
+commands (`keys`, `workflows`, `hub`) address the control plane at
+`id.tangle.tools`, which accepts only an `sk-tan-*` key.
+
+Sandbox command auth modes, resolved in order:
 
 | Priority | Source | Set via |
 |----------|--------|--------|
@@ -20,14 +25,18 @@ Generic command auth modes, resolved in order:
 | 2 | Env var | `TANGLE_API_KEY` |
 | 3 | Profile store | `tangle auth login` (keychain or file) |
 
-Hub commands resolve auth in this order:
+Platform commands resolve auth in the same order, with one step added: the
+session that `tangle auth login` stores is not a platform credential, so the CLI
+mints a short-lived platform key from it on first use and refreshes it as
+needed. Hub commands also accept `TANGLE_HUB_CAPABILITY_TOKEN`, ranked directly
+below `--api-key`; other platform commands do not, because that token
+authenticates `/v1/hub/exec` alone.
 
-| Priority | Source | Set via |
-|----------|--------|--------|
-| 1 | CLI flag | `--api-key <key>` |
-| 2 | Hub capability | `TANGLE_HUB_CAPABILITY_TOKEN` |
-| 3 | Env var | `TANGLE_API_KEY` |
-| 4 | Profile store | `tangle auth login` (keychain or file) |
+The minted key lives for minutes, so the platform refuses key creation and
+revocation through it. `tangle keys list` works from a browser login; `tangle
+keys create` and `tangle keys revoke` need a key you minted yourself
+(`TANGLE_API_KEY`, `tangle auth login --api-key`, or the web console). A stored
+`sk-tan-*` is presented as-is and never minted over.
 
 **Inside a sandbox:** `tangle` is automatically authenticated.
 No extra authentication is needed.
@@ -75,6 +84,24 @@ Use a normal sandbox first, then attach a GPU only for the work that needs it.
 Omit `--provider` to use the cheapest configured GPU cloud.
 Always set a spend cap and lifetime.
 
+Check which GPU clouds work before attaching. `gpu providers` lists every supported provider with its state (`ready`, `credential-invalid`, `unverified`, `not-configured`, `disabled`), the orchestrator variables it needs, and a live price for the accelerator you name:
+
+```bash
+tangle sandbox gpu providers <sandbox-id> --accelerator-kind nvidia-h100
+```
+
+| Provider | `--provider` | Orchestrator variables |
+| --- | --- | --- |
+| RunPod | `runpod` | `RUNPOD_API_KEY` |
+| Vast.ai | `vast-ai` | `VAST_API_KEY` |
+| Lambda | `lambda-labs` | `LAMBDA_API_KEY` |
+| Modal | `modal` | `MODAL_TOKEN_ID`, `MODAL_TOKEN_SECRET` |
+
+TensorDock, Paperspace, AWS, GCP, Azure, Crusoe and Fluidstack are also supported; `gpu providers` prints the variables each needs.
+Setting a provider's variables enables it; `GPU_LEASE_PROVIDERS` only narrows the set.
+An attach with no usable provider fails with 503 `GPU_PROVIDER_NOT_CONFIGURED` naming the variables to set; a refused key shows as `credential-invalid` and is never selected.
+Modal offers T4, L4, A10G, L40S, A100, H100, H200 and B200, not consumer cards such as the RTX 3090.
+
 ```bash
 # One-shot eval: attach GPU, run command, always destroy the lease.
 tangle sandbox gpu run <sandbox-id> \
@@ -147,8 +174,8 @@ Two equivalent commands are available: `call` and `exec`.
 
 ```bash
 # Basic call: <path tokens...> <json-input>
-tangle hub call github issues search '{"q":"repo:tangle-network/agent-dev-container is:issue"}'
-tangle hub exec github.issues.search '{"q":"repo:tangle-network/agent-dev-container is:issue"}'
+tangle hub call github issues search '{"q":"repo:tangle-network/agent-container is:issue"}'
+tangle hub exec github.issues.search '{"q":"repo:tangle-network/agent-container is:issue"}'
 
 # With explicit connection
 tangle hub call github issues createIssue '{"owner":"foo","repo":"bar","title":"Fix bug"}' --connection conn_xxx
@@ -257,7 +284,13 @@ tangle team invitations [team]  # List pending/historical invitations
 ## Workflows
 
 Authenticate with the `sk-tan-*` API key (`TANGLE_API_KEY`), same as the other
-platform commands, not a hub capability token.
+platform commands, not a hub capability token. These commands address the
+platform control plane, not the sandbox API. The host resolves from
+`--base-url`, then `TANGLE_HUB_URL` (which a spawned sandbox injects to name
+its own hub, so it wins over an ambient value), then `TANGLE_PLATFORM_URL`,
+then `https://id.tangle.tools`. On `workflows`,
+`--base-url` names the PLATFORM host — unlike `tangle keys`, where `--base-url`
+is the sandbox API and `--platform-url` is the platform.
 
 Authoring a workflow (graph topology, guards, joins, KV state, decisions):
 https://sandbox.tangle.tools/docs/workflows
@@ -266,7 +299,9 @@ https://sandbox.tangle.tools/docs/workflows
 tangle workflows validate workflow.yml
 tangle workflows schema              # print JSON Schema
 tangle workflows create workflow.yml
+tangle workflows apply workflow.yml  # create or update, matched by the definition's name
 tangle workflows list
+tangle workflows fleet               # run tallies over a trailing window, failing first
 tangle workflows get <id>
 tangle workflows update <id> workflow.yml
 tangle workflows enable <id>
@@ -291,6 +326,7 @@ tangle workflows runs <id>                                  # run history
 tangle workflows run-detail <id> <runId>                    # single-run detail
 tangle workflows events <id> <runId>                        # tail live progress
 tangle workflows cancel <id> <runId>                        # cancel a queued/running run
+tangle workflows retry <id> <runId>                         # re-run a failed run with the same trigger context
 
 # Cross-run KV state
 tangle workflows kv list <id>
@@ -328,10 +364,6 @@ tangle backend restart <sandboxId>
 tangle env ls
 tangle env get <id>
 
-# Tools (mise)
-tangle tools ls <id>
-tangle tools install <id> python 3.12
-
 # Batch tasks across sandboxes
 tangle batch run --tasks tasks.json
 tangle batch run --tasks tasks.json --backend writer=opencode --backend reviewer=claude-code --stream
@@ -354,10 +386,6 @@ tangle mcp serve <id>
 tangle preview ls <id>
 tangle preview create <id> 3000
 tangle preview rm <id> <preview-id>
-
-# Sandbox user permissions
-tangle permissions list <sandboxId>
-tangle permissions add <sandboxId> --userId <userId> --role editor
 ```
 
 ## Common Workflows