# 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](#58-classic-autogpt-legacy) for completeness.

| Surface | What it is | Where |
|---|---|---|
| **AutoPilot** | Conversational assistant that builds agents, runs agents, and runs blocks directly | `/copilot` |
| **Agents** (Library) | Your agents, their tasks (runs), schedules, triggers, templates, and costs | `/library` |
| **Marketplace** | Community and team-published agents you can add with one click | `/marketplace` |
| **Build** | Visual canvas where you connect blocks into an agent graph | `/build` |

---

## 1. Quick Start

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

| | **Hosted AutoGPT Platform** | **Self-hosted** |
|---|---|---|
| Access | Public signup at `platform.agpt.co` | Run it on your own machine or server |
| Cost | Paid plan plus agent usage | No license fee; you pay your own infrastructure and model providers |
| Setup | None | Docker and configuration |
| Model access | Built in | Bring your own API keys |
| Updates | Managed by AutoGPT | Managed by you |
| Support | Plan-dependent | Community |

### 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.

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

```text
[+] 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.

```text
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

| Method | Status | Platforms | Best for |
|---|---|---|---|
| **From source (Docker Compose)** | Supported, recommended today | Linux, macOS, Windows | Most self-hosters; offline installs with local LLMs |
| **Single-container appliance** (`significantgravitas/autogpt`) | Experimental | Linux/macOS hosts running Linux containers on `amd64`/`arm64` | One-container, loopback-bound single-tenant installs |
| **Release installer script** | Not yet live | Linux, macOS | Future one-command appliance install |
| **Local development** (Poetry + pnpm) | Supported | Any | Contributors and block developers |

