AutoGPT — Admin Guide

This guide is for the people who deploy, operate, secure, and extend AutoGPT: administrators, platform engineers, architects, and block developers. It covers the AutoGPT Platform (autogpt_platform/) in depth and the legacy classic/ tree briefly. End-user tasks (building agents, AutoPilot, the Marketplace, scheduling) are in the companion User Guide.

1. Executive Summary

Important

The three most consequential operator facts: (1) the backend refuses to start without ENCRYPTION_KEY, and losing it makes every stored integration credential unreadable; (2) the appliance persists every generated secret in /data/config/runtime.env and has no in-place rotation; (3) BEHAVE_AS=local (the self-host default) bypasses subscription entitlement gating and is only appropriate for single-tenant installs.

2. Architecture

2.1 Component diagram (Compose deployment)

                         Browser
                            │ :3000
                ┌───────────▼────────────┐
                │ frontend (Next.js)     │  Better Auth (sessions, ES256 JWT,
                │  /api/auth/jwks        │  JWKS in platform."UserAuthJwks")
                └──────┬───────────┬─────┘
          REST :8006   │           │  WS :8001
        ┌──────────────▼──┐   ┌────▼─────────────┐
        │ rest_server     │   │ websocket_server │◄── Redis event bus
        │ FastAPI (/api,  │   │ (execution       │    (execution_event,
        │ /external-api,  │   │  updates)        │     notification_event)
        │ /health)        │   └──────────────────┘
        └──┬───────┬──────┘
           │ RPC   │ publish
           │       ▼
           │   ┌─────────┐   consume  ┌──────────────┐   ┌──────────────────┐
           │   │RabbitMQ │──────────► │ executor     │   │ copilot_executor │
           │   │  :5672  │──────────► │ :8002        │   │ :8008 (AutoPilot)│
           │   └─────────┘            └──────┬───────┘   └────────┬─────────┘
           │                                 │ RPC                │
     ┌─────▼──────────────┐       ┌──────────▼─────────┐  ┌───────▼───────┐
     │ database_manager   │◄──────┤ scheduler :8003    │  │ FalkorDB      │
     │ :8005 (DB RPC)     │       │ notification :8007 │  │ :6380 Graphiti│
     └─────┬──────────────┘       │ linking mgr :8009  │  └───────────────┘
           │                      └────────────────────┘
   ┌───────▼───────────┐   ┌──────────────────┐   ┌──────────────┐
   │ PostgreSQL :5432  │   │ Redis cluster    │   │ ClamAV :3310 │
   │ pgvector pg15     │   │ :17000-17002     │   │ (uploads)    │
   │ schema "platform" │   └──────────────────┘   └──────────────┘
   └───────────────────┘

2.2 Service inventory

All backend roles are the same image started with a different Poetry script.

Additional roles defined in code (not separate Compose services by default): batch-executor (batch_executor_port 8011, polls LLM batch APIs), and the chat bridge (copilot_chat_bridge_port 8010).

poetry run app starts all roles in one process tree, in this order: DatabaseManager, Scheduler, BatchExecutor, NotificationManager, PlatformLinkingManager, WebsocketServer, AgentServer (REST), ExecutionManager, CoPilotChatBridge, CoPilotExecutor (the last runs in the foreground).

2.3 Repository layout

2.4 Execution flow

1. A run is requested via REST (POST /api/graphs/{graph_id}/execute/{graph_version}), the External API, a schedule, a webhook trigger, or AutoPilot.
2. The REST layer validates inputs and credentials, enforces the payment paywall where applicable, records an AgentGraphExecution, and publishes to RabbitMQ.
3. The executor consumes the message (up to num_graph_workers, default 10), resolves starting nodes, and queues downstream nodes as their required inputs validate.
4. Each node execution loads its block, injects credentials (never persisted into node I/O), charges credits (execution_cost_* settings), and records AgentNodeExecution + AgentNodeExecutionInputOutput.
5. Progress is published on the Redis event bus (execution_event); the WebSocket server forwards it to subscribed browsers.
6. A block failure yields on its error pin; errors inheriting from ValueError (BlockInputError, BlockExecutionError) are classified as user-fixable "expected failures".

Concurrency guards in Config:

2.5 Data Layer

• ORM: Prisma (Python client), schema postgres/schema.prisma-style layout at backend/schema.prisma, default DB schema platform (DB_SCHEMA).
• Database: PostgreSQL 15 with pgvector (embeddings for hybrid search).
• Key model groups (90 models):

Warning

Don't hand-edit rows that carry encrypted payloads (IntegrationCredential) or Better Auth key material (AuthJwks, exposed as platform."UserAuthJwks" in the upgrade instructions). Use the CLI (rotate-encryption-key) or the documented DELETE FROM platform."UserAuthJwks"; reset only.

