Como usar
- Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
- Consulte no original as ferramentas, credenciais e ambientes necessários.
- Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/yzailab/delta-infra-cli --skill delta-sharedAntes de começar
- A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
- Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.
delta-cli Shared Rules
General guidance for AI agents using delta-cli. Core principles: check, do not guess or expose credentials.
Before any operation
- Verify the server address:
delta-cli config show- Inspect the local authentication configuration:
delta-cli auth status- If
auth statusreportsmethod: tokenormethod: apikey, a credential is configured locally; run the requested command directly without logging in or initialising configuration again. auth statusreads local configuration and environment overrides; it does not validate the credential with the remote server. If it reportsmethod: none, follow “Complete configuration” below. If a requested command returnserror.type: authorpermission, 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:
delta-cli config init --base-url <server-url> --token <token>
# For an API key:
delta-cli config init --base-url <server-url> --apikey <api-key>Do not use interactive config init (without flags), as it may hang when stdin is unavailable.
Priority of information sources
- Environment variables:
DELTA_INFRA_BASE_URL,DELTA_INFRA_TOKEN,DELTA_INFRA_API_KEY base_url,token, andapikeyin~/.delta-infra/config.json(environment values override file values)- Default value: only
base_urlhas an internal default - 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 <credential> 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
delta-cli usageThis 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 touser_idif missing)data.user_id: user IDdata.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
delta-cli quota # the current account
delta-cli quota --pool # parent account only: sub-account hardware allocation poolThrough 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 theallowed_gpu_providers/allowed_gpu_types/allowed_gpu_imagesallowlists, plusdenied_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 withlimit/used/remaining.data.active_sandboxes/data.gpu_running_seconds: current occupancy included inused.
`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 finishandsandbox writewill affect. ~/.delta-infra/config.jsonmust have0600permissions; do not loosen them manually.- The sandbox must be destroyed explicitly: after calling
sandbox create, callsandbox killbefore the current task ends (usefinishwhen results must be preserved). Sandboxes do get reclaimed automatically (default--max-lifeis 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
{"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.typeis 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.hintmay be shown to the user. Act on it rather than retrying blindly: for a failedsandbox createthe 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_ididentifies the same failure in the server log; quote it when reporting the failure.- On a failed
sandbox createfrom a new server,error.detailscarries structured diagnostics:diagnostics_version,stage,retryable(whether a retry can help),suggested_actions, and a nesteddetailsmap (for examplesuggested_gpu_types,provider_label). When the CLI has no built-in hint for the error code, the server-providedhintis 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 |
| contentintegritymismatch / contentsizemismatch | 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 |
| unknownexecutionstate | 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:
delta-cli upgradeCommon 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 <id> --execution-id <exec_id>; cancel the still-running command with sandbox cancel <id> --execution-id <exec_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 <id> --execution-id <exec_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 |