> [!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

| Requirement | From source (Compose) | Single-container appliance |
|---|---|---|
| Docker | Docker Desktop or Docker Engine | Docker Engine or Desktop running Linux containers (`linux/amd64` or `linux/arm64`) |
| Docker Compose | Required (`docker compose`) | Not required |
| Git | Required | Not required |
| Node.js + npm | Required by the checkout workflow | Not required |
| Memory | Enough for Postgres, Redis cluster, RabbitMQ, FalkorDB, ClamAV and app services | More than the measured **5–6 GiB**, plus headroom |
| Disk | Image layers + `autogpt_platform/data/` | Image + growing `/data` volume + room for one full compressed backup |
| Shell tools | — | Bash, curl, and `sha256sum` or `shasum` (for the Unix bootstrap) |

> [!CAUTION]
> **Podman and podman-compose are not supported.** They cause path-resolution failures, particularly on Windows (see [Troubleshooting](#error-the-specified-containerfile-or-dockerfile-does-not-exist)).

Verify your tools:

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

```text
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"

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

    ```text
    ✔ 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):

    ```bash
    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:

    ```bash
    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**

| Step | Effect |
|---|---|
| `cp -n .env.default .env` (root, `backend/`, `frontend/`) | Creates missing `.env` files; never overwrites an existing one |
| `runtime_config.py fill-env --missing-ok` on each file | Fills every secret whose line is present but empty |
| Safe to re-run | Existing files and existing values are never overwritten |

> [!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)**

| Port | Service |
|---|---|
| `3000` | Frontend (Next.js UI and embedded auth service) |
| `8006` | REST API server (`rest_server`) |
| `8001` | WebSocket server (`websocket_server`) |
| `8002` | Graph executor |
| `8003` | Scheduler |
| `8005` | Database manager |
| `8007` | Notification server |
| `8008` | AutoPilot (copilot) executor |
| `8009` | Platform linking manager (bot profile only) |
| `5432` | PostgreSQL (`pgvector/pgvector:pg15`) |
| `5672` | RabbitMQ |
| `17000`–`17002` | Redis cluster nodes |
| `6380` / `3001` | FalkorDB (Redis protocol / web UI) |
| `3310` | ClamAV virus scanner |

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

```bash
curl http://localhost:8006/health
```

```text
{"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.**

| Tag | Meaning |
|---|---|
| `latest` | Newest fully verified stable Platform release |
| `vX.Y.Z` | Immutable image for GitHub release `autogpt-platform-beta-vX.Y.Z` |
| `sha-<git-sha>` | Immutable image for an exact `dev` or release revision |
| `canary-sha-*` | Legacy pre-release artifacts — not supported |

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

Or build from source (from the repository root):

```bash
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.**

```bash
umask 077
touch autogpt.env
chmod 600 autogpt.env
```

Add at least:

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

**Step 3 — Start the appliance.**

```bash
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}"
```

| Flag | Why |
|---|---|
| `--restart unless-stopped` | Lets Docker recover the container after the internal watchdog stops it |
| `--shm-size 2g` | Keeps temporary ChatGPT/Codex auth homes in memory |
| `--ulimit nofile=65536:65536` | Predictable file-descriptor ceiling for bundled services |
| `--log-opt max-size=50m --log-opt max-file=5` | Caps logs at about five 50 MB files |
| `--publish 127.0.0.1:3000:3000` | Loopback-only exposure — this is the exposure control |
| `--volume autogpt-data:/data` | Named volume holding all durable state |

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

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

```text
starting
```

Repeat until it reports:

```text
healthy
```

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

```bash
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`:

```dotenv
AUTH_ALLOW_NEW_ACCOUNTS=false
```

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

```bash
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.

    ```bash
    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.

    ```bash
    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](#13-your-first-agent-no-api-key-needed) 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

| File | Used by | Created from |
|---|---|---|
| `autogpt_platform/.env` | Compose-level settings (Postgres host/port/password) | `.env.default` |
| `autogpt_platform/backend/.env` | Backend services (DB, Redis, RabbitMQ, secrets, provider keys, OAuth apps) | `backend/.env.default` |
| `autogpt_platform/frontend/.env` | Next.js UI and embedded Better Auth service | `frontend/.env.default` |
| `autogpt.env` (appliance) | Every setting for the single-container image | You create it (optionally from `single-container/.env.example`) |

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**

| Variable | Purpose |
|---|---|
| `OPENAI_API_KEY` | OpenAI models; also OpenAI embeddings for memory |
| `ANTHROPIC_API_KEY` | Anthropic models; also routes AutoPilot directly to Anthropic |
| `GROQ_API_KEY` | Groq models |
| `LLAMA_API_KEY` | Llama API models |
| `AIML_API_KEY` | AI/ML API (300+ models) |
| `OPEN_ROUTER_API_KEY` | OpenRouter (default remote AutoPilot route) |
| `NVIDIA_API_KEY` | NVIDIA models |
| `V0_API_KEY` | v0 blocks |

After adding keys to a Compose install, restart:

```bash
docker compose down && docker compose up -d
```

**AutoPilot model routing**

| Profile | Settings |
|---|---|
| OpenRouter + OpenAI embeddings (default remote) | `CHAT_USE_LOCAL=false`, `CHAT_USE_OPENROUTER=true`, `OPEN_ROUTER_API_KEY`, `OPENAI_API_KEY` |
| Anthropic chat + remote memory | `CHAT_USE_LOCAL=false`, `CHAT_USE_OPENROUTER=false`, `ANTHROPIC_API_KEY`, `OPEN_ROUTER_API_KEY`, `OPENAI_API_KEY` |
| Ollama / local OpenAI-compatible server | `CHAT_USE_LOCAL=true`, `CHAT_BASE_URL=http://host.docker.internal:11434/v1`, `CHAT_API_KEY=ollama`, `CHAT_FAST_STANDARD_MODEL=<model>` |

> [!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:
>
> ```bash
> 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**

| Variable | Where | Purpose |
|---|---|---|
| `AUTOGPT_PUBLIC_URL` | appliance | Exact browser origin, including scheme and non-default port |
| `AUTH_SIGNUP_ALLOWLIST` | appliance / frontend | Comma-separated exact emails or `@domain` entries allowed to sign up |
| `AUTH_ALLOW_NEW_ACCOUNTS` | appliance / frontend | `false` blocks all new accounts |
| `AUTH_REQUIRE_EMAIL_VERIFICATION` | frontend | Keep `false` (the appliance refuses to start if enabled) |
| `FRONTEND_BASE_URL` | backend | Frontend URL used in links and OAuth callbacks (default `http://localhost:3000`) |
| `PLATFORM_BASE_URL` | backend | Backend URL for webhooks and OAuth (default `http://localhost:8006`) |

**Email (optional, for password reset)**

```dotenv
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)**

```dotenv
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:

```text
<your_frontend_url>/auth/integrations/oauth_callback
```

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

| Provider | Variables |
|---|---|
| GitHub | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` |
| Google (Gmail, Sheets, Calendar, ...) | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` |
| Notion | `NOTION_CLIENT_ID`, `NOTION_CLIENT_SECRET` |
| Twitter / X (OAuth 2.0 + PKCE) | `TWITTER_CLIENT_ID`, `TWITTER_CLIENT_SECRET` |
| Linear | `LINEAR_CLIENT_ID`, `LINEAR_CLIENT_SECRET` |
| Todoist | `TODOIST_CLIENT_ID`, `TODOIST_CLIENT_SECRET` |
| Discord | `DISCORD_CLIENT_ID`, `DISCORD_CLIENT_SECRET` |
| Reddit | `REDDIT_CLIENT_ID`, `REDDIT_CLIENT_SECRET` |

> [!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

| Area | What you do there |
|---|---|
| **Home / New Task** | Entry points to AutoPilot |
| **AutoPilot** (`/copilot`) | Chat to build, edit, and run agents or run blocks directly |
| **Agents** (`/library`) | Run agents, view tasks, schedules, triggers, templates, costs |
| **Marketplace** (`/marketplace`) | Find, add, download, and publish agents |
| **Build** (`/build`) | Visual canvas for agent graphs |
| **Settings** | Integrations, API keys, Billing, Creator Dashboard, account |

### 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**

| Type | Role |
|---|---|
| **Input blocks** | Define what the agent asks for when it runs; they become the run form fields |
| **Action blocks** | Do the work — AI text/image generation, API calls, data processing, hundreds of integrations |
| **Output blocks** | Define what the agent returns; they become the visible result |
| **Trigger blocks** | Special input blocks that start the agent from an external webhook event |

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**

| Type | Carries |
|---|---|
| Text | Strings |
| Number | Numeric values |
| File | Uploads and downloads |
| List | Arrays |
| Boolean | True/false |
| Object | Structured data |

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

| Where | What you see |
|---|---|
| Left pane of the agent page | History of every task (run) |
| Task detail | **Inputs**, **Outputs**, and **Cost** (in dollars) |
| Agent tabs | `Tasks`, `Scheduled`, `Triggers`, `Templates` with counts |

### 4.6 Manage your library

| Action | How |
|---|---|
| Favorite | Click the heart icon; view under the **Favorites** tab |
| Folders | Create a folder, then **Move to folder** from an agent's menu |
| Edit | Agent page → **⋯** → **Edit Agent** |
| Delete | Agent page → **⋯** → **Delete Agent** (permanent) |
| Export | Agent page → **⋯** → **Export Agent to File** |
| Import | Library → **Import** → **AutoGPT agent** tab → upload the `.json` |

> [!CAUTION]
> Deleting an agent is permanent and cannot be undone.

### 4.7 Use AutoPilot

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

| Capability | Example request |
|---|---|
| Run agents | "Run my SEO agent for the keyword *espresso grinders*." |
| Build agents | "Build an agent that takes a topic, researches it, and emails me a summary." |
| Edit agents | "Add a step that translates the output to Spanish." (user-created or duplicated agents only) |
| Browse the Marketplace | "Find an agent that summarizes YouTube videos." |
| Run blocks directly | Research with Perplexity, generate or edit images, generate video, run models on Replicate, make custom HTTP requests, write and execute code |
| Manage the library | View task results, set up schedules |

AutoPilot requests missing inputs or credentials before running anything.

| | AutoPilot | Agent Builder |
|---|---|---|
| Audience | Everyone | Users comfortable with visual programming |
| How | Describe what you want | Drag, drop, connect |
| Builds agents | Yes | Yes (manually) |
| Edits agents | User-created or duplicated editable agents | Full visual editing |
| Block access | Runs supported blocks without an agent | Blocks must be wired into an agent |

> [!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.

| Step | Action |
|---|---|
| Create | Task **⋯** → **Save as Template** → name + description → **Save** |
| Use | **Templates** tab → pick template → review → **Start task from template** |

> [!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.

| Credential type | How you connect | Examples |
|---|---|---|
| OAuth | Authorize on the service's login page | Google, GitHub, Twitter |
| API key | Paste the key from the service dashboard | Linear, OpenAI |
| Username & password | Enter account credentials | Varies |

**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)

| Concept | Behavior |
|---|---|
| When charged | When blocks run |
| Pricing | Fixed or usage-based (tokens, provider cost, time, data size, item count) |
| Estimates | Usage-based blocks may be estimated before execution and reconciled after |
| Balance | Automation-credits wallet in the navigation, and **Settings → Billing → Automation Credits** |
| Out of credits | Paid blocks cannot start; scheduled tasks may fail; reconciliation can leave a negative balance |
| Top-up | **Settings → Billing → Automation Credits → Add credits**, or configure auto-refill |

> [!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**.

| Choice | Wiring |
|---|---|
| Surface the error | Connect the error pin to an Output block |
| Recover | Connect the error pin to fallback blocks (retry with other settings, default value, alternate path) |
| Ignore | Leave it unconnected; downstream blocks that needed the failed output simply don't run |

> [!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:

```text
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:

```bash
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.

| | Schedule | Trigger |
|---|---|---|
| Starts | At configured times | When an external event hits the webhook |
| Inputs | Fixed when you create the schedule | From the webhook payload |
| Setup | **New agent task → Schedule Task** | Trigger block in Build, then **New agent task → Set up Trigger** |

### 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.

```bash
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:

| Goal | Command |
|---|---|
| Run the interactive agent CLI | `poetry run autogpt` |
| Serve the Agent Protocol server | `poetry run serve --debug` |
| Run the Forge agent | `poetry run python -m forge` |
| Run benchmarks | `poetry run direct-benchmark run` |

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

```yaml
# .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)

```dotenv
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**):

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

**Or with an OAuth access token:**

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

**External API v1 endpoints**

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/external-api/v1/me` | Current user (id, name, email, timezone) |
| `GET` | `/external-api/v1/blocks` | List blocks |
| `POST` | `/external-api/v1/blocks/{block_id}/execute` | Run a single block |
| `POST` | `/external-api/v1/graphs` | Create an agent graph |
| `POST` | `/external-api/v1/graphs/{graph_id}/execute/{graph_version}` | Run an agent |
| `GET` | `/external-api/v1/graphs/{graph_id}/executions/{graph_exec_id}/results` | Read run results |
| `GET` | `/external-api/v1/store/agents` | Browse store agents |
| `GET` | `/external-api/v1/store/agents/{username}/{agent_name}` | Store agent detail |
| `GET` | `/external-api/v1/store/creators` | Browse creators |
| `GET` | `/external-api/v1/store/creators/{username}` | Creator detail |

**Run an agent and fetch results**

```bash
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
```

```text
{"id":"GRAPH_EXEC_ID"}
```

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

```bash
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**

| Scope | Grants |
|---|---|
| `IDENTITY` | Read user ID, e-mail, timezone |
| `EXECUTE_GRAPH` | Run agents |
| `READ_GRAPH` | Read agent run results |
| `WRITE_GRAPH` | Create and update agent graphs |
| `EXECUTE_BLOCK` | Run individual blocks |
| `READ_BLOCK` | Read block definitions |
| `READ_STORE` | Access the agent store |
| `WRITE_LIBRARY` | Add agents to your library |
| `USE_TOOLS` | Use platform tools |
| `MANAGE_INTEGRATIONS` | Create and update user integrations |
| `READ_INTEGRATIONS` | Read integration status |
| `DELETE_INTEGRATIONS` | Remove user integrations |

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

1. Redirect to:

```text
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:

```bash
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"}'
```

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

| Token | Lifetime |
|---|---|
| Access token (`agpt_xt_...`) | 1 hour |
| Refresh token (`agpt_rt_...`) | 30 days |
| Authorization code | 10 minutes |

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](#101-cli-reference).

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

```text
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:

```python
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:

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

Test it:

```bash
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:

| Direction | What | Where to configure |
|---|---|---|
| **Inbound** (events start agents) | Generic webhook triggers and provider triggers (GitHub, Slant3D, ...) | Trigger blocks in Build + **Set up Trigger** in the library |
| **Inbound** (chat bots) | Slack, Telegram, Microsoft Teams AutoPilot bots | `AUTOPILOT_BOT_*` env vars (see Admin Guide) |

> [!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:

| Platform | Required variables |
|---|---|
| Discord | `AUTOPILOT_BOT_DISCORD_TOKEN` |
| Slack | `AUTOPILOT_BOT_SLACK_TOKEN` + `AUTOPILOT_BOT_SLACK_SIGNING_SECRET` |
| Telegram | `AUTOPILOT_BOT_TELEGRAM_TOKEN` + `AUTOPILOT_BOT_TELEGRAM_WEBHOOK_SECRET` (and register the webhook with Telegram) |
| Microsoft Teams | `MICROSOFT_CLIENT_ID` + `MICROSOFT_CLIENT_SECRET` + `MICROSOFT_TENANT_ID` |

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

| Term | Meaning |
|---|---|
| **Agent** / **graph** | A saved workflow of connected blocks, stored as JSON with version history |
| **Block** | One action (AI call, API call, data transform, integration) |
| **Node** | A block placed in a specific graph |
| **Pin** | A typed input or output on a block |
| **Task** / **execution** | One run of an agent |
| **Preset** / **template** | Saved inputs and credential references for re-running |
| **Trigger** | Webhook-driven agent start |
| **Schedule** | Cron-like recurring run |
| **Library** | Your agents (built, imported, or added from the Marketplace) |
| **Credits** | Metered cost of block execution on the hosted Platform |

### 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.

| Concept | Behavior |
|---|---|
| Starting point | Input blocks and blocks with no inbound links |
| Ending point | Output blocks |
| Parallelism | Independent blocks can execute in any order |
| Errors | Failed blocks emit on their error pin; you decide what happens |
| Lists | Whole list or item by item |
| Visual feedback | Coloured beads on connection lines |

### 7.3 What happens when you click Start Task

```text
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)

| Data | Compose location | Appliance location |
|---|---|---|
| Accounts, agents, runs | Postgres, `autogpt_platform/data/db/data` | `/data/postgres` |
| Queue state | RabbitMQ container | `/data/rabbitmq` |
| Cache / realtime | Redis cluster | `/data/valkey` |
| Memory graph | FalkorDB | `/data/falkordb` |
| User workspaces | backend storage | `/data/workspaces` |
| Marketplace media (no GCS) | local `store-media/` | `/data/store-media` |

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:

```bash
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:**

```bash
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:

```bash
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:

```bash
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](#23-install-from-source-docker-compose)).

**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/`)

| Command | What it does |
|---|---|
| `make init-env` | Create missing `.env` files and generate blank secrets |
| `make start-core` | `docker compose up -d deps` (Postgres, Redis, RabbitMQ) |
| `make stop-core` | `docker compose stop` |
| `make logs-core` | Tail core-service logs |
| `make reset-db` | Stop `db`, delete `data/db/data`, re-run migrations and Prisma generate |
| `make migrate` | `prisma migrate deploy` + `prisma generate` + `gen-prisma-stub` |
| `make run-backend` | `cd backend && poetry run app` |
| `make run-frontend` | `cd frontend && pnpm dev` |
| `make format` | Backend `poetry run format`; frontend `pnpm format` and `pnpm lint` |
| `make test-data` | Run the test data creator |
| `make load-store-agents` | Load store agents from the `agents/` folder into the test DB |
| `make help` | List targets |

> [!CAUTION]
> `make reset-db` **deletes** `data/db/data` — all accounts, agents, and run history.

#### Backend Poetry scripts (`autogpt_platform/backend`)

| Command | Starts / does |
|---|---|
| `poetry run app` | All backend services together |
| `poetry run rest` | REST API server |
| `poetry run ws` | WebSocket server |
| `poetry run executor` | Graph executor |
| `poetry run copilot-executor` | AutoPilot executor |
| `poetry run batch-executor` | Batch executor |
| `poetry run scheduler` | Scheduler |
| `poetry run notification` | Notification service |
| `poetry run db` | Database manager service |
| `poetry run platform-linking-manager` | Chat-bot account linking service |
| `poetry run copilot-bot` | AutoPilot chat bot (standalone) |
| `poetry run cli ...` | Admin CLI (see below) |
| `poetry run oauth-tool ...` | OAuth app tooling (see below) |
| `poetry run export-api-schema` | Write the OpenAPI JSON |
| `poetry run format` / `lint` / `test` | Code quality and tests |
| `poetry run load-store-agents` | Seed store agents |
| `poetry run analytics-setup` / `analytics-views` | Analytics views |
| `poetry run gen-prisma-stub` | Regenerate Prisma type stubs |

#### `poetry run cli` — backend admin CLI

| Command | Options | Purpose |
|---|---|---|
| `cli start` | — | Start the backend |
| `cli stop` | — | Stop the backend |
| `cli gen-encrypt-key` | — | Print a new Fernet `ENCRYPTION_KEY` |
| `cli rotate-encryption-key` | `--old-key` (or env `OLD_ENCRYPTION_KEY`), `--apply` | Re-encrypt stored credentials under the current key; dry run without `--apply` |
| `cli chat list` | `--user`, `--limit/-n` (default 20) | List AutoPilot chat sessions |
| `cli chat view SESSION_ID [SEQ_RANGE]` | `--full/-f`, `--json`, `--limit/-n` | Show a chat session (range forms `7`, `6-10`, `6-`, `-10`) |
| `cli store backfill-categories` | `--apply`, `--limit`, `--concurrency` (default 5) | Classify store listings into categories |
| `cli test reddit SERVER_ADDRESS` | — | Test helper |
| `cli test populate-db SERVER_ADDRESS` | — | Populate test data |
| `cli test graph SERVER_ADDRESS` | — | Create a test graph |
| `cli test execute GRAPH_ID CONTENT` | — | Execute a graph |
| `cli test event` | — | Send a test event |
| `cli test websocket SERVER_ADDRESS GRAPH_EXEC_ID` | — | Watch execution over WebSocket |

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`

| Command | Options |
|---|---|
| `generate-app` | `--name`, `--description`, `--redirect-uris` (comma-separated), `--scopes` (comma-separated, e.g. `EXECUTE_GRAPH,READ_GRAPH`), `--grant-types` (default `authorization_code,refresh_token`) |
| `hash-secret SECRET` | Hash a client secret |
| `validate-secret SECRET HASH SALT` | Validate a secret against a hash |
| `test-server` | `--owner-id`, `--port`, `--platform-url` (default `http://localhost:3000`), `--backend-url` (default `http://localhost:8006`) |

#### Single-container appliance commands

| Command | Purpose |
|---|---|
| `docker exec autogpt autogpt-admin promote EMAIL` | Grant administrator role |
| `docker exec autogpt autogpt-healthcheck` | Check every bundled service |
| `docker exec autogpt supervisorctl status` | Show supervised processes (e.g. `runtime:rest`, `state:postgres`) |
| `python3 single-container/runtime_config.py fill-env --path FILE [--missing-ok]` | Fill blank secrets in an env file |

#### Classic: `poetry run autogpt` (from `classic/`)

| Command / option | Purpose |
|---|---|
| `autogpt run` | Run the interactive agent |
| `-c`, `--continuous` | Continuous mode (no approval between steps) |
| `-l`, `--continuous-limit` | Max iterations in continuous mode (requires `-c`) |
| `--speak` | Speak mode |
| `--install-plugin-deps` | Install third-party plugin dependencies |
| `--skip-news` | Suppress startup news |
| `-y`, `--skip-reprompt` | Skip re-prompting at start |
| `--ai-name`, `--ai-role` | Override AI name/role |
| `--constraint`, `--resource`, `--best-practice` | Add directives (repeatable) |
| `--override-directives` | Replace instead of append directives |
| `--debug` | Implies `--log-level=DEBUG --log-format=debug` |
| `--log-level`, `--log-format`, `--log-file-format` | Logging controls (`structured_google_cloud` disables file logs) |
| `--component-config-file` | JSON component configuration |
| `-w`, `--workspace` | Workspace directory (default: current directory) |
| `autogpt serve` | Agent Protocol server; takes `--install-plugin-deps`, `--debug`, logging options, `-w` |
| `autogpt config` | `-e/--env-file` (default `~/.autogpt/.env`) |

#### Classic: `poetry run direct-benchmark`

| Command | Key options |
|---|---|
| `run` | `-s/--strategies` (default `one_shot`), `-m/--models`, `-c/--categories`, `-S/--skip-category`, `-t/--tests`, `-N/--attempts` (1), `-p/--parallel` (4), `--timeout` (300), `--cutoff`, `--no-cutoff`, `--max-steps` (50), `--maintain`, `--improve`, `--explore`, `--no-dep`, `--workspace`, `--challenges-dir`, `--reports-dir`, `--keep-answers`, `-q`, `-v`, `--json`, `--ci`, `--fresh`, `--retry-failures`, `--reset-strategy`, `--reset-model`, `--reset-challenge`, `--debug`, `-b/--benchmark` (`gaia`, `swe-bench`, `agent-bench`), `--benchmark-split` (`validation`), `--benchmark-subset`, `--benchmark-limit`, `--benchmark-cache-dir` |
| `list-challenges` | `--challenges-dir` |
| `list-models` | — |
| `list-strategies` | — |
| `list-benchmarks` | — |
| `state show` / `state clear` | `--reports-dir` |
| `state reset` | `-s/--strategy`, `-m/--model`, `-c/--challenge`, `--reports-dir` |

### 10.2 Configuration Quick Reference

| Setting | File | Default / example | Notes |
|---|---|---|---|
| `ENCRYPTION_KEY` | backend | blank → generated | Required; Fernet key |
| `UNSUBSCRIBE_SECRET_KEY` | backend | blank → generated | Email unsubscribe links |
| `BETTER_AUTH_SECRET` | frontend | blank → generated | Session signing |
| `DATABASE_URL` | backend, frontend | `postgresql://postgres:...@localhost:5432/postgres?schema=platform...` | Frontend auth uses it too |
| `DB_SCHEMA` / `AUTH_DB_SCHEMA` | backend / frontend | `platform` | |
| `REDIS_HOST` / `REDIS_PORT` | backend | `localhost` / `17000` | |
| `JWT_JWKS_URL` | backend | `http://localhost:3000/api/auth/jwks` | HTTPS over untrusted networks |
| `FRONTEND_BASE_URL` | backend | `http://localhost:3000` | |
| `PLATFORM_BASE_URL` | backend | `http://localhost:8006` | Webhooks + OAuth |
| `NEXT_PUBLIC_AGPT_SERVER_URL` | frontend | `http://localhost:8006/api` | |
| `NEXT_PUBLIC_AGPT_WS_SERVER_URL` | frontend | `ws://localhost:8001/ws` | |
| `NEXT_PUBLIC_FRONTEND_BASE_URL` | frontend | `http://localhost:3000` | |
| `AUTOGPT_PUBLIC_URL` | appliance | `http://localhost:3000` | Exact browser origin |
| `AUTH_SIGNUP_ALLOWLIST` | appliance / frontend | empty (open) | Emails or `@domain` |
| `AUTH_ALLOW_NEW_ACCOUNTS` | appliance / frontend | open | `false` closes signup |
| `CHAT_USE_LOCAL` | backend / appliance | `false` | Local OpenAI-compatible AutoPilot |
| `CHAT_BASE_URL` / `CHAT_API_KEY` | backend / appliance | empty | Required for local profile |
| `CHAT_DAILY_COST_LIMIT_MICRODOLLARS` | appliance | `-1` (off) | Microdollars |
| `CHAT_WEEKLY_COST_LIMIT_MICRODOLLARS` | appliance | `-1` (off) | Microdollars |
| `DB_CONNECTION_LIMIT` | backend / appliance | `12` (Compose default file); appliance range `1`–`5`, default `5` | |
| `DB_CONNECT_TIMEOUT` | backend / appliance | `60` | Appliance range `1`–`600` |
| `DB_POOL_TIMEOUT` | backend / appliance | `300` | Appliance range `1`–`3600` |
| `BEHAVE_AS` | appliance | `local` | `cloud` for backend entitlement enforcement |
| `AUTOGPT_ENABLE_BOT_SERVICES` | appliance | `false` | Enables chat-bot processes |
| `POSTMARK_*` | backend / appliance | empty | Password reset emails |

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

---

_Generated September 2026 from Significant-Gravitas/AutoGPT at c035ab1. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._