AutoGPT — User Guide

AutoGPT is an open-source platform for building, deploying, and running AI agents that carry out complete workflows. You describe an outcome in plain English (AutoPilot) or wire every step yourself on a visual canvas (Build), then run the agent on demand, on a schedule, or from a webhook trigger. The same repository powers the paid, hosted AutoGPT Platform at platform.agpt.co and the free self-hosted deployment you run on your own infrastructure.

This guide is for people who use AutoGPT: running it, building agents, connecting integrations, scheduling work, and troubleshooting. Architecture, the complete configuration reference, security hardening, and internals live in the companion Admin Guide.

Note

The repository contains two products. autogpt_platform/ is the current, maintained AutoGPT Platform and is the subject of almost all of this guide. classic/ is the original 2023 autonomous agent (plus the forge framework and a benchmark harness). Classic is officially unsupported and receives no dependency updates; it is covered briefly in Classic AutoGPT for completeness.

1. Quick Start

You have two paths. Pick the one that matches what you want.

1.1 Fastest path: the hosted Platform

1. Sign up at https://platform.agpt.co/signup.
2. Open AutoPilot and describe a job, for example: "Build me an agent that takes a blog topic as input, generates an outline, then writes the full article."
3. Review the agent AutoPilot creates, then run it from your Agents library.

No API keys or infrastructure are required on the hosted Platform; some plans include managed AI providers.

1.2 Fastest self-hosted path: from source with Docker Compose

This is the currently supported self-hosting path on Linux, macOS, and Windows.

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

[+] Running ... containers
 ✔ Container autogpt_platform-db-1        Healthy
 ✔ Container autogpt_platform-migrate-1   Exited
 ✔ Container autogpt_platform-rest_server-1  Started
 ✔ Container autogpt_platform-frontend-1  Started
 ...

Open http://localhost:3000, create an account, and open Build.

Important

Run make init-env before docker compose up. It creates each .env from its .env.default and generates the three secrets the defaults deliberately leave blank (ENCRYPTION_KEY, UNSUBSCRIBE_SECRET_KEY, BETTER_AUTH_SECRET). The backend refuses to start while ENCRYPTION_KEY is empty.

1.3 Your first agent (no API key needed)

The Calculator agent uses no model provider, so it is the best way to confirm a fresh self-hosted install works:

1. Open Build.
2. Add two Input blocks; name them a and b.
3. Add a Calculator block and connect a → Calculator a, b → Calculator b.
4. Add an Output block named results and connect Calculator's result to its value.
5. Press Ctrl+S (Cmd+S on macOS), name the agent, and save.
6. Run it with 227 and 17 and the Multiply operation.

results: 3859

Tip

Provider keys are not required to boot, create an account, use Build, or run provider-free blocks. Model-backed blocks return a clear missing-credential error until you configure a provider.

2. Installation

2.1 Choose an installation method

Warning

The self-hosting guide in the repository says it plainly: do not follow outside tutorials — they will likely be out of date. The platform's setup, auth stack, and secret handling have changed substantially (for example the switch from Supabase to the built-in Better Auth service).

Note

The hosted release installer (setup.agpt.co/install.sh) still serves the older Compose installer, and the appliance image tags are not public until the maintainers' release gates pass. Until then — and always on Windows — use the from-source setup.

2.2 Requirements

Caution

Podman and podman-compose are not supported. They cause path-resolution failures, particularly on Windows (see Troubleshooting).

Verify your tools:

git --version
node -v
npm -v
docker -v
docker compose version

git version 2.x
v20.x
10.x
Docker version 2x.x
Docker Compose version v2.x

2.3 Install from source (Docker Compose)

Linux / macOS

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

✔ Container autogpt_platform-frontend-1  Started

Windows (Docker Desktop + WSL 2)

Enable the WSL 2 engine first (Docker Desktop → Settings → General → Use the WSL 2 based engine, then restart Docker Desktop). Then, in a shell with make and python3 available (for example a WSL 2 distribution):

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

Without make, run the equivalent steps by hand:

cp -n .env.default .env
cp -n backend/.env.default backend/.env
cp -n frontend/.env.default frontend/.env
python3 single-container/runtime_config.py fill-env --path .env
python3 single-container/runtime_config.py fill-env --path backend/.env
python3 single-container/runtime_config.py fill-env --path frontend/.env
docker compose up -d --build

Warning

On Windows, select WSL 2 rather than Hyper-V. Hyper-V can cause the db (Postgres) container to be marked unhealthy. Switching an existing Docker Desktop to WSL 2 may erase existing containers and build history — back up anything important first.

What make init-env does

Important

make init-env does not merge newly added variables into an .env you already have. After upgrading, diff each .env against its .env.default and copy new keys across yourself.

Default ports (Compose)

Check that it is running by visiting http://localhost:3000, or probe the API:

curl http://localhost:8006/health

{"status":"healthy"}

2.4 Docker: single-container appliance (experimental)

The appliance packages the frontend and backend together with PostgreSQL, a three-node Valkey cluster, RabbitMQ, nginx, and FalkorDB in one container. Only nginx listens publicly, on container port 3000. All durable state lives under /data.

Step 1 — Pick an image.

IMAGE=significantgravitas/autogpt:latest
docker pull "${IMAGE}"

Or build from source (from the repository root):

docker buildx bake \
  --file autogpt_platform/single-container/docker-bake.hcl \
  --load \
  single-container
IMAGE=autogpt-platform:single-container-dev

Step 2 — Create a private environment file.

umask 077
touch autogpt.env
chmod 600 autogpt.env

Add at least:

AUTOGPT_PUBLIC_URL=http://localhost:3000
AUTH_SIGNUP_ALLOWLIST=[email removed]