Search infrastructure. api/features/search/ provides a unified embedding table (UnifiedContentEmbedding) and unified_hybrid_search (semantic + BM25 lexical + recency + category scoring) across store agents, blocks, docs, library agents, workspace files, and chat sessions, exposed at /api/search/global. New content types add a ContentType enum value, a ContentHandler subclass registered in CONTENT_HANDLERS, and a background ensure_content_embedding call on write. Embeddings use store_embedding_model (default text-embedding-3-small).

2.6 Caching

3. System Requirements

Note

There is no measured minimum CPU count or supported concurrent-run ceiling for the appliance; performance depends on enabled services and workload.

Appliance fixed ceilings

4. Configuration Mastery

4.1 How configuration is loaded

The backend settings are two Pydantic settings models in backend/util/settings.py: Config (behavior) and Secrets (credentials). Field names map to environment variables of the same name (conventionally upper-case, e.g. num_graph_workers ↔ NUM_GRAPH_WORKERS). .env.default only lists variables that must be set; everything else falls back to the code defaults below.

A ./secrets directory is also supported: each file ./secrets/<name> holds one secret value, loaded at startup — useful for Docker secrets.

4.2 Required settings

Caution

VAPID_PRIVATE_KEY / VAPID_PUBLIC_KEY ship as a dev-only keypair in .env.default. Regenerate before any non-local deployment:

poetry run python -c "
from py_vapid import Vapid; import base64
from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
v = Vapid(); v.generate_keys()
raw_priv = v.private_key.private_numbers().private_value.to_bytes(32, 'big')
print('VAPID_PRIVATE_KEY=' + base64.urlsafe_b64encode(raw_priv).rstrip(b'=').decode())
raw_pub = v.public_key.public_bytes(Encoding.X962, PublicFormat.UncompressedPoint)
print('VAPID_PUBLIC_KEY=' + base64.urlsafe_b64encode(raw_pub).rstrip(b'=').decode())
"

Also set VAPID_CLAIM_EMAIL to a real mailbox (default mailto:[email removed] in .env.default).

4.3 Config reference (behavior)

Service ports and hosts

Execution and concurrency

Codex / ChatGPT subscription processes

Credits and billing

Files, scanning, moderation

URLs, CORS, environment

Feature flags and toggles

Force individual flags locally with FORCE_FLAG_<NAME>=true (or FORCE_ALL_FLAGS=true when APP_ENV=local); frontend equivalents use NEXT_PUBLIC_FORCE_FLAG_<NAME>.

Periodic cleanup jobs

Alerts and email senders

4.4 Secrets reference (credentials)

All default to empty. Only set what you use.

4.5 AutoPilot and memory settings

Key fallbacks: Graphiti's LLM key falls back to CHAT_API_KEY, then OPEN_ROUTER_API_KEY, then (local) the chat config; its embedder key falls back to CHAT_OPENAI_API_KEY, then OPENAI_API_KEY, then (local) the chat config. Under CHAT_USE_LOCAL=true cloud-slug Graphiti defaults are rewritten to local-friendly slugs unless you set custom values.

Note

On the hosted cloud (BEHAVE_AS=cloud), CHAT_*_MODEL is the bottom layer of AutoPilot model resolution — the catalog routing cells in backend/data/llm_registry/catalog.py and the per-user LaunchDarkly copilot-model-routing flag take precedence. On self-hosted installs the catalog cells are skipped and the env vars are authoritative.

4.6 Frontend settings

Warning

NEXT_PUBLIC_* values are compiled into the browser bundle. Never put a secret in a NEXT_PUBLIC_ variable.

4.7 Single-container appliance settings

runtime_config.py validates the environment at boot and raises precise errors (see Troubleshooting). Generated secrets are written once to /data/config/runtime.env (root:root, 0600); supplying a different value later fails instead of silently rotating.

4.8 Migrations

Caution

Never stop the appliance during a boot-time migration, and never run an older image against a volume migrated by a newer one. Rollback = old image + its matching pre-upgrade backup restored into a new volume.

Notable migrations: 20260716120000_copy_supabase_users_to_better_auth copies Supabase auth.users into Better Auth tables during the Supabase → Better Auth upgrade.

Model retirement (catalog-as-code): set is_enabled: False in backend/data/llm_registry/catalog.py, then migrate existing graph nodes:

python -m backend.data.llm_registry.retire <slug> --replacement <slug> --yes

It is a dry run by default and revertable.

5. Deployment

5.1 Docker Compose (multi-container, from source)

git clone https://github.com/Significant-Gravitas/AutoGPT.git
cd AutoGPT/autogpt_platform
make init-env
docker compose up -d --build

✔ Container autogpt_platform-migrate-1       Exited
✔ Container autogpt_platform-rest_server-1   Started
✔ Container autogpt_platform-frontend-1      Started

Compose profiles:

Deployment checklist:

• [ ] make init-env run; ENCRYPTION_KEY, UNSUBSCRIBE_SECRET_KEY, BETTER_AUTH_SECRET populated
• [ ] DB_PASS, RABBITMQ_DEFAULT_*, VAPID keys replaced from published defaults
• [ ] FRONTEND_BASE_URL, PLATFORM_BASE_URL, BACKEND_CORS_ALLOW_ORIGINS match real origins
• [ ] JWT_JWKS_URL is HTTPS if backend and frontend are not on one host
• [ ] OAuth apps registered with callback <frontend>/auth/integrations/oauth_callback
• [ ] Only 3000 (and, if needed, 8006/8001) exposed through a TLS proxy; infrastructure ports not public
• [ ] Backups scheduled for Postgres (and FalkorDB if memory matters)

5.2 Docker: single-container appliance

docker run --detach --name autogpt \
  --restart unless-stopped \
  --shm-size 2g \
  --ulimit nofile=65536:65536 \
  --log-driver json-file \
  --log-opt max-size=50m \
  --log-opt max-file=5 \
  --env-file autogpt.env \
  --publish 127.0.0.1:3000:3000 \
  --volume autogpt-data:/data \
  "${IMAGE}"

Internals:

• Supervisor runs process groups; names are group-qualified (runtime:rest, state:postgres). supervisorctl status lists them.
• Shutdown is tuned to fit Docker's stock 10-second timeout: runtime processes are signalled first; PostgreSQL, RabbitMQ, Valkey, and FalkorDB get at most five seconds each; the event listener stops last (measured ~8.4 s). Do not shorten Docker's timeout.
• A watchdog allows 600 seconds for initial full health, then stops the container so --restart unless-stopped retries.
• A fatal-event listener (fatal_listener.py) and probes (probe.py: HTTP, AMQP, Redis/cluster) back autogpt-healthcheck.
• nginx and Next.js run under separate Unix identities; the frontend reaches PostgreSQL via a passwordless local peer role restricted to Better Auth tables/columns.

/data layout

Warning

Never mount one /data volume into two running containers, and never selectively mix service directories from different backups.

Optional processes: FalkorDB is mandatory. Chat-bot services default off; set AUTOGPT_ENABLE_BOT_SERVICES=true after configuring an adapter (Discord: AUTOPILOT_BOT_DISCORD_TOKEN; Telegram: token + webhook secret + a public HTTPS webhook).

Local models: on Docker Engine add --add-host host.docker.internal:host-gateway (Docker Desktop provides the hostname already).

5.3 Reverse Proxy / Load Balancing

Appliance. Keep the container bound to loopback and terminate TLS in a reverse proxy outside the container, forwarding to 127.0.0.1:3000; the appliance routes internally. Set AUTOGPT_PUBLIC_URL to the HTTPS origin:

AUTOGPT_PUBLIC_URL=https://agents.example.com

Example (nginx on the host):

server {
    listen 443 ssl;
    server_name agents.example.com;
    ssl_certificate     /etc/ssl/agents.crt;
    ssl_certificate_key /etc/ssl/agents.key;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}

Important

The bundled nginx records your proxy as the client. Your proxy must keep its own client-attribution logs and enforce per-client IP rate limits and access rules.

Caution

On Linux, Docker-managed port forwarding can bypass firewall rules expressed only through UFW. The 127.0.0.1: in --publish is the exposure control; publishing on a non-loopback address can expose the app regardless of INPUT-chain rules.

Compose. Route https://<host>/ → frontend :3000, and expose the backend API (:8006) and WebSocket (:8001) either on their own hostnames or paths, then set:

Note

backend/api/utils/cors.py rejects localhost origins in production (Production environment cannot allow localhost origins), including via regex patterns.

Horizontal scaling: webhook-style chat adapters ride the N-replica REST deployment (no dedicated pod); socket adapters (Discord Gateway, Slack Socket Mode) run in a separate copilot-bot process. Executors scale by adding executor replicas consuming the same RabbitMQ queues; cluster locks live in Redis.

6. Security

6.1 Authentication

Caution

The backend trusts whatever keys JWT_JWKS_URL returns. Over any untrusted network use HTTPS; a cleartext fetch lets an attacker substitute keys and forge tokens for any user. The backend refuses to boot with a cleartext non-local JWKS URL unless JWKS_ALLOW_INSECURE_TRANSPORT=true.

Account policy (appliance): allowlist by exact email or @domain; passwords ≥ 12 characters; AUTH_ALLOW_NEW_ACCOUNTS=false after bootstrap. Allowlisting compares the email asserted at signup — without email verification it is not proof of mailbox ownership.

6.2 Authorization & Access Control

Warning

BEHAVE_AS=local also enables blocks disabled in hosted mode, self-host model routing, and different diagnostics/telemetry. Any multi-tenant deployment must use BEHAVE_AS=cloud — and even then the appliance frontend is compiled in local mode, so the appliance is not a turnkey multi-tenant distribution.

