--- name: delta-shared description: "delta-cli shared global rules: configuration and authentication checks, security boundaries, error handling, and sandbox destruction." --- # delta-cli Shared Rules General guidance for AI agents using `delta-cli`. Core principles: **check, do not guess or expose credentials**. ## Before any operation 1. Verify the server address: ```bash delta-cli config show ``` 2. Inspect the local authentication configuration: ```bash delta-cli auth status ``` - If `auth status` reports `method: token` or `method: apikey`, a credential is configured locally; **run the requested command directly without logging in or initialising configuration again**. - `auth status` reads local configuration and environment overrides; it does not validate the credential with the remote server. If it reports `method: none`, follow “Complete configuration” below. If a requested command returns `error.type: auth` or `permission`, follow the matching recovery action below. ## Complete configuration If the server address or credentials are missing, **ask the user once**, then initialise with the flag that matches the credential type: ```bash delta-cli config init --base-url --token # For an API key: delta-cli config init --base-url --apikey ``` Do not use interactive `config init` (without flags), as it may hang when stdin is unavailable. ### Priority of information sources 1. Environment variables: `DELTA_INFRA_BASE_URL`, `DELTA_INFRA_TOKEN`, `DELTA_INFRA_API_KEY` 2. `base_url`, `token`, and `apikey` in `~/.delta-infra/config.json` (environment values override file values) 3. Default value: only `base_url` has an internal default 4. If none of the above are available, **you must ask the user**; do not make anything up ### Runtime credentials The CLI sends the effective credential in the `Authorization: Bearer ` header; an API key takes precedence over a token when both are configured. It adds `X-User-Uid` when it can parse a `uid` from the credential as an unverified JWT. ## Querying user information and remaining credits ```bash delta-cli usage ``` This returns the current user's information and remaining credits (through the gateway `/infra/api/users/me`; the CLI automatically attaches the configured credentials). Keep only these three fields in the output: - `data.display_name`: display name (fall back to `user_id` if missing) - `data.user_id`: user ID - `data.resources.credit`: remaining balance in credits `usage` reports **credits only** — it does not include hardware quota. Use `quota` below for that. `username`/`id`/`email`/`role`/`quota`/`group`/`tier`/`status`/`created_at`/`is_admin`, `stats` and its `total_consumed_credits` (in the database's original quota units) are internal fields and must not be exposed externally. ## Querying hardware quota and GPU access ```bash delta-cli quota # the current account delta-cli quota --pool # parent account only: sub-account hardware allocation pool ``` Through the gateway `/infra/api/tasks/resource-quota` (read-only: it does not deduct credits or record a task). The response is the account's **effective** quota, using the same admission rules as sandbox creation: - `data.gpu_access`: `allow_gpu`, and the `allowed_gpu_providers` / `allowed_gpu_types` / `allowed_gpu_images` allowlists, plus `denied_gpu_types` (a parent-set model denylist for sub-accounts). An **empty list means unrestricted**, not "nothing allowed". The denylist takes precedence over the allowlists: a matching model is rejected at create time. - `data.per_sandbox`: the ceiling for one create request (`cpu_cores`, `memory_mib`, `gpu_cards`) — **not** the remaining amount. - `data.account`: per dimension (`gpu_cards`, `gpu_mem_mib`, `cpu_cores`, `memory_mib`, `concurrency`, `gpu_duration_seconds`), each with `limit` / `used` / `remaining`. - `data.active_sandboxes` / `data.gpu_running_seconds`: current occupancy included in `used`. **`null` means unlimited; `0` means zero quota** (for example, GPU cards `0` = no GPU). Never collapse the two. `--pool` returns the parent's `pool` / `allocated` / `remaining` / `effective` plus `unallocated_children` and `warnings`; sub-accounts that inherit their tier do not consume the pool. On a server without the endpoint the command fails with `error.type: not_found` and an upgrade hint; fall back to `usage` (credits only) and the create rejection codes in `delta-sandbox`. ## Security rules - **Never output credentials**: token and API key values must not appear in logs, messages or the terminal. - **Never construct URLs or make HTTP requests yourself**: route all requests through `delta-cli`. - **Do not install the CLI proactively**: if the user says it is not installed, direct them to the README or `install.sh`; do not choose an installation method yourself. - **Confirm intent before write or delete operations**: tell the user what commands such as `sandbox kill`, `sandbox finish` and `sandbox write` will affect. - `~/.delta-infra/config.json` must have `0600` permissions; do not loosen them manually. - **The sandbox must be destroyed explicitly**: after calling `sandbox create`, call `sandbox kill` before the current task ends (use `finish` when results must be preserved). Sandboxes do get reclaimed automatically (default `--max-life` is 30 minutes; private compute starts the clock when create is accepted and the platform reclaims, while third-party compute starts at readiness and the server reclaims at max-life plus up to 10 minutes of grace), but the platform may reclaim early and automatic reclamation does not write back to OSS — relying on it loses artifacts. Do not skip destruction, even if an error occurs. ## JSON output conventions ```json {"ok":true,"data":{...}} {"ok":false,"error":{"type":"auth","message":"...","hint":"...","request_id":"..."}} ``` AI agent parsing rules: - Always check `ok`; do not rely on the exit code alone. - `error.type` is the stable field for branching on: `auth`, `permission`, `not_found`, `validation`, `network`, `api`, `command_failed`, `timeout`, `unknown_execution_state`, `content_integrity_mismatch`, `content_size_mismatch`, `internal`. - `error.hint` may be shown to the user. **Act on it rather than retrying blindly**: for a failed `sandbox create` the hint names the concrete cause and the next step (for example, the image was not cached on the target node — retry, or pick a GPU type whose node already has the image). - `error.request_id` identifies the same failure in the server log; quote it when reporting the failure. - `data.error_code` is the machine-readable reason when the envelope itself is a business error (`code=-1`) or an idempotent no-op success: `sandbox_not_found` (the sandbox no longer exists — do not retry, create a new one), `sandbox_already_gone` with `data.already_gone: true` (`kill`/`finish`/`dispose` on an already-destroyed sandbox — this is success, not a failure), `expose_not_found` (no active tunnel on that port — check `sandbox exposes `), `port_pool_exhausted` (recycle stale tunnels or retry later), `upstream_unavailable` (provider temporarily unreachable — check `sandbox list` before retrying). - On a failed `sandbox create` from a new server, `error.details` carries structured diagnostics: `diagnostics_version`, `stage`, `retryable` (whether a retry can help), `suggested_actions`, and a nested `details` map (for example `suggested_gpu_types`, `provider_label`). When the CLI has no built-in hint for the error code, the server-provided `hint` is used. ## Exit code conventions | Type | Exit Code | Scenario | |------|-----------|----------| | validation | 2 | Invalid flag or argument | | auth | 3 | Not authenticated or authentication failed | | permission | 4 | Insufficient permissions | | not_found | 5 | Sandbox or file does not exist | | network | 6 | DNS, timeout or connection failure | | api | 7 | Server returned a non-2xx response | | command_failed | 8 | Command failed inside the sandbox (non-zero `exit_code` or an error); on the SSE path, an error envelope is appended after the `complete` frame, with the stderr tail in `message` for quick reference | | content_integrity_mismatch / content_size_mismatch | 12 | File-transfer verification failed (sha256 or byte-count mismatch): the file is not byte-exact — retry the transfer instead of using the file | | timeout | 11 | A local wait deadline elapsed (`sandbox run-bg --wait`): the remote command may still be running — `error.details` keeps `sandbox_id`, `execution_id` and `remote_state` (`not_cancelled` / `cancelled` / `cancel_failed`) so it can be queried or cancelled | | unknown_execution_state | 13 | The command's outcome is **unknown** (the stream ended before the `complete` frame, or only an error frame arrived). Never treat this as success and never guess the exit code | | internal | 10 | Internal client error | ## Upgrade check After completing the user's request, if the JSON contains `_notice.update`, you may recommend: ```bash delta-cli upgrade ``` ## Common recovery actions | Error / symptom | Recovery action | |-------------|----------| | `error.type: auth` / `method: none` | Check the server address and local credential configuration. If no credential is configured or the server rejects it, ask the user once for a credential; use `--apikey` for an API key or `--token` for a bearer token, or set the matching `DELTA_INFRA_API_KEY` / `DELTA_INFRA_TOKEN` environment variable. An invalid, expired or unauthorised API key is reported as `error.type: auth` (with a hint to run `delta-cli auth login`) — do not treat it as a server failure or retry the same command unchanged. | | `error.type: permission` | Check whether the current credential has sufficient permissions; if needed, ask for a credential with the required permissions. | | `error.type: not_found` | Check `sandbox_id` / path. If the command was `delta-cli quota` / `quota --pool`, the server predates the hardware-quota endpoint — upgrade it, or fall back to `usage` (credits only) and the create rejection codes | | `error.type: network` | Check `base_url` and network connectivity | | `error.type: validation` | Check required flags and argument formats | | `error.type: command_failed` | Command failed inside the sandbox: the envelope's `message` already includes the stderr tail to help locate the issue quickly; the full `stderr` / `result_summary` are in the `complete` frame. Retry or correct the command | | `error.type: timeout` | A local wait deadline elapsed, **not** a command failure. Read `error.details.execution_id` and query it with `sandbox logs --execution-id `; cancel the still-running command with `sandbox cancel --execution-id ` (or re-run with `--cancel-on-timeout` so the CLI cancels it for you) | | `error.type: unknown_execution_state` | The remote outcome is unknown — the CLI will not guess. Re-check the command with `sandbox logs --execution-id ` (the execution id is in the error details) before deciding whether it succeeded | | `sandbox create` failed (`error.type: api` with a specific `hint`) | Follow the hint — it names the cause and the next step. "the image may not be cached on the target node" → retry once (the pull continues in the background, so later creates succeed) or pick a GPU type whose node already has the image. "check the target node's free disk space" → a retry will not help until an operator frees the node. A failed create leaves no sandbox behind, so retrying is safe. Quote `error.request_id` when reporting it. On new servers `error.details` adds `stage`/`retryable`/`suggested_actions` for a machine-readable retry decision. | | `sandbox create` rejected with `TIER_*` / `SUBACCOUNT_*` | Account/plan quota rejection, not a transient failure — do not retry the same request unchanged. See the quota row in `delta-sandbox`'s recovery table for which dimension to reduce or which model/provider/image to choose. | | Configuration file parsing failed | Check that `~/.delta-infra/config.json` contains valid JSON |