Step 3 — Start the 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}"

Step 4 — Wait for health, then create and promote the administrator.

docker inspect --format '{{.State.Health.Status}}' autogpt

starting

Repeat until it reports:

healthy

Open http://localhost:3000, sign up with the allow-listed email (passwords need at least 12 characters), then:

docker exec autogpt autogpt-admin promote [email removed]

Sign out and back in so your session picks up the administrator role.

Step 5 — Close signup. Add to autogpt.env:

AUTH_ALLOW_NEW_ACCOUNTS=false

Replace only the container (the named volume is kept):

docker stop autogpt
docker rm autogpt

Then repeat the Step 3 docker run command.

Caution

Do not stop the container while the first boot is applying database migrations. An interrupted migration makes later boots refuse to continue. For a brand-new empty install, remove the unused volume and start again; for an existing install, restore the pre-upgrade backup.

Warning

If you omit AUTH_SIGNUP_ALLOWLIST, anyone who can reach the published port can create an account until you set AUTH_ALLOW_NEW_ACCOUNTS=false. Bootstrap the admin while the app is still loopback-only.

2.5 Local development setup (contributors)

Backend (Poetry)

Requires Python >=3.10,<3.14 and Poetry.

cd autogpt_platform
make start-core
cd backend
poetry install --with dev
poetry run app

make start-core runs docker compose up -d deps (Postgres, Redis, RabbitMQ). poetry run app starts the backend.

Frontend (pnpm)

Requires Node.js and pnpm.

cd autogpt_platform
docker compose --profile local up deps_backend --build --detach
cd frontend
pnpm install
pnpm generate:api-client
pnpm dev

Note

When the frontend runs outside Docker, Next.js only reads .env (not .env.default), and the embedded auth service needs DATABASE_URL and BETTER_AUTH_SECRET from it. Run make init-env first.

2.6 Setup verification checklist

• [ ] docker compose ps (or docker inspect ... autogpt) shows all services healthy
• [ ] http://localhost:3000 loads and you can create an account
• [ ] curl http://localhost:8006/health returns {"status":"healthy"} (Compose)
• [ ] The Calculator agent from Quick Start runs
• [ ] At least one model provider key is set if you want AI blocks or AutoPilot
• [ ] Signup is restricted (AUTH_SIGNUP_ALLOWLIST) or closed (AUTH_ALLOW_NEW_ACCOUNTS=false) before any non-loopback exposure

3. Configuration Basics

Self-hosted AutoGPT is configured entirely through environment files. This section covers only what you need to run; every setting is documented in the Admin Guide's Configuration Mastery chapter.

3.1 Where settings live

Precedence (Compose): .env.default → .env → Compose environment: → your shell environment (highest).

Important

.env.default files are public. Never put a working secret in them. Secrets belong in your .env files (or autogpt.env), which make init-env generates per machine.

3.2 Environment Variables

Model providers (backend .env) — add only the ones you use

After adding keys to a Compose install, restart:

docker compose down && docker compose up -d

AutoPilot model routing

Tip

For the local profile, pull the chat and embedding models on the Docker host and raise Ollama's context window — AutoPilot's system prompt is roughly 8k tokens:

ollama pull hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M
ollama pull nomic-embed-text