6.3 TLS / Certificates

• AutoGPT does not terminate TLS itself; terminate at a reverse proxy.
• For LAN splits, use locally trusted certificates (e.g. mkcert) and point JWT_JWKS_URL at the https:// URL.
• Production OAuth redirect URIs must be HTTPS.
• Telegram and Teams webhooks require public HTTPS endpoints.

6.4 Secrets handling

Suspected exposure of appliance secrets: there is no in-place rotation. Isolate the installation, revoke external provider and OAuth credentials, build a new installation on a new volume, move only non-secret agent definitions via export/import, and reconnect credentials. Restoring an older backup does not rotate anything.

6.5 Input validation and network exposure

6.6 Security hardening checklist

• [ ] Loopback-only publish + external TLS proxy
• [ ] Signup allowlist during bootstrap, then AUTH_ALLOW_NEW_ACCOUNTS=false
• [ ] No published defaults in use (DB_PASS, RabbitMQ creds, VAPID keypair, pre-v0.7.4 ENCRYPTION_KEY)
• [ ] HTTPS JWT_JWKS_URL for any split deployment
• [ ] BEHAVE_AS=cloud for anything multi-tenant
• [ ] ClamAV enabled (Compose) or uploads restricted (appliance)
• [ ] Unauthenticated local model servers not exposed to the internet
• [ ] Backups encrypted (they contain plaintext secrets and user content)
• [ ] Webhook URLs for unsigned providers treated as secrets

7. Operations

7.1 Start, stop, restart

Note

Agent runs executing when services stop are abandoned: queue messages can be dropped and rows can stay RUNNING. They do not resume.

7.2 Upgrades

Compose:

