From ee22c03c3f4c781d61192b1a4814015e8efc6519 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Sun, 12 Jul 2026 15:05:59 +0530 Subject: [PATCH 1/4] docs: rewrite launch docs to match agentsfleet 0.17.0 Rewrites published pages to the docs Constitution (concise, testable, source-verified), adds a pre-commit documentation linter, and syncs error-code, CLI, connector, and quickstart content against Zig, OpenAPI, and CLI source truth. Restores github-pr-reviewer as the quickstart's flagship example now that the upstream fleet-bundle repo is being fixed in a companion PR. Co-Authored-By: Claude Sonnet 5 --- .githooks/pre-commit | 27 ++ Makefile | 25 +- README.md | 27 +- api-reference/error-codes.mdx | 548 ++++++++++++++-------------- api-reference/introduction.mdx | 76 ++-- api-reference/scopes.mdx | 83 +++-- billing/budgets.mdx | 58 +-- billing/plans.mdx | 32 -- changelog.mdx | 16 + cli/agentsfleet.mdx | 629 +++++++-------------------------- cli/configuration.mdx | 93 ++--- cli/flags.mdx | 75 ++-- cli/install.mdx | 95 ++--- concepts.mdx | 151 +++----- concepts/context-lifecycle.mdx | 88 ++--- docs.json | 28 +- fleets/authoring.mdx | 265 ++++---------- fleets/connectors.mdx | 163 +++------ fleets/install.mdx | 117 +++--- fleets/library.mdx | 98 ++--- fleets/overview.mdx | 116 +++--- fleets/running.mdx | 173 +++++---- fleets/secrets.mdx | 182 +++------- fleets/tools.mdx | 168 ++------- fleets/troubleshooting.mdx | 230 +++--------- fleets/webhooks.mdx | 189 +++------- index.mdx | 61 ++-- memory.mdx | 124 ++----- quickstart.mdx | 201 +++++------ scripts/check-documentation.py | 346 ++++++++++++++++++ scripts/test-documentation.py | 169 +++++++++ scripts/test-spec.sh | 119 ------- snippets/contact.mdx | 9 +- workspaces/managing.mdx | 110 +++--- workspaces/overview.mdx | 49 +-- 35 files changed, 2153 insertions(+), 2787 deletions(-) create mode 100755 .githooks/pre-commit delete mode 100644 billing/plans.mdx create mode 100755 scripts/check-documentation.py create mode 100755 scripts/test-documentation.py delete mode 100755 scripts/test-spec.sh diff --git a/.githooks/pre-commit b/.githooks/pre-commit new file mode 100755 index 0000000..bc76da5 --- /dev/null +++ b/.githooks/pre-commit @@ -0,0 +1,27 @@ +#!/usr/bin/env bash +set -euo pipefail + +repo_root="$(git rev-parse --show-toplevel)" +cd "$repo_root" + +staged_paths="$(git diff --cached --name-only --diff-filter=ACMR | sort -u)" +unstaged_paths="$(git diff --name-only --diff-filter=ACMR | sort -u)" +partial_paths="$(comm -12 <(printf '%s\n' "$staged_paths") <(printf '%s\n' "$unstaged_paths"))" +if [ -n "$partial_paths" ]; then + echo "pre-commit: these files have staged and unstaged edits:" >&2 + while IFS= read -r path; do + printf ' - %s\n' "$path" >&2 + done <<< "$partial_paths" + echo "Stage each whole file before committing." >&2 + exit 1 +fi + +make test + +while IFS= read -r path; do + case "$path" in + docs.json|api-reference/endpoint/*.mdx|Makefile|.githooks/pre-commit) + make _lint-openapi-drift + break ;; + esac +done <<< "$staged_paths" diff --git a/Makefile b/Makefile index ac517ff..b34b936 100644 --- a/Makefile +++ b/Makefile @@ -1,34 +1,45 @@ SHELL := /bin/bash -.PHONY: dev lint test _lint-openapi-drift +.PHONY: dev install-hooks lint test _lint-openapi-drift OPENAPI_URL ?= https://raw.githubusercontent.com/agentsfleet/agentsfleet/main/public/openapi.json dev: npx mintlify dev +install-hooks: + @git config core.hooksPath .githooks + @echo "Git hooks enabled from .githooks" + test: - @bash scripts/test-spec.sh + @python3 scripts/test-documentation.py + @python3 scripts/check-documentation.py . -lint: _lint-openapi-drift +lint: test _lint-openapi-drift npx mintlify validate npx mintlify broken-links find . -name "*.mdx" | xargs -I{} npx markdown-link-check --config .mlc-config.json {} _lint-openapi-drift: - @command -v jq >/dev/null 2>&1 || { echo "jq not installed — skipping openapi drift check"; exit 0; } + @command -v jq >/dev/null 2>&1 || { echo "jq is required for the OpenAPI drift check"; exit 1; } @tmp=$$(mktemp); \ - if ! curl -sSfL --connect-timeout 5 "$(OPENAPI_URL)" -o "$$tmp"; then \ - echo "warn: could not fetch $(OPENAPI_URL) — skipping openapi drift check"; \ - rm -f "$$tmp"; exit 0; \ + if ! curl -sSfL --connect-timeout 5 --max-time 10 "$(OPENAPI_URL)" -o "$$tmp"; then \ + echo "could not fetch $(OPENAPI_URL) for the OpenAPI drift check"; \ + rm -f "$$tmp"; exit 1; \ fi; \ upstream=$$(jq -r '.paths | to_entries[] | . as $$p | $$p.value | keys[] | (ascii_upcase + " " + $$p.key)' "$$tmp" | sort -u); \ referenced=$$(grep -hoE '"(GET|POST|PUT|DELETE|PATCH) /[^"]+"' docs.json api-reference/endpoint/*.mdx 2>/dev/null | tr -d '"' | sort -u); \ missing=$$(comm -23 <(echo "$$referenced") <(echo "$$upstream")); \ + unlisted=$$(comm -13 <(echo "$$referenced") <(echo "$$upstream")); \ rm -f "$$tmp"; \ if [ -n "$$missing" ]; then \ echo "❌ openapi drift: paths referenced by docs but missing from $(OPENAPI_URL):"; \ echo "$$missing" | sed 's/^/ - /'; \ exit 1; \ fi; \ + if [ -n "$$unlisted" ]; then \ + echo "❌ openapi drift: operations missing from docs.json:"; \ + echo "$$unlisted" | sed 's/^/ - /'; \ + exit 1; \ + fi; \ echo "✓ openapi drift check clean" diff --git a/README.md b/README.md index 4a39221..d371bbe 100644 --- a/README.md +++ b/README.md @@ -20,13 +20,38 @@ Each one wakes on an event — a pull request, an incident, a deploy — investi ## Development -Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview documentation changes locally: +Before editing a page or API text, read `~/Projects/dotfiles/docs/DOCUMENTATION_RULES.md`. + +1. Install the [Mintlify CLI](https://www.npmjs.com/package/mint). ```bash npm i -g mint +``` + +```text +added packages in +``` + +2. Enable the repository's pre-commit checks. + +```bash +make install-hooks +``` + +```text +Git hooks enabled from .githooks +``` + +3. Start the local preview. + +```bash mint dev ``` +```text +Local: http://localhost:3000 +``` + View your local preview at `http://localhost:3000`. ## Publishing diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index 47c4b2a..ad11894 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -1,11 +1,22 @@ --- -title: 'Error Codes' -description: 'All error responses from agentsfleetd use RFC 7807 (application/problem+json). This page lists every error code, its HTTP status, and common causes.' +title: Error codes +description: API error response fields and stable error codes. +type: reference +audience: user +verified: 2026-07-12 +product_version: 0.17.0 +executable: false --- -## Response format +# Error codes -Every `4xx` and `5xx` response uses `Content-Type: application/problem+json`: +## Synopsis + +Every API error uses a JSON Problem Details response. Each response carries a stable error code and documentation URL. + +Use the error code for program logic. Use the request identifier when you contact support. + +## Example with output ```json { @@ -13,268 +24,281 @@ Every `4xx` and `5xx` response uses `Content-Type: application/problem+json`: "title": "Fleet not found", "detail": "No fleet with id '0198a7ba-2c1d-7f08-8a45-3e9b6d2f1c70' in this workspace.", "error_code": "UZ-AGT-009", - "request_id": "0198a7b5-3c8d-7e41-9a2b-6f1d4c7e8a05" + "request_id": "0198a7b5-3c8d-7e41-9a2b-6f1d4c7e8a05", + "user_message": "We couldn't find that Fleet. Check the workspace and fleet identifier." } ``` -| Field | Description | -|---|---| -| `docs_uri` | Stable link to this page for the specific code | -| `title` | Short label — identical for every occurrence of a given code | -| `detail` | Instance-specific context (varies per call) | -| `error_code` | Machine-readable code. Use this for programmatic handling. | -| `request_id` | Correlation ID for support and log tracing | - - -This page is generated from agentsfleetd's error registry (`make gen-error-codes`) — every code below is one the server can actually emit. A retired code disappears from this page entirely; an old `docs_uri` anchor that 404s here means the code was removed. - - -## IDs - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-UUIDV7-009` | 400 | Invalid ID shape | The supplied ID does not match the expected UUIDv7 shape. | - -## Internal - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-INTERNAL-001` | 503 | Database unavailable | Check that DATABASE_URL is set and the database server is reachable. Run 'agentsfleetd doctor' to verify. | -| `UZ-INTERNAL-002` | 500 | Database error | A database query failed. Check the err= field and database logs. | -| `UZ-INTERNAL-003` | 500 | Internal operation failed | An internal operation failed. Check the err= field for details. If persistent, check service connectivity and run 'agentsfleetd doctor'. | - -## Request - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-REQ-001` | 400 | Invalid request | The request body or parameters are invalid. Check the API documentation. | -| `UZ-REQ-002` | 413 | Payload too large | Request body exceeds the maximum allowed size. | - -## Authentication - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-AUTH-001` | 403 | Forbidden | Access denied. Check that your API key has the required role. | -| `UZ-AUTH-002` | 401 | Unauthorized | Authentication required. Provide a valid Bearer token. | -| `UZ-AUTH-003` | 401 | Token expired | Your authentication token has expired. Re-authenticate. | -| `UZ-AUTH-004` | 503 | Authentication service unavailable | Authentication service is temporarily unavailable. Retry shortly. | -| `UZ-AUTH-005` | 404 | Session not found | Session was not found. It may have expired or been invalidated. | -| `UZ-AUTH-006` | 401 | Session expired | Your session has expired. Please sign in again. | -| `UZ-AUTH-011` | 400 | Verification code did not match | The 6-digit verification code did not match what the dashboard issued. Double-check the code shown in your browser and try again. | -| `UZ-AUTH-012` | 410 | Login session already consumed | This login session has already been consumed. Start over with `agentsfleet login`. | -| `UZ-AUTH-013` | 410 | Login session aborted | This login session was aborted (too many wrong codes, explicit cancel, or replaced by a newer session). Start over with `agentsfleet login`. | -| `UZ-AUTH-014` | 409 | Login session not approved | This login session has not been approved in the dashboard yet. Approve it in your browser before submitting a verification code. | -| `UZ-AUTH-015` | 409 | Login session already approved | This login session has already been approved. Do not call /approve a second time. | -| `UZ-AUTH-016` | 400 | Invalid CLI public key | The supplied public_key is malformed. Expect base64url-encoded P-256 SubjectPublicKeyInfo. | -| `UZ-AUTH-017` | 400 | Invalid token name | token_name must be 1-64 characters of printable ASCII. | -| `UZ-AUTH-018` | 400 | Invalid verification code shape | verification_code must be exactly 6 ASCII digits. | -| `UZ-AUTH-019` | 400 | Invalid ciphertext | ciphertext is missing or empty. Expect a base64url-encoded AES-256-GCM output. | -| `UZ-AUTH-020` | 400 | Invalid nonce | nonce is missing, empty, or the wrong length. Expect a base64url-encoded 12-byte value. | -| `UZ-AUTH-022` | 403 | Insufficient scope | Your token does not carry a scope required for this action. The required scope is named in the error detail; see the [Scopes](/api-reference/scopes) reference for what each one grants. | - -## API - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-API-001` | 429 | Too many in-flight requests | This API instance is at its in-flight request ceiling and is shedding load. Honor the Retry-After header and retry with backoff. Operators: raise API_MAX_IN_FLIGHT_REQUESTS or add replicas. | -| `UZ-API-002` | 503 | Event-stream capacity reached | This instance is serving its maximum number of concurrent event streams. Close unused dashboard tabs or retry shortly. Operators: raise SSE_MAX_STREAMS or add replicas. | - -## Fleet Keys - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-FLEETKEY-001` | 404 | Fleet key not found | Fleet key not found. Verify the fleet_key_id. | - -## Webhooks - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-WH-001` | 404 | Fleet not found for webhook | No fleet is registered for this webhook endpoint. | -| `UZ-WH-002` | 400 | Malformed webhook | Webhook payload could not be parsed. Check Content-Type and body. | -| `UZ-WH-010` | 401 | Invalid webhook signature | Webhook signature verification failed. Confirm the signing secret stored for this provider (Slack/Clerk/other) matches the one configured upstream. | -| `UZ-WH-011` | 401 | Stale webhook timestamp | Webhook request timestamp is outside the allowed 5-minute drift window. This may indicate a replay attack or clock skew. | -| `UZ-WH-020` | 401 | Webhook credential not configured | No webhook credential is configured for this fleet's source. Run `agentsfleet secret add --data='{"webhook_secret":"..."}'` in the fleet's workspace, then resend. | -| `UZ-WH-021` | 404 | Connector installation is not mapped | Reconnect the provider App to the intended workspace before redelivering the event. | -| `UZ-WH-022` | 404 | No fleet subscription matched | Bind the repository and event to an active fleet with an approved integration grant. | -| `UZ-WH-030` | 413 | Webhook payload too large | Webhook body exceeds the 1 MiB ingest limit. Reduce the payload size or filter at the source. | - -## Slack - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-SLK-010` | 401 | Invalid Slack signature | The Slack request signature did not verify. Confirm the platform Slack app signing secret matches the one vaulted at slack-app/signing_secret. | -| `UZ-SLK-011` | 401 | Stale Slack timestamp | The Slack request timestamp is outside the allowed 5-minute drift window — a replay attempt or a skewed server clock. | -| `UZ-SLK-020` | 200 | Slack team not installed | The Slack team that sent this event has no connector install, so the event is acknowledged (200) and ignored. Re-run Connect Slack in the dashboard to (re)install. | -| `UZ-SLK-022` | 502 | Slack token exchange failed | The Slack OAuth code could not be exchanged for a bot token. Retry the connect flow; if it persists, verify the platform Slack app credentials. | -| `UZ-SLK-030` | 502 | Slack answer post failed | The channel bot's answer could not be delivered to Slack (missing chat:write, a 429, or a Slack outage). It is logged and retried with backoff; the run itself never fails. | - -## Tools - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-TOOL-005` | 400 | Unknown tool | Unknown tool name. Check spelling against the known tools list. | - -## Fleets - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-AGT-003` | 424 | Fleet credential missing | A required credential is not in the vault. Add it with: `agentsfleet secret add ` | -| `UZ-AGT-004` | 500 | Fleet claim failed | Fleet could not be claimed from the database. Check that the fleet_id exists and status is 'active'. | -| `UZ-AGT-006` | 409 | Fleet name already exists | A Fleet with this name already exists. Use `agentsfleet kill ` first, then deploy again. | -| `UZ-AGT-008` | 400 | Invalid fleet config | Config JSON is malformed. Verify trigger, tools, credentials, and budget fields in your TRIGGER.md frontmatter. See the [Authoring a fleet](/fleets/authoring) guide for a working example. | -| `UZ-AGT-009` | 404 | Fleet not found | Fleet not found. Verify the fleet_id and that it has not been killed. | -| `UZ-AGT-010` | 409 | Fleet state transition not allowed | The requested lifecycle action is not valid from the fleet's current state. The response detail names the specific transition that was refused. | -| `UZ-AGT-011` | 400 | SKILL.md and TRIGGER.md disagree on `name:` | Top-level `name:` in SKILL.md must match `name:` in TRIGGER.md. One identity per Fleet Bundle. | -| `UZ-AGT-012` | 409 | Fleet is paused | This fleet is not active and refuses new work. Resume it with: `agentsfleet resume `, then retry. | -| `UZ-AGT-013` | 500 | Fleet install rolled back | Event-stream setup failed during create; the fleet row was rolled back so the caller can retry cleanly. If this persists, check queue connectivity. | - -## Fleet Bundles - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-BUNDLE-001` | 400 | Invalid Fleet Bundle | The supplied Fleet Bundle is missing SKILL.md or contains unsafe, oversized, or malformed files. | -| `UZ-BUNDLE-002` | 404 | Fleet Bundle not found | No installable library entry or stored snapshot matches the request in this workspace. | -| `UZ-BUNDLE-003` | 424 | Fleet Bundle secrets missing | Add the missing workspace secrets before installing this Fleet Bundle. | -| `UZ-BUNDLE-004` | 502 | Fleet Bundle fetch failed | The Fleet Bundle source could not be fetched from GitHub. The repository may be missing or private, or GitHub may be unreachable. Verify the source reference and retry. | -| `UZ-BUNDLE-005` | 503 | Fleet Bundle storage unavailable | Snapshot storage is not configured or is unavailable, so the validated bundle could not be stored. Retry later or contact the operator. | - -## Secrets - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-VAULT-001` | 400 | Secret data must be a non-empty JSON object | POST /secrets body must include a 'data' field that is a JSON object with at least one key. Bare strings, arrays, scalars, and `{}` are rejected. | -| `UZ-VAULT-002` | 400 | Secret data too large | Stringified secret data exceeds 4KB. Compose the secret from fewer or shorter fields. | -| `UZ-VAULT-003` | 404 | Secret not found | No secret matches this name in the workspace. List the workspace secrets to find a valid name, or create it first. | -| `UZ-VAULT-004` | 409 | Secret still referenced by model entries | One or more core.tenant_model_entries rows reference this secret_ref (M121). Remove those entries first, then delete the secret. The response detail names the exact count. | - -## Model Providers - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-PROVIDER-001` | 400 | secret_ref required when mode=self_managed | PUT body must include `secret_ref` naming a vault credential when `mode` is self_managed. | -| `UZ-PROVIDER-002` | 400 | Secret row not found in vault | The named secret_ref has no vault row in the tenant's primary workspace. Run `agentsfleet secret add --data=@-` to create it. | -| `UZ-PROVIDER-003` | 400 | Secret JSON missing required field | Stored secret JSON must include `provider` (a non-empty string); `api_key` is required for a named provider but optional for an `openai-compatible` endpoint. `model` is optional — the model registry entry carries it, not the credential. Re-run `agentsfleet secret add` with the required fields. | -| `UZ-PROVIDER-004` | 400 | Model not in library | The effective model is not present in core.model_library. Pick a model from the model library (`GET /v1/models`, or the admin list) or request the library be extended. | -| `UZ-PROVIDER-005` | 400 | Custom endpoint base_url invalid or unsafe | An openai-compatible credential needs a valid `base_url`: it must use https and must not target a loopback, private, link-local, or cloud-metadata host. A non-openai-compatible provider must not carry a `base_url`. | -| `UZ-PROVIDER-006` | 404 | Library model not found | No core.model_library row matches this id. List the library to find a valid id, or add the model first. | -| `UZ-PROVIDER-007` | 409 | Library model is the active platform default | This model is the active platform default. Point the default at another library model before deleting it. | -| `UZ-PROVIDER-008` | 409 | Library model already exists | A library row for this provider and model already exists. Edit the existing row instead of adding a duplicate. | -| `UZ-PROVIDER-009` | 500 | Platform LLM key not configured | No active row in core.platform_provider_defaults. An operator must set one via PUT /admin/platform-keys before tenants can switch to platform defaults. | -| `UZ-PROVIDER-010` | 500 | Tenant has no primary workspace | The tenant row has no primary workspace — an onboarding invariant that should always hold. Contact support with the request id. | - -## MODELS - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-MODELS-001` | 409 | Cannot delete the active model entry | This entry is the tenant's current active selection. Switch to a different entry first, then delete this one. | -| `UZ-MODELS-002` | 404 | Referenced secret not found | POST/PATCH secret_ref does not name a vault secret in the tenant's primary workspace. Store the secret first, or pick an existing one. | -| `UZ-MODELS-003` | 409 | Model entry already exists | An entry with this exact (model_id, secret_ref) pair already exists for this tenant. Edit the existing entry instead of adding a duplicate. | -| `UZ-MODELS-004` | 404 | Model entry not found | No core.tenant_model_entries row matches this id for the calling tenant. It may have already been deleted — refresh the list. | - -## Startup - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-STARTUP-001` | 500 | Environment check failed | Required environment variables are missing. Run 'agentsfleetd doctor' to see which ones. | -| `UZ-STARTUP-002` | 500 | Config load failed | Configuration failed to load. Check that all required env vars are set. Run 'agentsfleetd doctor' to verify. | -| `UZ-STARTUP-003` | 500 | Database connect failed | Database is unreachable. Check that DATABASE_URL is set and the database accepts connections. | -| `UZ-STARTUP-004` | 500 | Redis connect failed | Redis is unreachable. Check that REDIS_URL_API is set and the Redis server accepts connections. Run 'agentsfleetd doctor' to verify. | -| `UZ-STARTUP-005` | 500 | Migration check failed | Database migration state could not be verified. Check DB connectivity. | -| `UZ-STARTUP-006` | 500 | Startup env allocation failed | An environment variable could not be allocated at startup (out of memory). A required secret fails the boot closed; optional config falls back to its default — check host memory pressure. | - -## Runners - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-RUN-001` | 401 | Invalid runner token | The Bearer runner_token is missing, malformed, or not recognized. Re-register the runner. | -| `UZ-RUN-005` | 409 | Stale fencing token | The lease was reclaimed by a newer holder. This report is rejected; the current holder's result wins. | -| `UZ-RUN-006` | 404 | Lease not found | No active lease matches this lease_id for the presenting runner; it may have expired, been reclaimed, or never existed. | -| `UZ-RUN-009` | 401 | Runner admin state blocks access | This runner is cordoned, draining, drained, or revoked and cannot call the runner plane. Re-enroll the host to mint a fresh runner token. | -| `UZ-RUN-010` | 409 | Lease exceeded max runtime | The lease reached the hard maximum runtime and may not be renewed further; the run is terminated. The child is killed and the result, if any, is reported. | -| `UZ-RUN-011` | 409 | Lease lost | The lease was reassigned to another runner before this renewal; it can no longer be renewed. The presenting runner must terminate its child. | -| `UZ-RUN-012` | 402 | Lease renewal blocked: no credits | The tenant's balance can no longer cover continued execution; the lease may not be renewed and the run terminates gracefully. | -| `UZ-RUN-013` | 400 | Renew body malformed | The renew request body could not be parsed; cumulative token counts default to zero and the slice meters its run-time fee only (never a negative charge). The lease is still renewed. | -| `UZ-RUN-014` | 404 | Runner not found | No runner matches this runner_id. Verify the platform admin minted the runner before mutating it. | -| `UZ-RUN-015` | 402 | Lease renewal blocked: fleet budget exhausted | The fleet reached its own daily_dollars or monthly_dollars ceiling declared in TRIGGER.md; the lease may not be renewed and the run terminates. Distinct from UZ-RUN-012 (the tenant's credit pool), so an operator can tell the fleet author's own limit from a billing failure. | - -## Execution - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-EXEC-003` | 500 | Execution timeout kill | Execution exceeded the timeout limit and was killed. | -| `UZ-EXEC-004` | 500 | Execution OOM kill | Execution exceeded memory limit and was killed. | -| `UZ-EXEC-005` | 500 | Execution resource kill | Execution exceeded resource limits and was killed. | -| `UZ-EXEC-006` | 500 | Execution transport loss | Connection to execution transport was lost. | -| `UZ-EXEC-007` | 500 | Execution lease expired | Execution lease expired. The task took too long to complete. | -| `UZ-EXEC-008` | 500 | Execution renewal-terminated | The control plane stopped the lease mid-run (lease lost, max-runtime cap, or no credits). A policy stop, kept distinct from a wall-clock timeout (UZ-EXEC-003) for triage and billing. | -| `UZ-EXEC-009` | 500 | Execution startup posture failure | Execution startup posture check failed. Verify runner security config. | -| `UZ-EXEC-010` | 500 | Execution crash | The execution process crashed. Check logs for details. | -| `UZ-EXEC-011` | 403 | Landlock policy deny | Landlock policy denied the filesystem operation. | -| `UZ-EXEC-012` | 500 | Runner fleet init failed | Runner fleet initialization failed. Check configuration. | -| `UZ-EXEC-013` | 500 | Runner fleet run failed | Runner fleet execution failed. Check logs for details. | -| `UZ-EXEC-014` | 400 | Runner invalid config | Runner configuration is invalid. Check config_json fields. | -| `UZ-EXEC-015` | 402 | Execution stopped: fleet budget exhausted | The control plane refused the lease renewal because the fleet reached its own daily_dollars or monthly_dollars ceiling (UZ-RUN-015). A fleet-scoped spend stop, kept distinct from a renewal-terminate (UZ-EXEC-008) so triage can tell the fleet author's own limit from a platform or billing stop. | - -## Approvals - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-APPROVAL-001` | 400 | Approval parse failed | Gate policy in TRIGGER.md config_json has invalid syntax. Check the 'gates' section. | -| `UZ-APPROVAL-002` | 404 | Approval not found | Approval action not found or already resolved. The action may have timed out or been handled by another click. | -| `UZ-APPROVAL-003` | 401 | Approval invalid signature | The approval callback signature is invalid. Check the signing secret. | -| `UZ-APPROVAL-004` | 503 | Approval Redis unavailable | Gate service unavailable — default-deny applied. Check Redis connectivity. | -| `UZ-APPROVAL-005` | 400 | Approval condition invalid | Gate condition expression is invalid. Supported operators: == and != with single-quoted values. | -| `UZ-APPROVAL-006` | 409 | Approval already resolved | Resolved earlier by Slack, dashboard, or auto-timeout. Original outcome + resolver in body. | - -## Memory - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-MEM-002` | 404 | Fleet not found for memory op | The fleet_id does not exist or does not belong to the requesting workspace. Verify the fleet_id and workspace scope. | -| `UZ-MEM-003` | 503 | Memory backend unavailable | The memory backend (Postgres memory schema) is unreachable. The fleet falls back to ephemeral workspace memory. Check MEMORY_RUNTIME_URL. | - -## API Keys - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-APIKEY-001` | 401 | Invalid API key | API key is invalid or revoked. Mint a replacement with: `POST /v1/workspaces/{ws}/fleet-keys` | -| `UZ-APIKEY-003` | 404 | API key not found | No API key matches the supplied id for this tenant. Verify the id with: GET /v1/api-keys | -| `UZ-APIKEY-004` | 401 | API key has been revoked | This key was revoked and can no longer authenticate. Mint a replacement with: POST /v1/api-keys | -| `UZ-APIKEY-005` | 409 | Key name already exists in this tenant | key_name must be unique per tenant. Pick a different name or revoke the existing key first. | -| `UZ-APIKEY-006` | 409 | API key is already revoked | This key is already revoked. No further action is required. | -| `UZ-APIKEY-007` | 409 | active cannot be set to true; mint a new key instead | Re-activation is not supported. Create a new key via POST /v1/api-keys and revoke the old one. | -| `UZ-APIKEY-008` | 409 | Active API key must be revoked before deletion | Revoke the key first with `PATCH /v1/api-keys/{id}` body `{"active": false}`, then retry DELETE. | - -## Integration Grants +## Options -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-GRANT-001` | 403 | No integration grant for service | This fleet has no approved grant for the target service. Request one with: `POST /v1/workspaces/{ws}/fleets/{id}/integration-requests` | -| `UZ-GRANT-002` | 404 | Integration grant not found | No grant with that id exists for this fleet, or it was already revoked. List current grants with: `GET /v1/workspaces/{ws}/fleets/{id}/integration-grants` | -| `UZ-GRANT-003` | 409 | Grant already resolved | This grant was already approved or denied — by an earlier click, the dashboard, or an auto-timeout. The original decision stands; this request changed nothing. | - -## Credentials - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-CRED-001` | 404 | Integration not connected | No connected integration matches this id for the fleet's workspace. Connect it first (e.g. GitHub via the dashboard “Connect” flow) before a fleet can mint a token for it. | -| `UZ-CRED-002` | 503 | Credential broker not configured | The on-demand credential broker is not wired on this deployment (a boot-time misconfiguration, not a client error). An operator must configure it before runners can mint credentials. | - -## GitHub - -| Code | HTTP | Title | Common Causes | -|---|---|---|---| -| `UZ-GH-001` | 409 | GitHub App reconnect required | The GitHub App installation is gone (uninstalled or revoked), so no token can be minted. Reconnect GitHub from the dashboard — the fleet stays blocked until the App is reinstalled. | -| `UZ-GH-002` | 502 | GitHub token mint failed | GitHub did not return an installation token (upstream 5xx, network, or a malformed exchange response). This is transient — retry shortly; if it persists, check GitHub status and the App configuration. | +The error format has no client option. Every response contains the first five fields below. -## Connectors +A conflict response also contains `current_state`. Some errors contain `user_message`. -| Code | HTTP | Title | Common Causes | +| Field | Effect | Default | Unit or range | |---|---|---|---| -| `UZ-CONN-001` | 503 | Connector not configured | This connector's platform app is not provisioned on this deployment (its admin-vault secret bag, App slug, or signing secret is unset). An operator must register the provider app and populate the admin vault before workspaces can connect. | -| `UZ-CONN-002` | 400 | Invalid connect state | The connect callback's state was missing, forged, expired, or already used. Start the connect again from the dashboard — each attempt issues a fresh single-use state. | -| `UZ-CONN-003` | 502 | Connector vendor call exceeded its deadline | An outbound call to the connector's vendor hit its enforced deadline (the vendor accepted the connection, then stalled), could not be deadline-armed and was refused (watchdog unavailable), or the vendor was unreachable (dial/transport failure) — the call never runs unbounded. Transient — retry; if it persists, check the vendor's status page and this deployment's egress. | -| `UZ-CONN-004` | 404 | Unknown connector provider | The `{provider}` segment does not match any provider in this deployment's connector registry. List the available providers from the dashboard connectors page (or the catalog endpoint once it ships). | -| `UZ-CONN-006` | 502 | Connector OAuth exchange failed | The connector's OAuth code exchange or provider callback body was rejected. Start the connect again from the dashboard; if it repeats, verify the provider app credentials and redirect URL. | -| `UZ-CONN-007` | 500 | Connector catalog lookup failed | The vault existence check for connector app/fleet keys failed (a Postgres error). Retry; if it persists, check DB connectivity and the vault schema state. | -| `UZ-CONN-008` | 403 | Connector installation ownership not verified | GitHub did not confirm that the authorizing user can access the submitted App installation, or that installation is already connected to another workspace. Start the connection again while signed in to the GitHub account that owns the installation. | +| `docs_uri` | Links to this error. | Included | URL | +| `title` | Gives a stable short label. | Included | Text | +| `detail` | Explains this failure. | Included | Text that varies by request | +| `error_code` | Identifies the failure for client logic. | Included | Registered code below | +| `request_id` | Identifies the request for support. | Included | Server-generated value | +| `current_state` | Names the state that blocked a change. | Omitted | Included on HTTP 409 responses | +| `user_message` | Gives text safe to show to a user. | Omitted | Included when the error defines one | + +## Errors + +### Identifiers + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-UUIDV7-009` | 400 | Invalid identifier shape | The supplied identifier does not match the expected version 7 universally unique identifier shape. | Use identifiers returned by agentsfleet. | + +### Service failures + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-INTERNAL-001` | 503 | Service unavailable | A required service is unavailable. Try again shortly. | Clients cannot prevent this failure. Keep retry handling ready. | +| `UZ-INTERNAL-002` | 500 | Request failed | We couldn't finish that request. Try again shortly. | Clients cannot prevent this failure. Keep retry handling ready. | +| `UZ-INTERNAL-003` | 500 | Request failed | The request could not finish. Retry it, then report the error code and request identifier if it continues. | Clients cannot prevent this failure. Keep retry handling ready. | + +### Request + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-REQ-001` | 400 | Invalid request | That request wasn't valid. Double-check the values you entered and try again. | Validate request fields before sending the request. | +| `UZ-REQ-002` | 413 | Payload too large | Request body exceeds the maximum allowed size. | Validate request fields before sending the request. | + +### Authentication + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-AUTH-001` | 403 | Forbidden | You need operator access for that. Ask a tenant operator or admin to manage API keys. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-002` | 401 | Unauthorized | Authentication required. Provide a valid Bearer token. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-003` | 401 | Token expired | Your authentication token has expired. Re-authenticate. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-004` | 503 | Authentication service unavailable | Authentication service is temporarily unavailable. Retry shortly. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-005` | 404 | Session not found | Session was not found. It may have expired or been invalidated. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-006` | 401 | Session expired | Your session has expired. Please sign in again. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-011` | 400 | Verification code did not match | The 6-digit verification code did not match what the dashboard issued. Double-check the code shown in your browser and try again. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-012` | 410 | Login session already consumed | This login session has already been consumed. Start over with `agentsfleet login`. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-013` | 410 | Login session aborted | This login session was aborted (too many wrong codes, explicit cancel, or replaced by a newer session). Start over with `agentsfleet login`. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-014` | 409 | Login session not approved | This login session has not been approved in the dashboard yet. Approve it in your browser before submitting a verification code. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-015` | 409 | Login session already approved | This login session has already been approved. Do not call /approve a second time. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-016` | 400 | Invalid command-line public key | The supplied public_key is malformed. Expect base64url-encoded P-256 SubjectPublicKeyInfo. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-017` | 400 | Invalid token name | token_name must contain 1 to 64 characters from space through tilde. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-018` | 400 | Invalid verification code shape | verification_code must contain exactly 6 decimal digits. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-019` | 400 | Invalid ciphertext | ciphertext is missing or empty. Expect a base64url-encoded AES-256-GCM output. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-020` | 400 | Invalid nonce | nonce is missing, empty, or the wrong length. Expect a base64url-encoded 12-byte value. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-022` | 403 | Insufficient scope | You need an additional scope for that. Ask an agentsfleet admin to grant the scope this action requires. | Keep sign-in sessions and credentials current. | + +### API + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-API-001` | 429 | Too many requests | The API is handling its maximum number of requests. Wait for the Retry-After delay, then retry. | Limit concurrent requests and honor retry delays. | +| `UZ-API-002` | 503 | Activity stream capacity reached | The API is serving its maximum number of activity streams. Close unused dashboard tabs or retry shortly. | Limit concurrent requests and honor retry delays. | + +### Fleet keys + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-FLEETKEY-001` | 404 | Fleet key not found | Fleet key not found. Verify the fleet_key_id. | Use a current Fleet API key for the intended fleet. | + +### Webhooks + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-WH-001` | 404 | Fleet not found for webhook | No fleet is registered for this webhook endpoint. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-002` | 400 | Malformed webhook | Webhook payload could not be parsed. Check Content-Type and body. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-010` | 401 | Invalid webhook signature | Webhook signature verification failed. Confirm the signing secret stored for this provider (Slack/Clerk/other) matches the one configured upstream. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-011` | 401 | Stale webhook timestamp | Webhook request timestamp is outside the allowed 5-minute drift window. This may indicate a replay attack or clock skew. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-020` | 401 | Webhook credential not configured | Create a random webhook secret with at least 32 bytes. Store it as this source's webhook_secret, configure the same value upstream, then resend. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-021` | 404 | Connector installation is not mapped | Reconnect the provider App to the intended workspace before redelivering the event. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-022` | 404 | No fleet subscription matched | Bind the repository and event to an active fleet with an approved integration grant. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-030` | 413 | Webhook payload too large | Webhook body exceeds the 1 MiB ingest limit. Reduce the payload size or filter at the source. | Keep webhook signing secrets matched and service clocks synchronized. | + +### Slack + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-SLK-010` | 401 | Invalid Slack signature | The Slack request signature did not verify. Confirm the platform Slack app signing secret matches the one vaulted at slack-app/signing_secret. | Keep Slack app credentials, permissions, and clocks current. | +| `UZ-SLK-011` | 401 | Stale Slack timestamp | The Slack request timestamp is outside the allowed 5-minute drift window — a replay attempt or a skewed server clock. | Keep Slack app credentials, permissions, and clocks current. | +| `UZ-SLK-020` | 200 | Slack team not installed | The Slack team that sent this event has no connector install, so the event is acknowledged (200) and ignored. Re-run Connect Slack in the dashboard to (re)install. | Keep Slack app credentials, permissions, and clocks current. | +| `UZ-SLK-022` | 502 | Slack token exchange failed | The Slack OAuth code could not be exchanged for a bot token. Retry the connect flow; if the error continues, verify the platform Slack app credentials. | Keep Slack app credentials, permissions, and clocks current. | +| `UZ-SLK-030` | 502 | Slack answer post failed | The channel bot's answer could not be delivered to Slack (missing chat:write, a 429, or a Slack outage). It is logged and retried with backoff; the run itself never fails. | Keep Slack app credentials, permissions, and clocks current. | + +### Tools + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-TOOL-005` | 400 | Unknown tool | Unknown tool name. Check spelling against the known tools list. | Declare every tool used by the fleet. | + +### Fleets + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-AGT-003` | 424 | Fleet credential missing | A required credential is not in the vault. Add it with: `agentsfleet secret create ` | Use fleet identifiers from the current workspace. | +| `UZ-AGT-004` | 500 | Fleet unavailable | The fleet could not accept work. Check that the fleet exists and is active, then retry. | Use fleet identifiers from the current workspace. | +| `UZ-AGT-006` | 409 | Fleet name already exists | A Fleet with this name already exists. Use `agentsfleet kill ` first, then deploy again. | Use fleet identifiers from the current workspace. | +| `UZ-AGT-008` | 400 | Invalid fleet config | That fleet's config isn't valid. Check the trigger, tools, credentials, and budget fields, then try again. | Use fleet identifiers from the current workspace. | +| `UZ-AGT-009` | 404 | Fleet not found | We couldn't find that Fleet. It may have been deleted, or the identifier doesn't match one in this workspace. | Use fleet identifiers from the current workspace. | +| `UZ-AGT-010` | 409 | Fleet state transition not allowed | That action isn't available for this Fleet right now — check its current status and try again. | Use fleet identifiers from the current workspace. | +| `UZ-AGT-011` | 400 | Fleet files disagree on `name:` | This Fleet Bundle's files disagree on its name. `SKILL.md` and `TRIGGER.md` must match. Fix the source and try again. | Use fleet identifiers from the current workspace. | +| `UZ-AGT-012` | 409 | Fleet is paused | This Fleet is paused. Resume it before sending new work. | Use fleet identifiers from the current workspace. | +| `UZ-AGT-013` | 500 | Fleet install rolled back | We couldn't finish setting up your fleet. Nothing was created — try again. | Use fleet identifiers from the current workspace. | + +### Fleet Bundles + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-BUNDLE-001` | 400 | Invalid Fleet Bundle | That Fleet Bundle isn't valid. It's missing `SKILL.md`, or has an unsafe or oversized file. Check the source and try again. | Check Fleet Bundle files and limits before upload. | +| `UZ-BUNDLE-002` | 404 | Fleet Bundle not found | We couldn't find that Fleet Bundle. It may not be installed in this workspace yet — check the Fleet library. | Check Fleet Bundle files and limits before upload. | +| `UZ-BUNDLE-003` | 424 | Fleet Bundle secrets missing | This Fleet Bundle needs secrets this workspace doesn't have yet. Add the missing secrets, then install again. | Check Fleet Bundle files and limits before upload. | +| `UZ-BUNDLE-004` | 502 | Fleet Bundle fetch failed | We couldn't fetch that Fleet Bundle from GitHub. Check the source and try again. | Check Fleet Bundle files and limits before upload. | +| `UZ-BUNDLE-005` | 503 | Fleet Bundle storage unavailable | We couldn't store your Fleet Bundle right now. Try again shortly. | Check Fleet Bundle files and limits before upload. | + +### Secrets + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-VAULT-001` | 400 | Secret data must be a non-empty JSON object | That secret needs at least one field. Enter it as a JSON object with one or more keys — not a bare string or list. | Use a valid workspace secret name and value. | +| `UZ-VAULT-002` | 400 | Secret data too large | That secret is too large. Keep it under 4 KiB. Trim or shorten the fields. | Use a valid workspace secret name and value. | +| `UZ-VAULT-003` | 404 | Secret not found | We couldn't find that secret. It may have already been deleted — refresh the list. | Use a valid workspace secret name and value. | +| `UZ-VAULT-004` | 409 | Secret still referenced by model entries | This key is used by one or more models in your registry. Remove those entries first, then delete the key. | Use a valid workspace secret name and value. | + +### Model providers + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-PROVIDER-001` | 400 | secret_ref required when mode=self_managed | Pick a secret to activate. Choose a stored secret before switching to a self-managed model. | Configure a supported provider, model, and secret. | +| `UZ-PROVIDER-002` | 400 | Secret not found | We couldn't find that secret. Store it under Secrets & ENVs, then try again. | Configure a supported provider, model, and secret. | +| `UZ-PROVIDER-003` | 400 | Secret JSON missing required field | That secret is missing required fields. It needs a provider set (and an API key for a named provider) — edit it under Secrets & ENVs and add them. | Configure a supported provider, model, and secret. | +| `UZ-PROVIDER-004` | 400 | Model not in library | That model isn't in our library yet. Pick a listed model, or ask us to add support for it. | Configure a supported provider, model, and secret. | +| `UZ-PROVIDER-005` | 400 | Custom endpoint base_url invalid or unsafe | That endpoint URL isn't allowed. Use a public https URL for your custom endpoint. | Configure a supported provider, model, and secret. | +| `UZ-PROVIDER-006` | 404 | Library model not found | We couldn't find that model in the library. Refresh the list and try again. | Configure a supported provider, model, and secret. | +| `UZ-PROVIDER-007` | 409 | Library model is the active platform default | This model is the active platform default — point the default at another model before deleting it. | Configure a supported provider, model, and secret. | +| `UZ-PROVIDER-008` | 409 | Library model already exists | That model is already in the library. Edit the existing entry instead of adding a duplicate. | Configure a supported provider, model, and secret. | +| `UZ-PROVIDER-009` | 500 | Platform model key not configured | Platform defaults aren't set up on this deployment yet. Keep your current provider for now, or contact support. | Configure a supported provider, model, and secret. | +| `UZ-PROVIDER-010` | 500 | Tenant has no primary workspace | Something's off with your account setup. Contact support with the request id below. | Configure a supported provider, model, and secret. | + +### Tenant models + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-MODELS-001` | 409 | Cannot delete the active model entry | This is your active model — switch to a different one first, then remove this entry. | Use a model available to the tenant. | +| `UZ-MODELS-002` | 404 | Referenced secret not found | We couldn't find that key. Store it under Secrets & ENVs first, or pick an existing key. | Use a model available to the tenant. | +| `UZ-MODELS-003` | 409 | Model entry already exists | You already have this model registered with that key. Edit the existing entry instead. | Use a model available to the tenant. | +| `UZ-MODELS-004` | 404 | Model entry not found | We couldn't find that model entry. It may have already been removed — refresh the list. | Use a model available to the tenant. | + +### Startup + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-STARTUP-001` | 500 | Required settings missing | The service cannot start because required settings are missing. An operator must add them before retrying startup. | Operators should verify required service settings before startup. | +| `UZ-STARTUP-002` | 500 | Settings could not load | The service cannot start because one or more settings are invalid. An operator must correct them before retrying startup. | Operators should verify required service settings before startup. | +| `UZ-STARTUP-003` | 500 | Data service unavailable | The service cannot start because a required data service is unreachable. An operator must restore access before retrying startup. | Operators should verify required service settings before startup. | +| `UZ-STARTUP-004` | 500 | Event service unavailable | The service cannot start because its event service is unreachable. An operator must restore access before retrying startup. | Operators should verify required service settings before startup. | +| `UZ-STARTUP-005` | 500 | Stored data is not ready | The service cannot start because stored data is not ready. An operator must finish the data update before retrying startup. | Operators should verify required service settings before startup. | +| `UZ-STARTUP-006` | 500 | Service could not start | The host lacked enough memory during startup. Free memory or use a larger host, then retry. | Operators should verify required service settings before startup. | + +### Runners + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-RUN-001` | 401 | Invalid runner token | The Bearer runner_token is missing, malformed, or not recognized. Re-register the runner. | Keep runner settings and lease health within configured limits. | +| `UZ-RUN-005` | 409 | Stale fencing token | The lease was reclaimed by a newer holder. This report is rejected; the current holder's result wins. | Keep runner settings and lease health within configured limits. | +| `UZ-RUN-006` | 404 | Lease not found | No active lease matches this lease_id for the presenting runner; it may have expired, been reclaimed, or never existed. | Keep runner settings and lease health within configured limits. | +| `UZ-RUN-009` | 401 | Runner admin state blocks access | This runner is cordoned, draining, drained, or revoked and cannot call the runner plane. Re-enroll the host to mint a fresh runner token. | Keep runner settings and lease health within configured limits. | +| `UZ-RUN-010` | 409 | Lease exceeded max runtime | The lease reached its maximum runtime and cannot renew. The runner stops the child and reports any result. | Keep runner settings and lease health within configured limits. | +| `UZ-RUN-011` | 409 | Lease lost | The lease moved to another runner before renewal. The former runner must stop its child. | Keep runner settings and lease health within configured limits. | +| `UZ-RUN-012` | 402 | Lease renewal blocked: no credits | The tenant balance cannot cover another run slice. The lease does not renew, and the run stops cleanly. | Keep runner settings and lease health within configured limits. | +| `UZ-RUN-013` | 400 | Renew body malformed | The renew request body could not be parsed. Token counts become zero, but the renewed slice still charges for runtime. The lease still renews. | Keep runner settings and lease health within configured limits. | +| `UZ-RUN-014` | 404 | Runner not found | We couldn't find that runner. It may have been removed — refresh the list. | Keep runner settings and lease health within configured limits. | +| `UZ-RUN-015` | 402 | Lease renewal blocked: fleet budget exhausted | The fleet reached its daily_dollars or monthly_dollars limit from `TRIGGER.md`. The lease cannot renew, so the run stops. This differs from UZ-RUN-012, which reports a low tenant balance. | Keep runner settings and lease health within configured limits. | + +### Runs + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-EXEC-003` | 500 | Run timed out | The run exceeded its time limit and stopped. | Check runner settings and access before starting work. | +| `UZ-EXEC-004` | 500 | Run memory limit reached | The run reached its memory limit and stopped. | Check runner settings and access before starting work. | +| `UZ-EXEC-005` | 500 | Run resource limit reached | The run reached a resource limit and stopped. | Check runner settings and access before starting work. | +| `UZ-EXEC-006` | 500 | Runner connection lost | The connection to the runner was lost. | Check runner settings and access before starting work. | +| `UZ-EXEC-007` | 500 | Run lease expired | The run took too long and its lease expired. | Check runner settings and access before starting work. | +| `UZ-EXEC-008` | 500 | Run stopped during renewal | The run stopped because its lease was lost, expired, or refused renewal. | Check runner settings and access before starting work. | +| `UZ-EXEC-009` | 500 | Runner security check failed | Check the runner security settings before retrying. | Check runner settings and access before starting work. | +| `UZ-EXEC-010` | 500 | Run crashed | The run process crashed. Check the activity stream for details. | Check runner settings and access before starting work. | +| `UZ-EXEC-011` | 403 | Landlock policy deny | Landlock policy denied the filesystem operation. | Check runner settings and access before starting work. | +| `UZ-EXEC-012` | 500 | Runner fleet init failed | Runner fleet initialization failed. Check configuration. | Check runner settings and access before starting work. | +| `UZ-EXEC-013` | 500 | Runner fleet run failed | The runner could not finish the fleet run. Check the activity stream. | Check runner settings and access before starting work. | +| `UZ-EXEC-014` | 400 | Run settings invalid | The run settings are invalid. Check the fleet files before retrying. | Check runner settings and access before starting work. | +| `UZ-EXEC-015` | 402 | Run stopped: fleet limit reached | The run stopped because the fleet reached its configured limit. | Check runner settings and access before starting work. | + +### Approvals + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-APPROVAL-001` | 400 | Approval parse failed | That approval gate's config is invalid. Check the gates section in TRIGGER.md. | Resolve only current approval requests. | +| `UZ-APPROVAL-002` | 404 | Approval not found | That approval action wasn't found. It may have already timed out or been resolved elsewhere. | Resolve only current approval requests. | +| `UZ-APPROVAL-003` | 401 | Approval invalid signature | That approval callback couldn't be verified. Check the signing secret configuration. | Resolve only current approval requests. | +| `UZ-APPROVAL-004` | 503 | Approval service unavailable | Approvals are temporarily unavailable. We deny requests while this service is down. Try again shortly. | Resolve only current approval requests. | +| `UZ-APPROVAL-005` | 400 | Approval condition invalid | That approval gate's condition is invalid. Check the gate's condition expression for a supported operator. | Resolve only current approval requests. | +| `UZ-APPROVAL-006` | 409 | Approval already resolved | Someone already resolved this. Refresh to see the outcome and who resolved it. | Resolve only current approval requests. | + +### Memory + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-MEM-002` | 404 | Fleet not found for memory op | The fleet_id does not exist or does not belong to the requesting workspace. Verify the fleet_id and workspace scope. | Use an existing fleet and a valid memory category. | +| `UZ-MEM-003` | 503 | Saved memory unavailable | Saved memory is unavailable. The fleet uses temporary workspace memory until the service recovers. | Use an existing fleet and a valid memory category. | + +### API keys + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-APIKEY-001` | 401 | Invalid API key | API key is invalid or revoked. Mint a replacement with: `POST /v1/workspaces/{ws}/fleet-keys` | Use current API key identifiers and replace revoked keys. | +| `UZ-APIKEY-003` | 404 | API key not found | We couldn't find that API key. It may have already been deleted — refresh the list. | Use current API key identifiers and replace revoked keys. | +| `UZ-APIKEY-004` | 401 | API key has been revoked | This key was revoked and can no longer authenticate. Mint a replacement with: POST /v1/api-keys | Use current API key identifiers and replace revoked keys. | +| `UZ-APIKEY-005` | 409 | Key name already exists in this tenant | An API key with that name already exists. Pick a different name for this tenant. | Use current API key identifiers and replace revoked keys. | +| `UZ-APIKEY-006` | 409 | API key is already revoked | That API key is already revoked. Refresh the list to see its current state. | Use current API key identifiers and replace revoked keys. | +| `UZ-APIKEY-007` | 409 | active cannot be set to true; mint a new key instead | A revoked key can't be reactivated. Mint a new key instead. | Use current API key identifiers and replace revoked keys. | +| `UZ-APIKEY-008` | 409 | Active API key must be revoked before deletion | Revoke this key before deleting it. Revoke it first, then delete the revoked key. | Use current API key identifiers and replace revoked keys. | + +### Integration grants + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-GRANT-001` | 403 | No integration grant for service | This fleet has no approved grant for the target service. Request one with: `POST /v1/workspaces/{ws}/fleets/{id}/integration-requests` | Use active integration grants approved for the fleet. | +| `UZ-GRANT-002` | 404 | Integration grant not found | We couldn't find that grant request. It may have already been resolved — refresh the list. | Use active integration grants approved for the fleet. | +| `UZ-GRANT-003` | 409 | Grant already resolved | Someone already resolved this. Refresh to see the outcome and who resolved it. | Use active integration grants approved for the fleet. | + +### Credentials + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-CRED-001` | 404 | Integration not connected | That integration isn't connected. Connect it from the Integrations page, then try again. | Create required workspace secrets before starting a run. | +| `UZ-CRED-002` | 503 | Credential broker not configured | The on-demand credential broker is not wired on this deployment (a boot-time misconfiguration, not a client error). An operator must configure it before runners can mint credentials. | Create required workspace secrets before starting a run. | + +### GitHub + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-GH-001` | 409 | GitHub App reconnect required | The GitHub App installation is gone (uninstalled or revoked), so no token can be minted. Reconnect GitHub from the dashboard — the fleet stays blocked until the App is reinstalled. | Keep the GitHub App installed with required repository access. | +| `UZ-GH-002` | 502 | GitHub token mint failed | GitHub did not return an installation token (upstream 5xx, network, or a malformed exchange response). This is temporary. Retry shortly; if the error continues, check GitHub status and the App configuration. | Keep the GitHub App installed with required repository access. | + +### Connectors + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-CONN-001` | 503 | Connector not configured | This connector isn't set up yet. Contact your operator to enable it. | Check the provider connection before sending requests. | +| `UZ-CONN-002` | 400 | Invalid connect state | That connection attempt expired or was already used. Start connecting again from the dashboard. | Check the provider connection before sending requests. | +| `UZ-CONN-003` | 502 | Connector vendor call exceeded its deadline | We couldn't reach that service right now. Try again shortly. | Check the provider connection before sending requests. | +| `UZ-CONN-004` | 404 | Unknown connector provider | We don't recognize that connector. Check the available connectors on the dashboard. | Check the provider connection before sending requests. | +| `UZ-CONN-006` | 502 | Connector OAuth exchange failed | That connection didn't go through. Try connecting again from the dashboard. | Check the provider connection before sending requests. | +| `UZ-CONN-007` | 500 | Connector catalog lookup failed | We couldn't load your connectors right now. Try refreshing — if it keeps failing, contact support. | Check the provider connection before sending requests. | +| `UZ-CONN-008` | 403 | Connector installation ownership not verified | We couldn't verify that this GitHub installation belongs to you. Sign in with the owning GitHub account and try again. | Check the provider connection before sending requests. | + +## Related pages + +- [API introduction](/api-reference/introduction) +- [API scopes](/api-reference/scopes) +- [Troubleshoot fleets](/fleets/troubleshooting) diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index b14d186..707f93c 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -1,59 +1,55 @@ --- -title: 'API Reference' -description: 'agentsfleet Control Plane API — deploy, observe, and control fleets programmatically.' +title: API introduction +description: Base URL, authentication, errors, and common response formats. +type: explanation +audience: user +verified: 2026-07-12 +product_version: 0.17.0 +executable: false --- -## Base URL +# API introduction -``` -https://api.agentsfleet.net -``` +## What it is -## Authentication +The `agentsfleet` API lets your software create, inspect, and control fleets. Send requests to `https://api.agentsfleet.net`. -All API endpoints require a Bearer token in the `Authorization` header, except health checks and the initial auth session creation. +The linked OpenAPI file describes every path, request body, response, and status code. -```bash -curl https://api.agentsfleet.net/v1/workspaces/0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50/fleets \ - -H "Authorization: Bearer $AGENTSFLEET_API_KEY" -``` +## Why it exists + +Use the API when a script or service needs direct access. Use the command-line client for interactive terminal work. -Two kinds of bearer token are accepted: +## How it behaves -- **Tenant API key (`agt_t…`)** — long-lived, for programmatic and service-to-service callers (CI, cron, integrations, scripts). Create one in the dashboard from the **API Keys** page (in the sidebar); the raw value is shown once. This is the right token for calling the API directly. -- **User JWT** — short-lived, for an interactive human. Mint one with `agentsfleet login`, a browser device flow with terminal-side verification. It can't be obtained by a bare API client — the flow needs the dashboard's browser leg — so for unattended access use a tenant API key. +Most paths accept a bearer token in the `Authorization` header. Tenant API keys start with `agt_t` and are shown once when created. -## Errors +Interactive users can sign in with `agentsfleet login`. The login flow saves a short-lived JSON Web Token (JWT). -All errors use RFC 7807 problem detail (`Content-Type: application/problem+json`): +Webhook and connector paths use provider signatures instead of bearer tokens. The OpenAPI security section on each operation states the required method. -```json -{ - "docs_uri": "https://docs.agentsfleet.net/api-reference/error-codes#UZ-AGT-009", - "title": "Fleet not found", - "detail": "No fleet with the given ID exists in this workspace.", - "error_code": "UZ-AGT-009", - "request_id": "0198a7b6-1f2a-7d53-8c94-2b7e5a1f9d40" -} +`` comes from `agentsfleet workspace list`. Use an obviously fake key in copied examples. + +```bash +curl https://api.agentsfleet.net/v1/workspaces//fleets -H "Authorization: Bearer af_test_00000000" ``` -Error codes follow the `UZ--NNN` scheme in the `error_code` field. Every response includes a `request_id` for tracing. On `409 Conflict` responses the body may carry an extra `current_state` field naming the resource's blocking state (e.g. `paused`). See [Error codes](/api-reference/error-codes) for the full registry. +```text +{"items":,"total":,"cursor":} +``` + +Errors use the HTTP problem details format. Each product error includes an `error_code`, a `request_id`, and a documentation URL. + +Identifiers use version 7 Universally Unique Identifiers (UUIDs). Timestamps use Unix milliseconds unless an operation states another unit. -## Conventions +## Limits -- **IDs** are UUIDv7. -- **Timestamps** are Unix milliseconds. -- **State transitions** are partial updates on the parent resource (e.g., `PATCH /v1/workspaces/{workspace_id}/fleets/{fleet_id}` with body `{status: "stopped"}`). Sub-resources (e.g., `/messages`, `/events`, `/events/stream`) handle data-flow operations. -- **Streaming endpoints** (activity stream) return Server-Sent Events. +Rate limits apply per workspace. A limited request includes `Retry-After`; wait for that delay before retrying. -## Rate limits +Streaming activity uses Server-Sent Events (SSE). A stream can return `UZ-API-002` when the service cannot accept another subscriber. -API rate limits are per-workspace. If you hit a rate limit, the response includes a `Retry-After` header. +## Related pages - - View the full OpenAPI 3.1 specification - +- [OpenAPI 3.1 file](https://raw.githubusercontent.com/agentsfleet/agentsfleet/main/public/openapi.json) +- [Authentication scopes](/api-reference/scopes) +- [Error registry](/api-reference/error-codes) diff --git a/api-reference/scopes.mdx b/api-reference/scopes.mdx index 66b6076..e16a9f8 100644 --- a/api-reference/scopes.mdx +++ b/api-reference/scopes.mdx @@ -1,42 +1,69 @@ --- -title: 'Scopes' -description: 'The capability vocabulary every agentsfleet token (dashboard session or API key) carries as its `scopes` claim — what each scope grants, and what to do when a request is rejected for lacking one.' +title: API scopes +description: Permissions that an agentsfleet access token can carry. +type: reference +audience: user +verified: 2026-07-12 +product_version: 0.17.0 +executable: false --- -## How scopes work +# API scopes -Every request is authorized against an explicit `scopes` claim on the caller's token — not a role name. A scope like `fleet:write` grants exactly what it says; there is no hidden bundle of extra capabilities behind it. +## Synopsis -Related scopes ladder: holding the higher one satisfies a check for the lower one. `fleet:admin` holder passes a `fleet:read` gate; `apikey:write` passes an `apikey:read` gate. Discrete-verb scopes (`billing:read`, `workspace:admin`, `library:write`, `approval:read`/`approval:resolve`) don't ladder — each is its own, separately grantable capability. +Each access token carries named scopes. An API request fails when the token lacks the required scope. - -If a request returns [`UZ-AUTH-022`](/api-reference/error-codes#authentication--authorization) (Insufficient scope), the response's `detail` field names the exact scope your token is missing. Ask a workspace admin to grant it — see [API keys](/api-reference/introduction) for how a tenant API key's scopes are set. - +Some scope groups use `read`, `write`, and `admin` levels. A higher level includes every lower level in the same group. -## Fleets & workspace resources +## Example with output -Laddered `read < write < admin`: +This request uses an obviously fake token. Replace the token with a tenant API key from **Settings → API Keys**. -| Scope | Grants | -|---|---| -| `fleet:read` / `fleet:write` / `fleet:admin` | view fleets, their events, and memories / create, update, and message fleets / delete a fleet | -| `secret:read` / `secret:write` | list workspace secrets / store, rotate, or delete them, including your tenant LLM provider config | -| `apikey:read` / `apikey:write` / `apikey:admin` | list tenant API keys / create and rotate them / delete (revoke) one | -| `fleetkey:read` / `fleetkey:write` | list fleet-scoped keys / create and delete them | -| `grant:read` / `grant:write` | list integration grants / revoke them | -| `connector:read` / `connector:write` | read a connector's status / start a connector connect flow | +```bash +curl -s https://api.agentsfleet.net/v1/fleets -H 'Authorization: Bearer af_test_00000000' +``` -## Discrete capabilities +```text +{"title":"Insufficient scope","error_code":"UZ-AUTH-022","detail":"Missing required scope: fleet:read"} +``` -Each of these is its own capability — no ladder: +## Options -| Scope | Grants | -|---|---| -| `billing:read` | read your tenant's billing snapshot, charges, and metering periods | -| `workspace:admin` | create workspaces; list your tenant's workspaces | -| `library:write` | onboard an entry into your workspace's Fleet library | -| `approval:read` / `approval:resolve` | view the approval inbox / approve or deny a gate | +| Scope | Effect | Included by | +|---|---|---| +| `fleet:read` | Reads fleets, events, and memory. | `fleet:write`, `fleet:admin` | +| `fleet:write` | Creates, updates, and messages fleets. | `fleet:admin` | +| `fleet:admin` | Deletes fleets. | None | +| `secret:read` | Lists secret names and metadata. | `secret:write` | +| `secret:write` | Creates, rotates, and deletes secrets. | None | +| `apikey:read` | Lists tenant API keys. | `apikey:write`, `apikey:admin` | +| `apikey:write` | Creates and rotates tenant API keys. | `apikey:admin` | +| `apikey:admin` | Revokes tenant API keys. | None | +| `fleetkey:read` | Lists fleet keys. | `fleetkey:write` | +| `fleetkey:write` | Creates and deletes fleet keys. | None | +| `grant:read` | Lists integration grants. | `grant:write` | +| `grant:write` | Revokes integration grants. | None | +| `connector:read` | Reads connector state. | `connector:write` | +| `connector:write` | Starts a connector setup flow. | None | +| `billing:read` | Reads the tenant balance and charges. | None | +| `workspace:admin` | Creates and lists workspaces. | None | +| `library:write` | Adds an entry to a workspace library. | None | +| `approval:read` | Reads pending approvals. | None | +| `approval:resolve` | Approves or denies a request. | None | -## Platform-operator scopes +Operator tokens may carry `runner:*`, `platform-key:*`, `model:*`, or `workspace:any`. Tenant integrations do not need these scopes. -A smaller set of scopes (`runner:*`, `platform-key:*`, `model:*`, `workspace:any`) gates platform-administration surfaces — enrolling runners, setting the platform-default model, and cross-tenant operator tooling. These aren't relevant to a typical tenant API integration; they're documented for platform operators alongside the deployment's own admin runbook, not here. +## Errors + +### UZ-AUTH-022: Insufficient scope + +The token lacks the scope named in `detail`. Create a new key with that scope, then retry the request. + +Do not add unrelated scopes. A narrower key limits the effect of a leaked key. + +## Related pages + +- [API introduction](/api-reference/introduction) +- [Error codes](/api-reference/error-codes) +- [Client configuration](/cli/configuration) diff --git a/billing/budgets.mdx b/billing/budgets.mdx index f26818b..64b904b 100644 --- a/billing/budgets.mdx +++ b/billing/budgets.mdx @@ -1,17 +1,18 @@ --- -title: "Budgets and cost control" -description: "Per-fleet dollar ceilings, tenant-wide spend caps, and how debits work." +title: Fleet budgets +description: Daily and monthly spending limits for one fleet. +type: explanation +audience: user +verified: 2026-07-12 +product_version: 0.17.0 +executable: false --- -agentsfleet enforces budgets at two levels: per-fleet ceilings declared in `TRIGGER.md`, and a tenant-wide balance that every run debits against. +# Fleet budgets - - **Free until July 31, 2026.** During the launch trial, hosted execution is free — the tenant-wallet mechanics below apply **after** the trial. See [pricing](https://agentsfleet.net/pricing). - +## What it is -## Per-fleet ceilings (`daily_dollars` / `monthly_dollars`) - -Every fleet declares its own dollar ceilings in `TRIGGER.md`: +A fleet budget limits how much one fleet can spend. The fleet author sets the budget in `TRIGGER.md`. ```yaml budget: @@ -19,35 +20,36 @@ budget: monthly_dollars: 29.0 ``` -- `daily_dollars` caps spend over a rolling 24-hour window. -- `monthly_dollars` caps spend over the calendar month. +`daily_dollars` is required. `monthly_dollars` is optional. -When either ceiling is reached the fleet stops processing new events and a budget breach is recorded in the activity stream. This is the first line of defence — one bad prompt never becomes an infinite burn on a single fleet. +## Why it exists -Per-event token and wall-clock caps are internal runtime controls. They are not user-configurable in `TRIGGER.md` today. +Every workspace under one tenant shares the same credit balance. A fleet budget stops one fleet from draining that shared balance. -## Tenant wallet +The fleet owns its budget. Updating the fleet replaces the limits, and deleting the fleet removes them. -Separately, your tenant has a single wallet (the $5 free credit at signup, topped up via Stripe). Every completed run debits this wallet. +## How it behaves -- The wallet is **tenant-scoped**, not workspace-scoped. All workspaces under your tenant share the same pool. -- When the wallet hits **zero**, runs across all workspaces stop until the tenant tops up. -- The wallet balance is visible in the dashboard header and via `agentsfleet billing show`. +The daily limit covers a rolling 24-hour window. The monthly limit covers one Coordinated Universal Time (UTC) calendar month. -Set a monthly spend cap on your tenant from the billing page at [app.agentsfleet.net/billing](https://app.agentsfleet.net/billing). +`agentsfleet` checks the limits before a run and while the run continues. A reached limit blocks new work and stops an active run at its next billing check. -A `agentsfleet billing budget set` CLI command is planned for a future release. +A blocked event does not retry. Raise the limit, update the fleet, and send a new event. -## Run cancellation +The fleet, memory, and activity stream survive a budget stop. A stopped run has no final result. -Cancel an in-flight run at any time via CLI or API: +## Limits -```bash -agentsfleet kill -``` +| Field | Default | Unit | Valid range | +|---|---|---|---| +| `daily_dollars` | None; required | Dollars per rolling 24 hours | More than `$0` and at most `$1,000` | +| `monthly_dollars` | None | Dollars per UTC month | More than `$0` and at most `$10,000` | + +An invalid budget blocks fleet installation. A stored budget that cannot be read blocks the next run. -Cancelling stops the run at the next lease renewal. The run time already elapsed is metered and debited — cancelling doesn't refund the work done so far. See [Credit deduction timing](#credit-deduction-timing) below for the full rule. +`UZ-RUN-015` marks a budget stop during a run. `UZ-EXEC-015` records the final failure class. -## Credit deduction timing +## Related pages -Credit is metered continuously while a run executes: each background lease renewal debits the elapsed time slice from your tenant balance, and a final settle covers the last partial slice when the run ends. Because billing accumulates as the run proceeds, a run that is cancelled or fails partway through is still charged for the time it actually ran — only a run that never starts, or fails before its first metered slice, costs nothing. The same single tenant wallet is debited for every run, across all workspaces. +- [Author a fleet](/fleets/authoring) +- [Error codes](/api-reference/error-codes) diff --git a/billing/plans.mdx b/billing/plans.mdx deleted file mode 100644 index 1543563..0000000 --- a/billing/plans.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "Plans" -description: "One credit-based model — the starter credit and how per-second run billing works." ---- - -agentsfleet has a single credit-based model. Every tenant gets the full platform — always-on fleet hosting, the tool bridge, activity stream, webhook ingestion, kill switch — and pays from one shared credit wallet. There are no tiers to choose between or upgrade to. - - - **Free until July 31, 2026.** During the launch trial, hosted execution — every event receipt and run — is free. The billing details below describe charging **after** the trial. See [pricing](https://agentsfleet.net/pricing). - - -## Starter credit - -New tenants start with **$5 (500¢)** seeded into the tenant balance automatically on first sign-in — there are no tokens to enter or gates to clear. The balance is waiting for you the moment Clerk completes auth. - -| Feature | Details | -|---------|---------| -| Starter credit | $5 (500¢), tenant-scoped | -| Fleets per workspace | Unlimited | -| Workspaces | Unlimited | -| Event processing | Included | -| Support | Community (Discord, GitHub) | - -The $5 balance is **tenant-scoped and shared across every workspace** you create. There is no per-workspace pool — every run debits the same wallet. This is the single-wallet model introduced with v2. - -## How credits are spent - -Run time is metered by the second: each background lease renewal debits the elapsed slice from your wallet — plus the model's per-token cost on platform-key runs — with a final settle for the last partial slice when a run ends. Billing accumulates as the run proceeds, so a run that is cancelled or fails partway through is still charged for the time it actually ran; only a run that never starts, or fails before its first metered slice, is free. See [Budgets & limits](/billing/budgets) for the full deduction rule. - -## Topping up - -When the wallet runs low, top up at [app.agentsfleet.net/billing](https://app.agentsfleet.net/billing). Top-ups and payment-method updates happen via the dashboard, not the CLI — the CLI surface is `agentsfleet billing show` for read-only balance and charge history. Top-ups apply to the tenant, not an individual workspace — the wallet follows the tenant. diff --git a/changelog.mdx b/changelog.mdx index 1f9db9e..7cc2731 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -22,6 +22,22 @@ export const STAGE_SELF_MANAGED_M66 = "$0.0001"; agentsfleet is in **stealth-mode testing** and pre-production. APIs and agent behavior may change between releases without long deprecation windows. Email [agentsfleet@agentmail.to](mailto:agentsfleet@agentmail.to) if you want a hand calibrating an agent or to join as a design partner. + + ## Removed CLI commands stop appearing in hints, and workspace delete stops implying remote deletion + + Error hints and CLI messages now match the commands `agentsfleet` actually accepts. `agentsfleet workspace delete` also makes clear it only removes local client state — it never deletes the workspace or its data remotely. + + ## Upgrading + + - **`agentsfleet workspace delete` JSON output field renamed** — `{"deleted": ""}` is now `{"removed_from_local_state": ""}`. Update any script parsing this field. The workspace and its remote data are unaffected by this command. + + ## Bug fixes + + - **Stale command hints removed** — error text and CLI messages no longer point at removed verbs (`agentsfleet install --from`, `agentsfleet secret add`, `agentsfleet workspace add`, `agentsfleet tenant provider add`). `agentsfleet list` with no fleets now points to `agentsfleet library` and `agentsfleet install --library `; vault error hints now say `agentsfleet secret create `. + - **Clean `--help` output** — `agentsfleet --help` no longer prints a telemetry-shutdown timeout after valid help output. + - **GitHub Pull Request events** — the signed per-fleet webhook now accepts the full set of supported Pull Request actions from the routed source filter. + + ## GitHub App events route to repository-bound fleets diff --git a/cli/agentsfleet.mdx b/cli/agentsfleet.mdx index 057999f..c19a28a 100644 --- a/cli/agentsfleet.mdx +++ b/cli/agentsfleet.mdx @@ -1,538 +1,153 @@ --- -title: "Command reference" -description: "Complete agentsfleet command reference." +title: Command reference +description: Commands available in the agentsfleet command-line client. +type: reference +audience: user +verified: 2026-07-12 +product_version: 0.17.0 +executable: false --- -## Overview +# Command reference -| Group | Commands | -|-------|----------| -| Authentication | `login`, `logout`, `auth status` | -| Fleets (top-level) | `install --library`, `library`, `list`, `status`, `stop`, `resume`, `kill`, `delete`, `logs`, `events`, `steer` | -| Fleets (in-place update) | `fleet update --from` | -| Secrets | `secret add`, `secret show`, `secret list`, `secret delete` | -| Workspaces | `workspace add`, `workspace list`, `workspace use`, `workspace show`, `workspace secrets`, `workspace delete` | -| Memory | `memory list`, `memory search` | -| Fleet keys (external access) | `fleet-key add`, `fleet-key list`, `fleet-key delete` | -| Integration grants | `grant list`, `grant delete` | -| Billing | `billing show` | -| Tenant provider | `tenant provider show`, `tenant provider add`, `tenant provider delete` | -| Diagnostics | `doctor` | +## Synopsis -Every command accepts the [global flags](/cli/flags). Every command that returns structured data supports `--json` for machine-readable output. +The command-line interface (CLI) manages workspaces, fleets, access, secrets, and memory. ---- - -## Authentication - -### `agentsfleet login` - -Authenticate via a Clerk-backed browser device flow with terminal-side verification. Opens your default browser to the approval page; on Approve, the page displays a 6-digit verification code which you type back into the CLI to complete login. The verification code binds the browser approver to the terminal user — phishing the URL alone is not enough to mint a token. - -```bash -agentsfleet login -``` - -```bash -# Label this device for visibility in `auth status` and on the approval page -agentsfleet login --token-name "kishore-macbook" -``` - -```bash -# Non-interactive (CI, scripts): supply a token instead of the browser flow -agentsfleet login --token "$MY_TOKEN" -# …or pipe it so it never lands in shell history -printf '%s' "$MY_TOKEN" | agentsfleet login -``` - -After the token persists, `login` also fetches `GET /v1/tenants/me/workspaces` and writes the first workspace into local state as `current_workspace_id`. Signup auto-provisions a default workspace, so a fresh `npm i -g @agentsfleet/cli && agentsfleet login` is enough to reach `agentsfleet doctor` green — `workspace add` is only needed if you want a second or custom-named workspace, or if the workspace fetch failed (login still exits 0 in that case). - -Flags: - -- `--token ` — authenticate non-interactively with a token directly, skipping the browser entirely; the token is validated against the server and persisted. Prefer piping the token on stdin to keep it out of your shell history. `--token-name` is ignored for any non-browser token source — `--token` or piped stdin — since there's no browser session to label. -- `--token-name