Set OLLAMA_CONTEXT_LENGTH=32768 on the Ollama server (not in AutoGPT's env file) and restart Ollama.

Note

CHAT_API_KEY must be non-empty even when the local server ignores it. Under the local transport, extended-thinking mode is automatically downgraded to fast.

Accounts and URLs

Email (optional, for password reset)

POSTMARK_SERVER_API_TOKEN=
POSTMARK_SENDER_EMAIL=
POSTMARK_WEBHOOK_TOKEN=

Warning

Without Postmark there is no self-service password reset and no CLI to reset a password. Store the administrator password securely before closing signup.

AutoPilot spend caps (appliance defaults to disabled)

CHAT_DAILY_COST_LIMIT_MICRODOLLARS=5000000
CHAT_WEEKLY_COST_LIMIT_MICRODOLLARS=20000000

Values are in microdollars (1 USD = 1000000). -1 disables a cap. The daily window resets at midnight UTC; the weekly window at Monday 00:00 UTC.

3.3 OAuth apps for integration blocks

Integration blocks that use OAuth need your own OAuth application credentials in backend/.env. The callback URL for every provider is:

<your_frontend_url>/auth/integrations/oauth_callback

For a default local install: http://localhost:3000/auth/integrations/oauth_callback.

Note

Google blocks have no API-key fallback, so they are disabled until Google OAuth is configured. The appliance's prebuilt frontend cannot configure Google Picker public keys at runtime.

4. Everyday Usage

4.1 Navigating the platform

4.2 Build an agent on the canvas

The builder has a canvas, a Blocks menu on the left, and a Save button.

Block types

Input and output blocks define the agent's schema — the only parts a person running the agent sees.

Add and connect blocks

1. Open the Blocks menu, browse categories or search.
2. Click a block to place it on the canvas.
3. Click an output pin, then an input pin (or drag between them) to draw a connection.
4. Configure settings directly on the block — for example, choose the model on AI Text Generator, or hardcode a value on an input pin instead of connecting it.

Tip

Name your Input and Output blocks clearly. Those names become the labels users see on the run form and results.

Pin types

Connections are only allowed between compatible pin types.

Save

• Press Ctrl+S / Cmd+S, or click Save.
• Saving creates or updates an agent graph version in your library.
• The builder keeps a local recovery draft while you edit; a successful save clears it.

Note

Publishing to the Marketplace is a separate action from saving.

4.3 Credentials inside the builder

If a block needs a credential you have not connected, a credential bar appears on the block. Connect via OAuth, API key, or username/password depending on the service, or pick an existing compatible credential.

4.4 Run an agent

1. Open Agents and click the agent.
2. Click New agent task.
3. Fill in inputs and credentials.
4. Click Start Task.

The task runs immediately. While it runs, coloured beads slide along connection lines on the canvas to show data flowing from output pins to input pins.

4.5 View task results and cost

4.6 Manage your library

Caution

Deleting an agent is permanent and cannot be undone.

4.7 Use AutoPilot

AutoPilot (/copilot) performs supported platform actions through conversation:

AutoPilot requests missing inputs or credentials before running anything.

Tip

Be specific. "Build me an agent that takes a blog topic as input, generates an outline with Claude, then writes the full article" works far better than "make me an agent."

4.8 Use the Marketplace

1. Open Marketplace; search or browse by category.
2. Open an agent page (title, description, creator, video, output showcase, instructions).
3. Click Add to Library. If you already have it, the button reads See Runs.

Marketplace agents open read-only. To change one, open it in the builder and click Duplicate to create an editable fork; your fork never modifies the listing.

For a self-hosted instance, use Download here under "Want to use this agent locally?" on the listing, then import the JSON into your library.

4.9 Templates

Templates save a completed task's inputs and selected credential references (never the secrets themselves) for reuse.

Note

A template is pinned to the graph version it came from; later edits to the agent do not update it.

4.10 Share results

1. Open the completed task and click Share results.
2. Review the public-access warning and click Enable Sharing.
3. Copy the Share URL. Use Stop Sharing in the same dialog to revoke.

Warning

Anyone with a share URL can view the run's outputs. Inputs are not published, but outputs may contain sensitive data. Copying the normal (authenticated) task URL does not create a public link.

4.11 Integrations and credentials

Open Settings → Integrations (/settings/integrations) to add, review, or remove credentials centrally, or connect them in context when a block or task asks.

MCP services: services with an MCP badge in Settings → Integrations (also listed in Connect Service) can be connected by sign-in/token, or with No sign-in → Check connection for public tools. Some ask for your region or an official server URL; Allow changes adds a service's optional write actions.

Warning

Removing a credential can break agents, workflows, or active webhooks that reference it. Read the dependency warning before confirming.

4.12 Credits and billing (hosted Platform)

Note

Self-hosted installs run with BEHAVE_AS=local, which bypasses subscription entitlement gating. You pay model providers directly.

5. Common Workflows

5.1 Q&A agent with an AI model

Requires: a model provider key (self-hosted) or a hosted account.

1. Add Input (name it question), AI Text Generator, and Output (name it answer).
2. Connect Input result → AI Text Generator Prompt; AI Text Generator response → Output value.
3. Save as "question and answer".
4. Run with How far is Earth from Pluto?.
5. Read the answer in Agent Outputs or via View More.

5.2 Reuse an agent as a block

Every saved agent is also available as a block in other agents.

1. Build and save a base agent (for example Input question → AI Text Generator → Output answer, saved as "Weather Agent").
2. In another agent, open the Blocks menu, click the agent tag or search for "Weather Agent".
3. Add it and connect its question input and answer output like any other block.

Tip

Compose research → writing → editing → formatting agent blocks to build larger pipelines from proven parts.

5.3 Process a list item by item

Blocks can emit a whole list or each item one at a time, and some blocks iterate over an incoming list, yielding each item.

1. Use a block that outputs a list of URLs.
2. Feed it into an iterating block.
3. Connect each yielded item to an AI block.
4. Collect results in an Output block.

5.4 Robust error handling

A failing block does not stop the whole agent; it produces data on its error pin.

Tip

During development, wire error pins to Output blocks so you can see failures; add real fallbacks once the agent works.

5.5 Run an agent every weekday morning

1. Open the agent → New agent task.
2. Fill every input.
3. Click Schedule Task (next to Start Task).
4. Set Schedule Name, Repeats (e.g. Weekly), Repeats On (e.g. weekdays), At (e.g. 09:00). The timezone shown is your local timezone.
5. Save. Manage it from the agent's Scheduled tab.

5.6 Start an agent from a webhook

1. In Build, add a trigger block as the agent's input and connect it to your workflow. Save.
2. In Agents, open the agent → New agent task.
3. Enter the trigger name, description, and any required inputs or credentials; click Set up Trigger.
4. Copy the Webhook URL from the Trigger Status panel. Its shape is:

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

5. Configure the external service to POST to that URL, or send a test event:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"event":"test"}' \
  "https://<backend-host>/api/integrations/generic_webhook/webhooks/<webhook-id>/ingress"

Important

Trigger-based agents cannot be started manually — they only run when data reaches the webhook URL.

5.7 React to a GitHub pull request

1. Configure GitHub OAuth (GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET) on a self-hosted install, or use the hosted Platform.
2. Add the GitHub pull-request trigger block and select which events should fire it.
3. Connect its outputs (payload, sender, event, number, pull_request) to AI and notification blocks.
4. Set up the trigger from the library; the platform registers the webhook with GitHub using your credential.

5.8 Classic AutoGPT (legacy)

The original autonomous agent still runs from classic/ (Python 3.12+, Poetry). It is unsupported, has known dependency vulnerabilities, and is intended for educational use.

git clone https://github.com/Significant-Gravitas/AutoGPT.git
cd AutoGPT/classic
poetry install
cp .env.example .env

Set OPENAI_API_KEY in .env, then:

Agents listen on http://localhost:8000 by default. Each agent works inside a workspace (.autogpt/ in the current directory) with layered permissions:

# .autogpt/autogpt.yaml
allow:
  - read_file({workspace}/**)
  - write_to_file({workspace}/**)
  - web_search(*)
deny:
  - read_file(**.env)
  - execute_shell(sudo:*)

Permission check order (first match wins): agent deny → workspace deny → agent allow → workspace allow → prompt you (Once, Agent, Workspace, or Deny).

5.9 Move an agent between installations

1. Source: ⋯ → Export Agent to File.
2. Destination: Library → Import → AutoGPT agent → upload → complete metadata → Upload.
3. Reconnect credentials on the destination (exports never carry secrets).

5.10 Guard your model spend (self-hosted)

CHAT_DAILY_COST_LIMIT_MICRODOLLARS=5000000
CHAT_WEEKLY_COST_LIMIT_MICRODOLLARS=20000000

Once a window is exhausted, AutoPilot turns are refused with HTTP 429 until it resets. ChatGPT/Codex subscription turns and local servers (which report no cost) never count against a cap.

6. Advanced Usage

6.1 API Usage

AutoGPT exposes an External API mounted at /external-api, with interactive Swagger docs at https://backend.agpt.co/external-api/docs on the hosted Platform (and at the same path on your own backend).

Authenticate with an API key (create one under Settings → API Keys):

curl -H "X-API-Key: YOUR_API_KEY" \
  https://backend.agpt.co/external-api/v1/blocks

Or with an OAuth access token:

curl -H "Authorization: Bearer agpt_xt_..." \
  https://backend.agpt.co/external-api/v1/blocks

External API v1 endpoints

Run an agent and fetch results

curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"node_input": {"question": "How far is the Moon?"}}' \
  https://backend.agpt.co/external-api/v1/graphs/GRAPH_ID/execute/1

{"id":"GRAPH_EXEC_ID"}

The key requires the EXECUTE_GRAPH permission. Then poll (the result includes a status field):

curl -H "X-API-Key: YOUR_API_KEY" \
  https://backend.agpt.co/external-api/v1/graphs/GRAPH_ID/executions/GRAPH_EXEC_ID/results

Note

Request/response schemas are authoritative in the Swagger UI. Check it for the exact body of each endpoint before scripting against it.

OAuth scopes

"Sign in with AutoGPT" / OAuth for your app (PKCE required)

1. Redirect to:

https://platform.agpt.co/auth/authorize?client_id=CLIENT_ID&redirect_uri=https://yourapp.com/callback&scope=EXECUTE_GRAPH%20READ_GRAPH&state=RANDOM&code_challenge=CHALLENGE&code_challenge_method=S256&response_type=code

2. Exchange the code:

curl -X POST https://backend.agpt.co/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"authorization_code","code":"CODE","redirect_uri":"https://yourapp.com/callback","client_id":"CLIENT_ID","client_secret":"CLIENT_SECRET","code_verifier":"VERIFIER"}'

{"token_type":"Bearer","access_token":"agpt_xt_...","refresh_token":"agpt_rt_...","scopes":["EXECUTE_GRAPH","READ_GRAPH"], ...}

Refresh with "grant_type":"refresh_token" on the same endpoint; introspect with POST /api/oauth/introspect; revoke with POST /api/oauth/revoke.

Tip

On a self-hosted install, register an OAuth client with the backend CLI: poetry run oauth-tool generate-app --name "My App" --redirect-uris "https://app.example.com/callback" --scopes "EXECUTE_GRAPH,READ_GRAPH" (run from autogpt_platform/backend). See the CLI Reference.

Integration Setup Wizard — send users to connect third-party services before your app uses them:

https://platform.agpt.co/auth/integrations/setup-wizard?client_id=CLIENT_ID&providers=BASE64_JSON&redirect_uri=https://yourapp.com/callback&state=RANDOM

where providers is Base64 of, for example, [{"provider":"github","scopes":["repo","read:user"]},{"provider":"slack"}]. The callback receives success=true or success=false.

6.2 Plugins & Extensions: custom blocks

On a self-hosted install you extend AutoGPT by adding blocks — Python classes in autogpt_platform/backend/backend/blocks/. They are auto-discovered: every .py file in the tree is imported at startup except __init__.py and files starting with test_.

Minimal block:

import uuid
from backend.blocks._base import Block, BlockOutput, BlockSchemaInput, BlockSchemaOutput
from backend.data.model import SchemaField


class ShoutBlock(Block):
    class Input(BlockSchemaInput):
        text: str = SchemaField(description="Text to shout")

    class Output(BlockSchemaOutput):
        shouted: str = SchemaField(description="Upper-cased text")

    def __init__(self):
        super().__init__(
            id="REPLACE-WITH-A-REAL-uuid4",
            description="Upper-cases its input",
            input_schema=ShoutBlock.Input,
            output_schema=ShoutBlock.Output,
            test_input={"text": "hi"},
            test_output=("shouted", "HI"),
        )

    async def run(self, input_data: Input, **kwargs) -> BlockOutput:
        yield "shouted", input_data.text.upper()

Generate the ID once and paste it in:

python -c "print(__import__('uuid').uuid4())"

Test it:

cd autogpt_platform/backend
poetry run pytest 'backend/blocks/test/test_block.py::test_available_blocks[ShoutBlock]' -xvs

Important

Never invent a block id — generate a real UUID4. Block IDs are used across users for templates, and collisions break things.

For credentials, OAuth, webhooks, file handling, error classes, and the SDK ProviderBuilder, see the Admin Guide's Plugin / Extension System section.

6.3 Webhooks

AutoGPT uses webhooks in two directions:

Warning

For providers with no signing scheme, the webhook URL's UUID is the only secret. Treat the URL like a password and don't paste it into public places.

6.4 AutoPilot chat bots (Discord, Slack, Telegram, Teams)

AutoPilot can answer in chat platforms once an operator configures the bot:

As a user: mention the bot in a channel. If your chat account isn't linked, the bot sends a Link Account prompt; use /setup to link and /unlink to disconnect. In Teams, commands must @mention the bot (for example @AutoGPT /setup) and group chats are not supported.

7. How It Works

7.1 Core terms

7.2 Execution order

1. Execution starts at every starting node: Agent Input blocks and any executable block with no inbound links.
2. A downstream block is queued when its required inputs validate after upstream outputs and configured values are applied.
3. Execution continues until no more blocks can be queued; conditional branches and skipped nodes mean not every block runs.
4. Output blocks collect whatever results reach them.

A block runs only when all connected input pins have received data and all required input pins have a value (connected or hardcoded). Independent blocks may run in any order.

7.3 What happens when you click Start Task

Browser (Next.js :3000)
   │  REST  /api/graphs/{id}/execute/{version}
   ▼
REST server (:8006) ──► PostgreSQL (graph + execution rows)
   │  enqueue
   ▼
RabbitMQ ──► Executor (:8002) runs nodes, charges credits, resolves credentials
                 │ progress events (Redis)
                 ▼
          WebSocket server (:8001) ──► Browser (live beads + results)

Schedules come from the scheduler service, AutoPilot turns from the copilot executor, and emails/push from the notification service.

7.4 Where your data lives (self-hosted)

Integration credentials are encrypted with ENCRYPTION_KEY. Lose the key and stored credentials become unreadable.

8. Troubleshooting

Installation and startup

Error: ENCRYPTION_KEY is not set

Cause: backend/.env has no ENCRYPTION_KEY value (it is blank in .env.default by design). Solution: From autogpt_platform/, run make init-env, then docker compose up -d. Prevention: Always run make init-env before the first docker compose up.

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

Cause: Your install still uses the key that .env.default shipped up to release v0.7.4 — a publicly known value. Solution: Follow the key-rotation upgrade: stop the stack, export the old key as OLD_ENCRYPTION_KEY, blank ENCRYPTION_KEY= and UNSUBSCRIBE_SECRET_KEY= in backend/.env (and BETTER_AUTH_SECRET= in frontend/.env), run make init-env, then:

docker compose build migrate rest_server
docker compose run --rm migrate
docker compose run --rm --no-deps -e OLD_ENCRYPTION_KEY rest_server cli rotate-encryption-key
docker compose run --rm --no-deps -e OLD_ENCRYPTION_KEY rest_server cli rotate-encryption-key --apply

Prevention: Never copy secrets from .env.default.

Error: the specified Containerfile or Dockerfile does not exist, ..\..\autogpt_platform\backend\Dockerfile

Cause: You are using Podman / podman-compose. Solution: Install Docker Desktop (or Docker Engine) and use docker compose. Prevention: Podman is not supported.

Error: db container is unhealthy on Windows

Cause: Docker Desktop is using Hyper-V. Solution: Enable Use the WSL 2 based engine in Docker Desktop → Settings → General, restart Docker. Prevention: Choose WSL 2 when installing Docker on Windows.

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

Cause: Backend and frontend are on different machines and the JWKS URL uses http://. Solution: Put the frontend behind TLS and set JWT_JWKS_URL=https://<frontend>/api/auth/jwks. On a genuinely trusted network you may set JWKS_ALLOW_INSECURE_TRANSPORT=true (a startup warning is logged). Prevention: Keep backend and frontend on one Docker network, or use HTTPS.

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

Cause: JWT_JWKS_URL is empty. Solution: Set it in backend/.env, e.g. JWT_JWKS_URL=http://localhost:3000/api/auth/jwks for a local run.

Error: Invalid JWT_JWKS_URL: '...'. Must be an http:// or https:// URL.

Cause: Malformed URL. Solution: Use a full http:// or https:// URL ending in /api/auth/jwks.

Error: Invalid JWT_JWKS_ALGORITHMS entry: '...'. JWKS verification only supports asymmetric algorithms.

Cause: A symmetric algorithm such as HS256 was listed. Solution: Use the default ES256,RS256,EdDSA or a subset of asymmetric algorithms.

Nobody can reach the backend after changing BETTER_AUTH_SECRET

Cause: The frontend's stored token-signing key was encrypted under the old secret. Solution:

docker compose up -d --wait db
docker compose exec db psql -U postgres -c 'DELETE FROM platform."UserAuthJwks";'
docker compose up -d --build

A new key is created on the next sign-in; everyone signs in once.

Integrations show as disconnected / revoked after an upgrade

Cause: The stack started on a new ENCRYPTION_KEY before stored credentials were re-encrypted. Solution: Stop the stack and run cli rotate-encryption-key --apply with OLD_ENCRYPTION_KEY. Untouched credentials are recovered; ones a user replaced in between stay revoked and must be reconnected.

Old Supabase database fails to start after moving the data directory

Symptoms: restart loop with could not open configuration file, could not access file "$libdir/…", unrecognized configuration parameter, extension "…" is not available, data directory … has wrong ownership, or Permission denied. Cause: The plain pgvector/pgvector:pg15 image lacks Supabase extensions/roles, or file ownership is wrong. Solution: rm -rf data/db/data and use the dump-and-restore fallback (pg_dump --no-owner --no-privileges from supabase/postgres:15.8.1.049, then pg_restore into the new db, after DROP SCHEMA IF EXISTS auth CASCADE;). Prevention: Back up autogpt_platform/db/docker/volumes/db/data before upgrading.

Upgraded Supabase install shows zero users

Cause: pg_restore failed on auth.users, or the fresh auth.users shim collided with the restore. Solution: Check select count(*) from auth.users. If 0, drop the auth schema and restore again before running docker compose run --rm migrate.

prisma generate targets the global Python instead of the virtualenv

Solution: pip uninstall prisma, then poetry run prisma generate again.

Single-container appliance

The browser cannot connect after docker run --rm "${IMAGE}"

Cause: A bare run publishes no port. Solution: Use the full Quick start command with --publish 127.0.0.1:3000:3000.

Port 3300 opens but sign-in and other auth actions fail

Cause: AUTOGPT_PUBLIC_URL doesn't match the browser origin. Solution: Use --publish 127.0.0.1:3300:3000 and AUTOGPT_PUBLIC_URL=http://localhost:3300, then replace the container.

Signup shows Email Not Allowed

Cause: Registration is closed or your address isn't on the allowlist. Solution: Set AUTH_ALLOW_NEW_ACCOUNTS=true and an exact AUTH_SIGNUP_ALLOWLIST=[email removed], replace the container, sign up, then close signup again.

Container stays starting or becomes unhealthy

Solution: First boot can take several minutes. Run docker exec autogpt autogpt-healthcheck and read docker logs --tail 100 autogpt for the first failed service.

Container is OOM-killed or restarts repeatedly during startup

Cause: The appliance uses about 5–6 GiB before workload headroom. Solution: Raise Docker Desktop's VM memory (Settings → Resources) or host memory.

Startup refuses to continue after an interrupted migration

Solution: Empty new install — stop, remove the container and its unused volume, start over. Existing install — restore the pre-upgrade backup. Only use prisma migrate resolve after confirming what the migration changed.

Error: DB_CONNECTION_LIMIT / DB_CONNECT_TIMEOUT / DB_POOL_TIMEOUT rejected

Solution: Use integers in range: 1–5, 1–600, 1–3600 respectively.

Startup rejects legacy JWT secrets

Solution: For a fresh install remove JWT_VERIFY_KEY and SUPABASE_JWT_SECRET. Only for an intentional legacy migration set AUTOGPT_ENABLE_LEGACY_AUTH=true and both secrets to the same value of at least 32 characters.

Error: AUTOGPT_PUBLIC_URL must use http or https

Also: 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: Use a bare origin like https://agents.example.com or http://localhost:3300.

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

Cause: You supplied a different value for a secret generated on first boot and stored in /data/config/runtime.env. Solution: Remove the override (or restore the original). There is no in-place rotation of generated appliance secrets.

Error: RABBITMQ_DEFAULT_USER may not use the built-in guest account

Solution: Choose a different RabbitMQ username (and avoid unsupported characters).

Error: VAPID_PRIVATE_KEY and VAPID_PUBLIC_KEY must be set together

Solution: Set both or neither. The private key must decode to exactly 32 bytes; the public key must be an uncompressed P-256 key.

Error: ENCRYPTION_KEY must be a Fernet-compatible key

Solution: Generate one with poetry run cli gen-encrypt-key or from cryptography.fernet import Fernet; Fernet.generate_key().decode().

A run stays RUNNING after a restart

Cause: The container stopped mid-run; the queue message was dropped and the row not reconciled. Solution: Start a new run. In-flight runs never resume.

Requests stall for minutes under concurrent runs

Cause: Prisma connection-pool exhaustion (max 5 per backend role in the appliance). Solution: Reduce concurrency or move to a distributed deployment. Lowering DB_POOL_TIMEOUT only fails faster.

Data appears missing after replacing the container

Cause: The new container uses a different or anonymous /data volume. Solution: Inspect the mount and reattach the original named volume:

docker inspect --format '{{range .Mounts}}{{if eq .Destination "/data"}}{{.Name}}{{end}}{{end}}' autogpt

The container exits after a persistent health failure

Cause: The watchdog allows 600 s for initial health, then stops the container on purpose. Solution: Keep --restart unless-stopped so Docker retries; fix the failing service shown in the logs.

AutoPilot and models

AutoPilot returns a provider 401

Solution: Configure the key for the selected transport — the default remote route needs OPEN_ROUTER_API_KEY; full remote memory also needs OPENAI_API_KEY.

AutoPilot returns HTTP 429

Cause: Daily or weekly spend cap reached. Solution: Wait for reset (midnight UTC daily, Monday 00:00 UTC weekly) or raise CHAT_DAILY_COST_LIMIT_MICRODOLLARS / CHAT_WEEKLY_COST_LIMIT_MICRODOLLARS.

Local chat works but memory ingestion fails

Solution: Install the embedding model and confirm its /v1/embeddings endpoint works. If your server lacks the default slugs, set GRAPHITI_LLM_MODEL, GRAPHITI_RERANKER_MODEL, and GRAPHITI_EMBEDDER_MODEL.

Ollama cannot be reached from AutoGPT

Solution: On Docker Engine add --add-host host.docker.internal:host-gateway; make Ollama listen on an address Docker can reach; test with:

docker exec autogpt curl --fail --show-error http://host.docker.internal:11434/api/tags

AutoPilot answers are cut off or ignore instructions with a local model

Cause: Ollama's default context is too small for the ~8k-token system prompt. Solution: Set OLLAMA_CONTEXT_LENGTH=32768 on the Ollama server and restart it.

AI blocks fail with a missing-credential error

Solution: Add the provider key to backend/.env (self-hosted) and restart, or connect the credential from the block.

Agents, schedules and triggers

A trigger-based agent has no Start Task option

Cause: Trigger agents cannot be started manually. Solution: Use New agent task → Set up Trigger, then send data to the webhook URL.

I can't edit a Marketplace agent

Cause: Marketplace agents are read-only. Solution: Open it in the builder and click Duplicate.

A block shows a broken image in the Blocks menu

Cause: The provider's icon PNG is missing from frontend/public/integrations/{provider_name}.png. Solution: Add the icon (developers) — it doesn't affect execution.

Scheduled task failed with insufficient balance

Solution: Add credits or enable auto-refill under Settings → Billing → Automation Credits.

A schedule keeps firing after its workflow was removed from an expert

Cause: Known open issue (#14607): nothing at execution time checks expert-workflow membership. Solution: Delete the schedule from the agent's Scheduled tab.

Error: Invalid cron expression format.

Solution: Use the schedule form's controls rather than a hand-typed cron string; check each field.

Error: Authentication error — please sign in again.

Cause: Your session expired during an upload. Solution: Sign in again and retry.

Removing a credential broke an agent

Solution: Reconnect a compatible credential in the block or task, or restore it in Settings → Integrations.

Template ignores my latest agent changes

Cause: Templates are pinned to the graph version they were created from. Solution: Create a new template from a task run on the current version.

Chat bots

/setup fails with an httpx.ConnectError (local Docker)

Cause: platform_linking_manager isn't running. Solution: docker compose up -d platform_linking_manager or docker compose --profile bot up -d.

The Telegram bot ignores @mentions in groups

Solution: Disable group privacy mode via BotFather /setprivacy.

The Teams bot ignores /setup in a channel

Solution: @mention it: @AutoGPT /setup. Group chats are not supported at all.

API and OAuth

OAuth error invalid_client

Solution: Verify the client ID and that the app is active.

OAuth error invalid_redirect_uri

Solution: Register the exact redirect URI with the platform admin.

OAuth error invalid_scope

Solution: Request only scopes allowed for your app.

OAuth error invalid_grant

Cause: Code expired (10 minutes) or already used. Solution: Restart the authorization flow.

API returns 401 / 403

Solution: 401 = invalid or expired token/key (refresh or regenerate); 403 = missing scope.

Classic AutoGPT

Error: --continuous-limit can only be used with --continuous

Solution: Add -c, e.g. poetry run autogpt run -c -l 5.

Error: OpenAI is unavailable: invalid API key

Also ... can't load credentials, and the same for Anthropic and Groq. Solution: Set a valid OPENAI_API_KEY (or ANTHROPIC_API_KEY / GROQ_API_KEY) in classic/.env.

Error: The agent failed to output valid thoughts N times in a row.

Cause: The model repeatedly returned unparseable output. Solution: Use a stronger SMART_LLM, simplify the task, or check provider errors in the logs.

Error: Access to internal/private addresses is restricted

Cause: Forge's URL validator blocks private/internal addresses (also: Access to local files is restricted, URL is too long, Invalid URL format: URL must start with http:// or https://). Solution: Use a public http(s) URL.

9. FAQ

Q: What is the difference between the AutoGPT Platform and AutoGPT Classic?

The Platform (autogpt_platform/) is the current product: a web app for building and running block-based agents. Classic (classic/) is the original 2023 autonomous agent; it is unsupported and kept for education.

Q: Is self-hosting free?

Yes. There is no license fee; you pay for your infrastructure and model providers. The hosted Platform is a paid service with usage-based runs.

Q: What license does AutoGPT use?

autogpt_platform/ is under the Polyform Shield license (free for personal and internal business use; you may not sell it as a competing hosted service). classic/ and everything else is MIT.

Q: Do I need an API key to try it?

Not on the hosted Platform. Self-hosted, you can boot, sign up, build, and run provider-free blocks (like Calculator) without keys; AI blocks and AutoPilot need a provider.

Q: Which model providers are supported?

OpenAI, Anthropic, Groq, Llama API, AI/ML API, OpenRouter, NVIDIA, and local OpenAI-compatible servers (Ollama, vLLM, LocalAI, LM Studio, LiteLLM) for AutoPilot. The exact model list ships in backend/data/llm_registry/catalog.py.

Q: Can I run everything offline with a local LLM?

The from-source setup supports a fully offline install with a local LLM. Set CHAT_USE_LOCAL=true and point CHAT_BASE_URL at your server.

Q: Which ports does the Compose stack use?

UI 3000, REST 8006, WebSocket 8001, plus internal services (see Default ports).

Q: Which port does the single container use?

Only 3000 inside the container. Publish it to loopback (127.0.0.1:3000:3000) and put a TLS reverse proxy in front for remote access.

Q: Can I change the host port of the appliance?

Yes: --publish 127.0.0.1:3300:3000 plus AUTOGPT_PUBLIC_URL=http://localhost:3300.

Q: Does the appliance support Windows?

Windows users should use the manual (from-source) guide for now.

Q: Is Podman supported?

No. Use Docker.

Q: How much memory does the appliance need?

More than the measured 5–6 GiB, plus headroom for agents, local models, and growth. There is no measured minimum CPU count.

Q: How do I become an administrator on the appliance?

Sign up, then run docker exec autogpt autogpt-admin promote [email removed], and sign out and back in.

Q: How do I stop strangers from creating accounts?

Set AUTH_SIGNUP_ALLOWLIST to exact emails during bootstrap, then AUTH_ALLOW_NEW_ACCOUNTS=false.

Q: Can I allow a whole email domain?

Yes, with an entry starting with @ (e.g. @example.com). Only use domains you fully control — never public domains like @gmail.com.

Q: Is email verification supported?

Not in the appliance; enabling AUTH_REQUIRE_EMAIL_VERIFICATION stops startup. Keep it false.

Q: How do I reset a forgotten password?

Only through Postmark-powered password reset. Without Postmark, create a replacement administrator using the add-administrator procedure; the old password cannot be reset.

Q: Why are my social-login buttons missing on the appliance?

The bundled local-mode frontend doesn't render them, even if AUTH_*_CLIENT_ID/SECRET are set.

Q: What does make init-env actually generate?

ENCRYPTION_KEY, UNSUBSCRIBE_SECRET_KEY, and BETTER_AUTH_SECRET (plus any other secret listed in SECRET_GENERATORS), only where the line exists and is empty.

Q: Can I re-run make init-env?

Yes; it never overwrites existing files or values.

Q: What happens if I lose ENCRYPTION_KEY?

Stored integration credentials become unreadable and must be reconnected.

Q: How do I rotate ENCRYPTION_KEY?

Set the new key, export the old one as OLD_ENCRYPTION_KEY, run cli rotate-encryption-key (dry run), then with --apply.

Q: What is a block?

A single action with typed input and output pins — AI call, API call, data transform, or integration.

Q: How many blocks are there?

Hundreds, across 45+ connected platforms.

Q: What's the difference between an input block and a trigger block?

An input block collects values when you start a task manually; a trigger block starts the agent when a webhook event arrives.

Q: Does a failed block stop my agent?

No. It emits on its error pin; blocks that needed its normal output don't run.

Q: In what order do blocks run?

Whenever their required inputs are satisfied; independent blocks may run in any order.

Q: Can I use an agent inside another agent?

Yes — saved agents appear as blocks in the Blocks menu.

Q: How do I save in the builder?

Ctrl+S / Cmd+S or the Save button. Each save is a new version.

Q: Will I lose work if my browser crashes mid-edit?

The builder keeps a local recovery draft until the next successful save.

Q: How do I run an agent on a schedule?

New agent task → Schedule Task, then set name, repeat, days, and time.

Q: What timezone do schedules use?

Your local timezone, shown on the schedule form.

Q: Why can't I start my trigger agent manually?

By design; trigger agents run only from webhook events.

Q: How do I share a result publicly?

Share results → Enable Sharing, then copy the Share URL. Stop Sharing revokes it.

Q: Does sharing expose my inputs?

No, only outputs — which may still be sensitive.

Q: How do I move an agent to another account or server?

Export Agent to File then Import on the other side; reconnect credentials.

Q: Do exports include my API keys?

No. Templates and exports store credential references, never secrets.

Q: Can I edit a Marketplace agent?

Duplicate it first; your fork is editable and independent.

Q: How do I publish to the Marketplace?

From the builder (Publish to Marketplace) or Settings → Creator Dashboard → Publish Agent; fill title, subheader, slug, images, optional video and output demo, category, description, instructions, recommended schedule; click Submit for review. The AutoGPT team reviews it.

Q: How are hosted runs billed?

In automation credits when blocks run; some blocks are fixed-price, others usage-based and reconciled after running.

Q: Where do I see what a run cost?

In the task detail header (Cost) and under Settings → Billing → Automation Credits.

Q: Can my balance go negative?

Yes, if reconciliation for a usage-based block that already ran exceeds the balance.

Q: Do self-hosted installs use credits?

With BEHAVE_AS=local (the appliance default) entitlement gating is bypassed; you pay providers directly.

Q: How do I call AutoGPT from my own code?

Use the External API at /external-api/v1/... with an X-API-Key header or an OAuth bearer token.

Q: Where is the full API reference?

The Swagger UI at /external-api/docs on the backend (hosted: https://backend.agpt.co/external-api/docs).

Q: Is PKCE optional for OAuth?

No, PKCE with S256 is required for every authorization request.

Q: How long do OAuth tokens last?

Access 1 hour, refresh 30 days, authorization code 10 minutes.

Q: Can I use AutoGPT as a "Sign in with" provider?

Yes, request the IDENTITY scope and call GET /external-api/v1/me.

Q: Can AutoPilot talk to me in Slack or Discord?

Yes, once an operator configures the bot; link your account with /setup.

Q: Does AutoPilot remember things between chats?

Memory uses Graphiti on FalkorDB and requires a working model profile (and embeddings).

Q: Are uploaded files virus-scanned?

The Compose stack runs ClamAV. The single-container appliance bundles no antivirus — treat uploads as trusted input there.

Q: How do I back up the appliance?

Use the documented cold-backup block, which stops the container, tars /data (excluding ./cache), and writes a SHA-256 checksum. There is no supported hot backup.

Q: What happens to runs when I stop the container?

In-flight runs are abandoned and do not resume; start new runs after restart.

Q: Can I downgrade the appliance?

Only by running the prior image against its matching pre-upgrade backup restored into a new volume. Never run an older image on a volume migrated by a newer one.

Q: Can I turn the appliance into a multi-tenant hosted service?

No. The bundled frontend is compiled in local mode; BEHAVE_AS=cloud alone is not a complete hosted switch.

Q: Is Classic AutoGPT still maintained?

No. It's unsupported, has known dependency vulnerabilities, and will not be updated.

Q: What Python version does Classic need?

Python 3.12+ with Poetry.

Q: Where does a Classic agent keep its files?

In .autogpt/agents/AutoGPT-{agent_id}/ inside the workspace, with file access sandboxed to its workspace/ subdirectory.

Q: Where do I get help?

Discord (discord.gg/autogpt), docs at docs.agpt.co, and GitHub Issues.

10. Reference

10.1 CLI Reference

Make targets (autogpt_platform/)

Caution

make reset-db deletes data/db/data — all accounts, agents, and run history.

Backend Poetry scripts (autogpt_platform/backend)

poetry run cli — backend admin CLI

In Docker, prefix with docker compose run --rm rest_server, e.g. docker compose run --rm --no-deps rest_server cli gen-encrypt-key.

poetry run oauth-tool

Single-container appliance commands

Classic: poetry run autogpt (from classic/)

Classic: poetry run direct-benchmark

10.2 Configuration Quick Reference

The complete reference — every variable, service, and default — is in the Admin Guide.