1. git pull the release.
2. Diff each .env against its .env.default and copy new keys (make init-env won't merge them).
3. docker compose build migrate rest_server && docker compose run --rm migrate.
4. docker compose up -d --build.

Appliance:

1. Record the running image reference and ID: docker inspect --format '{{.Config.Image}} {{.Image}}' autogpt.
2. Pull/build the new image while the old one runs.
3. export RESTART_AFTER_BACKUP=false, run the cold-backup block once, then unset RESTART_AFTER_BACKUP.
4. docker rm autogpt (stopped container only).
5. Re-run the original docker run with the new image reference.
6. Wait for health; test login, memory, one agent execution, streaming, WebSockets, and persistence across one restart.

Secret-generation upgrade (installs from before per-install secrets): stop, export OLD_ENCRYPTION_KEY (for never-set keys it's the .env.default value at tag autogpt-platform-beta-v0.7.4), blank the three secret lines, make init-env, build + migrate, run cli rotate-encryption-key (dry run) then --apply, clear platform."UserAuthJwks" if BETTER_AUTH_SECRET changed, and start. Do the re-encryption before starting the stack on the new key.

Supabase → Better Auth upgrade: the database moves to pgvector/pgvector:pg15 at autogpt_platform/data/db/data; old data remains at autogpt_platform/db/docker/volumes/db/data. Either reuse the data directory (same major version; may fail on missing Supabase extensions/roles) or dump/restore with --no-owner --no-privileges, dropping the auth shim schema first. Users are copied by migration 20260716120000_copy_supabase_users_to_better_auth. frontend/scripts/migrate-supabase-auth.ts is only for live cutovers. Neither data path has been validated against a real old volume — back up first.

7.3 Logging

Log style (backend convention): %s deferred interpolation in debug, f-strings elsewhere; error messages use os.path.basename() to avoid leaking paths.

7.4 Monitoring & Health Checks

curl -s http://localhost:8006/health

{"status":"healthy"}

Built-in alerting (via configured Discord channels / notifications):

Load testing: autogpt_platform/backend/load-tests/ (k6). Targets: core API P95 < 2 s, marketplace P95 < 5 s, success > 95 %.

cd autogpt_platform/backend/load-tests
node generate-tokens.js --count=160
node orchestrator/orchestrator.js DEV local

7.5 Backup & Restore

Compose. Back up PostgreSQL (and FalkorDB if you rely on memory) with service-native tools:

docker compose exec db pg_dump -U postgres -d postgres -Fc -f /tmp/autogpt.dump
docker compose cp db:/tmp/autogpt.dump ./autogpt.dump

Also preserve backend/.env — especially ENCRYPTION_KEY, without which restored credentials are unreadable.

Appliance cold backup. The documented block (in docs/platform/single-container.md):

• refuses anonymous volumes and a stopped/crashed appliance;
• takes an atomic lock (a stopped helper container named autogpt-backup-lock);
• captures the exact image ID/digest, stops the appliance, and tars /data read-only with --network none, excluding ./cache;
• writes autogpt-data-<UTC timestamp>.tgz plus .sha256, promoting from .partial only on success;
• restarts the appliance unless RESTART_AFTER_BACKUP=false.

Caution

Backups are plaintext and contain user content, provider credentials, auth keys, and database passwords. Encrypt them and delete staging copies. Stale *.partial files from interrupted runs may also contain secrets. After a SIGKILL/host crash, confirm no backup is running, then remove a stale lock with docker rm --volumes autogpt-backup-lock.

There is no supported hot backup for the appliance's coupled volume.

Restore always goes into a new named volume (autogpt-data-restored-<ts>-<pid>-<random>), verifies the SHA-256, labels the volume with a per-run owner, extracts with --network none, then validates the layout offline (runtime.env, backend.json, PG_VERSION, Postgres configs, RabbitMQ mnesia, three Valkey dirs, FalkorDB, workspaces, store-media, homes) and rejects unsafe Postgres configuration. Only then launch with the recorded image, env file, publish spec, and optional ADD_HOST_SPEC.

Warning

tar runs as root during restore and preserves ownership and setuid bits. Only restore archives from a trusted backup process. A full recovery rehearsal boots live schedules and credentials — do it on an egress-filtered host after revoking production credentials.

8. Performance Tuning

Tip

If requests stall under concurrent runs, inspect backend and PostgreSQL logs for pool exhaustion before changing limits. On the appliance, the fixed pools are the ceiling — move to a distributed deployment when they're insufficient.

Batch LLM work: the BatchExecutor polls submitted LLM batches (Anthropic) so slow batch polls never starve the scheduler's cron tick; the memory "dream pass" uses it when an Anthropic key is configured and falls back to a synchronous baseline otherwise.

9. Integrations

9.1 API Internals

The backend is one FastAPI app (backend/api/rest_api.py) with feature routers mounted under /api, the External API mounted as a sub-app at /external-api, and /health.

Router mount map (selected)

Graph routes (/api)

Library routes (/api/library)

External API v1 (/external-api/v1)

Additional External API modules (external/v1/integrations.py, tools.py) expose integration management and platform tools under the same prefix; the Swagger UI at /external-api/docs is authoritative.

Export the OpenAPI schema:

cd autogpt_platform/backend
poetry run export-api-schema --output openapi.json --pretty

The frontend's typed client is generated with pnpm generate:api-client.

Error semantics: 400 bad parameters, 401 invalid/expired credentials, 403 missing scope/permission, 404 missing resource, 429 AutoPilot spend cap, 503 paywall tier-lookup failure on execute.

9.2 Webhooks

Inbound triggers. A webhook-triggered block declares webhook_config (BlockWebhookConfig), an event filter input (a Pydantic model of booleans whose field name matches webhook_config.event_filter_input), a payload input, and a credentials input with scopes sufficient to manage webhooks. A provider's WebhooksManager (subclass of BaseWebhooksManager in integrations/webhooks/_base.py) registers/deregisters webhooks with the provider and validates payloads; register it in load_webhook_managers in integrations/webhooks/__init__.py. Webhook records live in IntegrationWebhook.

Generic ingress URL:

https://<backend>/api/integrations/generic_webhook/webhooks/<webhook-id>/ingress

Important

Override verify_signature with hmac.compare_digest for any provider that signs deliveries and raise fastapi.HTTPException(403) on failure. For unsigned providers, the webhook UUID is a bearer secret — document that.

Stripe billing webhooks use STRIPE_WEBHOOK_SECRET; Postmark webhooks use POSTMARK_WEBHOOK_TOKEN.

Chat-bot webhooks. copilot/bot/ implements a connector taxonomy:

Factories: app.py::_build_socket_adapters, webhook_routes.py::_build_webhook_adapters — each gated on its tokens being set. Messaging: link check → Link Account prompt or thread creation → Redis-subscribed thread (7-day TTL) → streamed AutoPilot reply chunked at chunk_flush_at → messages arriving mid-stream batched into one follow-up turn.

Teams specifics: signed Bot Framework JWT (auth the sender, not the body — serviceurl claim binding closes replay); replies go to the activity's serviceUrl (host-allowlisted); single-tenant only (MICROSOFT_TENANT_ID mandatory since 2025-07-31); no native slash commands in channels (must @mention); group chats accepted and ignored; at-most-once delivery via a Redis activity-id claim; the learned serviceUrl map is per process. Local testing with the M365 Agents Playground requires both APP_ENV=local and AUTOPILOT_BOT_TEAMS_ALLOW_UNVERIFIED=true.

9.3 Plugin / Extension System: blocks

Blocks are the extension point. Every .py under backend/blocks/ is auto-imported at startup (except __init__.py and test_* files); no registration needed.

Block anatomy

Runtime kwargs available to run(): user_id, graph_id, graph_exec_id, node_exec_id, node_id, execution_context (ExecutionContext: user_id, graph_exec_id, workspace_id, session_id — required for file handling).

Yield rules: prefer one result object at a time; for lists, yield each item and optionally the whole list. Yielding error stops the node and marks it failed; prefer raising.

Errors: raise BlockInputError (invalid input) or BlockExecutionError (user-addressable runtime failure) from backend.util.exceptions; bare ValueError is auto-wrapped. Don't wrap logic in blanket try/except, and don't catch infrastructure failures (out of credits, DB down, internal 5xx) — let them surface.

Files: store_media_file(file=..., execution_context=..., return_format=...):

Credentials

Use credentials.auth_header() or credentials.api_key.get_secret_value() / credentials.access_token.get_secret_value(). Blocks that need OAuth with no API-key fallback should disable themselves when OAuth isn't configured (Google uses GOOGLE_OAUTH_IS_CONFIGURED).

Frontend: add frontend/public/integrations/{provider_name}.png (missing icon = broken image in the Blocks menu). Provider names, descriptions, and auth types are fetched from GET /integrations/providers — no frontend registration needed.

Networking: always use backend.util.request.Requests / backend.sdk.Requests (SSRF protection).

Docs sync (CI-enforced):

cd autogpt_platform/backend
poetry run python scripts/generate_block_docs.py

Writes docs/integrations/block-integrations/{provider}/{module}.md; the "Block Documentation Sync Check" workflow fails PRs whose docs drift. Preserve hand-written content between <!-- MANUAL: use_case --> … <!-- END MANUAL --> (sections how_it_works, use_case, extras, file_description, additional_content).

Integration checklist

• [ ] Provider name registered (ProviderName or ProviderBuilder)
• [ ] Credentials in _auth.py / SDK config; description + auth types in _config.py
• [ ] Input/Output schemas, real UUID, categories, async run()
• [ ] BlockInputError / BlockExecutionError for user-fixable errors
• [ ] Inline tests and/or {name}_test.py
• [ ] Icon PNG added
• [ ] Block docs regenerated

Reference implementations: blocks/firecrawl/ (simple API key), blocks/linear/ (OAuth + API key), blocks/exa/ (webhooks), blocks/github/ (triggers + OAuth), blocks/zerobounce/ (_auth.py/_config.py pattern), blocks/typesafe/ and blocks/slant3d/ (documented provider packages).

9.4 LLM model catalog

Models, costs, and AutoPilot routing are catalog-as-code in backend/data/llm_registry/catalog.py. Block-selectable models also need a line in backend/data/llm_registry/llm_models.py (an import-time check enforces pairing). Catalog-only diffs may ship via hotfix/* → master.

9.5 MCP integrations

Hosted MCP services appear in Settings → Integrations with an MCP badge; catalog maintenance is documented in docs/platform/contributing/hosted-mcp-catalog.md. Open issue #15032 notes that AutoPilot's find_capability doesn't yet search user-connected custom MCP servers.

10. Developer Internals

10.1 Branching and contribution

10.2 Backend code conventions (from backend/AGENTS.md)

• Top-level, absolute imports (single-dot relative allowed within a package).
• No duck typing for dispatch; Pydantic models over dicts/dataclasses.
• No linter suppressors (# type: ignore, # noqa).
• Files under ~300 lines; functions under ~40 lines; top-down ordering.
• Security() (not Depends()) for auth dependencies so OpenAPI shows security.
• Redis pipelines with transaction=True for multi-step atomicity; TOCTOU awareness for file access and credit charging; max(0, value) guards.
• SSE: data: lines for parsed events (must match the frontend Zod schema), : comment lines for heartbeats.

10.3 Key classes

10.4 Classic AutoGPT internals

Caution

Classic has known vulnerabilities in its dependencies and will not be updated. Don't deploy it on a network-reachable host.

10.5 Testing Strategy

Mocking rule: patch where a symbol is used (e.g. backend.blocks.my_provider.my_block.Requests.post), use AsyncMock for async. Block test files ending _test.py are auto-imported at startup — keep them side-effect-free, or name them test_*.py to opt out.

11. Troubleshooting

Boot and configuration

Error: ENCRYPTION_KEY is not set

Cause: Blank ENCRYPTION_KEY. Solution: make init-env, restart. Prevention: Include make init-env in provisioning.

Error: ENCRYPTION_KEY is set to a value that was published…

Cause: Pre-v0.7.4 default key. Solution: Run the secret-generation upgrade with OLD_ENCRYPTION_KEY and cli rotate-encryption-key --apply.

Error: ENCRYPTION_KEY is not set, so there is no key to re-encrypt under.

Cause: rotate-encryption-key run before a new key was set. Solution: Set the new ENCRYPTION_KEY first.

Error: --old-key is the configured ENCRYPTION_KEY. Change ENCRYPTION_KEY first, then pass the previous value here.

Solution: Put the new key in ENCRYPTION_KEY; pass the old one via --old-key/OLD_ENCRYPTION_KEY.

Error: Not a valid encryption key: ...

Solution: Generate a Fernet key: poetry run cli gen-encrypt-key.

Error: ENCRYPTION_KEY must be a Fernet-compatible key / must decode to exactly 32 bytes

Solution: Same — use a Fernet key, not an arbitrary string.

Error: JWT_JWKS_URL must be set to the JWKS endpoint of the platform auth service ...

Solution: Set JWT_JWKS_URL (e.g. http://frontend:3000/api/auth/jwks inside Compose).

Error: JWT_JWKS_URL fetches keys over cleartext http:// from a non-local host ('...')

Solution: Use HTTPS, or on a trusted isolated network set JWKS_ALLOW_INSECURE_TRANSPORT=true.

Error: Invalid JWT_JWKS_ALGORITHMS entry: '...'

Solution: Only asymmetric algorithms (ES256, RS256, EdDSA).

Error: 'cryptography' package is required for JWT verification but not installed

Solution: Reinstall backend dependencies (poetry install).

Error: Production environment cannot allow localhost origins

Also ... via regex: <pattern> and Production regex pattern matches localhost/127.0.0.1: <pattern>. Solution: Remove localhost entries from BACKEND_CORS_ALLOW_ORIGINS in production.

Error: <Class>.expected_token is not set; either specify it or provide a custom validator

Cause: An API-key-protected internal route has no expected token configured. Solution: Set the corresponding token (e.g. POSTMARK_WEBHOOK_TOKEN for Postmark webhooks).

Error: Database is not connected (HTTP 5xx from /health)

Cause: Postgres unreachable or wrong DATABASE_URL. Solution: Check db health and credentials; confirm migrate completed.

Error: the specified Containerfile or Dockerfile does not exist

Cause: Podman. Solution: Use Docker.

db unhealthy on Windows

Solution: Switch Docker Desktop to the WSL 2 engine.

Nobody can reach the backend after rotating BETTER_AUTH_SECRET

Solution: DELETE FROM platform."UserAuthJwks"; then restart; keys regenerate on next sign-in.

Credentials marked revoked after starting on a new key

Solution: Stop, run rotate-encryption-key --apply, restart; users who reconnected in between must reconnect older credentials.

Supabase data directory restart-loops on pgvector/pgvector:pg15

Solution: Use the dump/restore fallback; drop the auth shim schema before pg_restore; verify select count(*) from auth.users before migrating.

Frontend (outside Docker) can't authenticate

Cause: Next.js reads only .env. Solution: make init-env; ensure DATABASE_URL and BETTER_AUTH_SECRET are in frontend/.env.

Appliance runtime configuration

Error: AUTOGPT_PUBLIC_URL must use http or https

Siblings: must include a host, must not include credentials, must be an origin without path, query, or fragment, has an invalid port, has an invalid host. Solution: A bare origin.

Error: <NAME> differs from the value persisted on first boot; restore the original value or start with a new data volume

Solution: Remove the override; generated secrets cannot be rotated in place.

Error: runtime configuration has missing or unknown keys / unsupported runtime configuration version / invalid runtime configuration line N

Cause: /data/config/runtime.env was edited or is from an incompatible version. Solution: Don't edit runtime.env; restore it from backup or start a new volume.

Error: runtime configuration is not a regular file: <path> / refusing symlink at <path>

Solution: Replace the symlink/special file with the original regular file.

Error: RABBITMQ_DEFAULT_USER may not use the built-in guest account / contains unsupported characters

Solution: Pick another username.

Error: <NAME> must be at least 32 URL-safe characters / invalid URL-safe base64 value

Solution: Provide a longer URL-safe value, or let the appliance generate it.

Error: VAPID_PRIVATE_KEY and VAPID_PUBLIC_KEY must be set together

Also VAPID_PRIVATE_KEY must decode to exactly 32 bytes, VAPID_PUBLIC_KEY must be an uncompressed P-256 public key, cryptography is required to generate VAPID keys. Solution: Generate a proper pair or set neither.

Startup rejects DB_CONNECTION_LIMIT / DB_CONNECT_TIMEOUT / DB_POOL_TIMEOUT

Solution: Ranges 1–5, 1–600, 1–3600.

Startup rejects legacy JWT secrets

Solution: Remove JWT_VERIFY_KEY and SUPABASE_JWT_SECRET on fresh installs; for legacy migration set AUTOGPT_ENABLE_LEGACY_AUTH=true and both to the same ≥32-character secret.

Startup stops because email verification is enabled

Solution: AUTH_REQUIRE_EMAIL_VERIFICATION=false (unsupported in the appliance).

Health probe errors: AMQP credentials are missing / AMQP connection failed

Solution: Check RabbitMQ state in /data/rabbitmq and logs for the state:rabbitmq process.

Health probe errors: Redis authentication failed / Redis cluster is not healthy / Redis did not return PONG / Redis closed the connection

Solution: Inspect Valkey process logs; confirm the three nodes (17000–17002) started; check disk space in /data/valkey.

Health probe error: HTTP <status> from <url>

Solution: The named internal HTTP service is failing; read its supervisor log.

Supervisor errors: Supervisor event payload is too large / ended unexpectedly / has an unsupported type / has an invalid payload length

Cause: The fatal-event listener received malformed events. Solution: Restart the container; if recurring, capture logs for an issue report.

Container stays starting / becomes unhealthy

Solution: docker exec autogpt autogpt-healthcheck, then the logs for the first failed service. The watchdog stops the container after 600 s.

OOM-killed during startup

Solution: More memory; the appliance needs more than 5–6 GiB.

Interrupted migration blocks startup

Solution: Empty install → discard volume; existing → restore backup. prisma migrate resolve only from a separate recovery environment after verifying the DB state.

Data missing after replacing the container

Solution: Reattach the original named volume (check with the /data mount inspect command).

Backup refuses to run

Messages: Refusing backup because /data uses an anonymous volume, ... another backup may be running or its lock is stale, ... the autogpt container is not running, Refusing to overwrite an existing backup. Solution: Use a named volume; clear a stale autogpt-backup-lock only after confirming no backup is running; start and verify health first.

Restore refuses to run

Messages: Backup checksum verification failed, Refusing to reuse existing volume, ... ownership cannot be verified. Solution: Use a trusted archive/checksum pair and a fresh volume name.

Runtime and capacity

Runs stuck in RUNNING after restart

Solution: Start new runs; abandoned runs never resume.

Requests stall under concurrent runs

Solution: Check for pool exhaustion; reduce concurrency or scale out (appliance pools are capped at 5).

Valkey or FalkorDB memory/disk keeps growing

Cause: No appliance-level ceiling or eviction. Solution: Monitor, back up, and move to a distributed deployment for growth.

/setup fails with httpx.ConnectError

Solution: Start platform_linking_manager (--profile bot).

Teams bot replies 404 for some tenants

Cause: Per-process serviceUrl map; a cold replica falls back to the default host. Solution: Keep replies reactive; persist the mapping in Redis before enabling proactive sends.

Teams bot drops a turn

Cause: At-most-once delivery (claim before processing). Solution: Ask the user to resend; release the claim on failure if you prefer retries over duplicates.

AutoPilot 401 / 429

Solution: 401 → set the transport's key (OPEN_ROUTER_API_KEY for the default route, OPENAI_API_KEY for memory); 429 → spend cap reached.

Local memory ingestion fails

Solution: Pull the embedding model; set GRAPHITI_LLM_MODEL, GRAPHITI_RERANKER_MODEL, GRAPHITI_EMBEDDER_MODEL to slugs your server serves.

ValueError: graph_exec #<id> not found for user #<user> (WebSocket subscribe)

Cause: Client subscribed to an execution it doesn't own or that doesn't exist. Solution: Verify the execution ID and user.

ValueError: Execution <id> not found

Solution: The execution was deleted or belongs to another user.

Schedule fires after its expert workflow was removed

Cause: Open issue #14607. Solution: Delete the schedule manually.

Development

Block shows a broken icon

Solution: Add frontend/public/integrations/{provider}.png.

CI "Block Documentation Sync Check" fails

Solution: poetry run python scripts/generate_block_docs.py, commit.

Block test fails with a type error on credentials

Cause: Missing CredentialsMetaInput[Literal[ProviderName.X], Literal["api_key"]] type hint. Solution: Add the full type hint.

Block module side effects run at startup

Cause: *_test.py files are auto-imported. Solution: Keep them side-effect-free or rename to test_*.py.

prisma generate writes to the global interpreter

Solution: pip uninstall prisma, rerun poetry run prisma generate.

OAuth tool: At least one scope is required / Invalid scope: ...

Solution: Pass --scopes with valid scope names (e.g. EXECUTE_GRAPH,READ_GRAPH).

CLI: Invalid --range '...'; use forms like '7', '6-10', '6-', '-10'. / start is after end

Solution: Fix the cli chat view range.

Load tests: No valid authentication token available / Token has expired

Solution: node generate-tokens.js --count=160 (24-hour tokens).

Load tests show 5 VUs in k6 cloud

Solution: k6 cloud run --env K6_ENVIRONMENT=DEV --env VUS=160 test.js.

Direct benchmark: Unknown benchmark: <name>. Available: ... / Workspace not initialized

Solution: Use gaia, swe-bench, or agent-bench; pass a valid --workspace.

12. Potential Improvements

13. Quick Reference

Paths

Ports

Commands

Critical settings