@tangle-network/sandbox-cli 0.3.3 → 0.4.0

package/README.md

@@ -86,6 +86,7 @@ Top-level command groups:
 - `exec`
 - `ssh`
 - `agent`
+- `fleet`
 - `snapshot`
 - `usage`
 - `permissions`
@@ -112,13 +113,23 @@ 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"
+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 task sbx_123 "triage issues" \
-  --connection github:github.issues.listIssues,github.issues.create
+  --connection github:github.issues.search,github.issues.create
 tangle agent task 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
@@ -131,9 +142,55 @@ short-lived platform Hub key from your `tangle auth login` session — no separa
 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.
+
 ## 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.
+`tangle sandbox create` exposes the full SDK provisioning surface, including image/environment, resources (CPU, memory, disk), temporary GPU leases, 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
 

package/SKILL.md

@@ -67,6 +67,44 @@ tangle sandbox expose <id> --port 3000
 tangle sandbox urls <id>
 ```
 
+## Temporary GPUs
+
+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.
+
+```bash
+# One-shot eval: attach GPU, run command, always destroy the lease.
+tangle sandbox gpu run <sandbox-id> \
+  --accelerator-kind nvidia-3090 \
+  --accelerator-memory 24000 \
+  --max-spend-usd 1 \
+  --max-lifetime 900 \
+  --idle-timeout 120 \
+  -- python eval.py
+
+# Manual lifecycle when the agent needs multiple GPU commands.
+tangle sandbox gpu attach <sandbox-id> \
+  --accelerator-kind nvidia-3090 \
+  --accelerator-memory 24000 \
+  --max-spend-usd 1 \
+  --max-lifetime 900 \
+  --idle-timeout 120
+tangle sandbox gpu exec <sandbox-id> <gpu-lease-id> -- python eval.py
+tangle sandbox gpu detach <sandbox-id> <gpu-lease-id>
+```
+
+For fleets, put the same GPU lease cap on every worker:
+
+```bash
+tangle fleet create --count 4 \
+  --accelerator-kind nvidia-3090 \
+  --accelerator-memory 24000 \
+  --gpu-max-spend-usd 1 \
+  --gpu-max-lifetime 900 \
+  --gpu-idle-timeout 120
+```
+
 ## Hub — Full Workflow
 
 Hub lets agents use connected provider tools (GitHub, etc.) through Tangle without seeing provider OAuth tokens.
@@ -98,7 +136,7 @@ tangle hub tools sources --json
 tangle hub tools search "github issues" --provider github --json
 
 # Describe a tool to see input/output schemas
-tangle hub tools describe github.issues.listIssues --json
+tangle hub tools describe github.issues.search --json
 ```
 
 ### Tool Execution
@@ -107,8 +145,8 @@ Two equivalent commands — `call` and `exec`:
 
 ```bash
 # Basic call: <path tokens...> <json-input>
-tangle hub call github issues listIssues '{"owner":"tangle-network","repo":"agent-dev-container"}'
-tangle hub exec github.issues.listIssues '{"owner":"tangle-network","repo":"agent-dev-container"}'
+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"}'
 
 # With explicit connection
 tangle hub call github issues createIssue '{"owner":"foo","repo":"bar","title":"Fix bug"}' --connection conn_xxx
@@ -125,7 +163,7 @@ tangle hub approvals approve <approval-id>
 tangle hub approvals deny <approval-id>
 
 # Set policy to always allow (skip future approvals)
-tangle hub permissions set --connection conn_xxx --action github.issues.listIssues --decision allow
+tangle hub permissions set --connection conn_xxx --action github.issues.search --decision allow
 
 # Set policy to always deny (block tool)
 tangle hub permissions set --connection conn_xxx --action github.issues.deleteIssue --decision deny
@@ -221,6 +259,9 @@ 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.
+
 ```bash
 tangle workflows validate workflow.yml
 tangle workflows schema              # print JSON Schema
@@ -228,7 +269,17 @@ tangle workflows create workflow.yml
 tangle workflows list
 tangle workflows get <id>
 tangle workflows update <id> workflow.yml
+tangle workflows enable <id>
+tangle workflows disable <id>
 tangle workflows delete <id>
+
+# Runs
+tangle workflows run <id>                                   # trigger a run
+tangle workflows run <id> --input pull_request.number=123   # with trigger inputs
+tangle workflows run <id> --wait                            # wait + print result
+tangle workflows runs <id>                                  # run history
+tangle workflows run-detail <id> <runId>                    # single-run detail
+tangle workflows events <id> <runId>                        # tail live progress
 ```
 
 ## Other Commands
@@ -287,7 +338,7 @@ tangle permissions add <sandboxId> --userId <userId> --role editor
 | Goal | Commands |
 |------|----------|
 | Spin up sandbox, run agent | `tangle sandbox create --name X` → `tangle agent task <id> "..."` |
-| Connect GitHub, read issues | `tangle hub connect github` → `tangle hub tools search "issues" --provider github` → `tangle hub call github issues listIssues '{"owner":"X","repo":"Y"}'` |
+| Connect GitHub, read issues | `tangle hub connect github` → `tangle hub tools search "issues" --provider github` → `tangle hub call github issues search '{"q":"repo:X/Y is:issue"}'` |
 | Push code from sandbox to GitHub | `tangle hub connect github` → `tangle git add <id> files` → `tangle git commit <id> -m "msg"` → `tangle git push <id>` |
 | Save and restore state | `tangle snapshot create <id>` → ...work... → `tangle snapshot revert <id> <snap-id>` |
 | Set secret for agent use | `tangle secret create GITHUB_TOKEN "..."` → agent reads via `process.env.GITHUB_TOKEN` |