Technical Documentation: Significant-Gravitas/AutoGPT

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

AutoGPT — AI agents that finish the work

The open-source platform for AI agents Copy Chapter

AutoGPT lets you build, deploy, and run AI agents that carry out complete workflows. Describe an outcome in plain English or shape every step in the visual builder, then run the agent on demand, on a schedule, or from a trigger.

185,000+ GitHub stars. Cited by:

Four surfaces, one platform Copy Chapter

| AutoPilot
Describe the job in plain English and turn the conversation into a working agent. | Agents
See every agent, run, cost, and action that needs your attention. |

| --- | --- |
| Marketplace
Start from proven agents, add one to your library, and customize it for your work. | Build
Drag, connect, branch, and inspect blocks for exact control over every step. |

Get started Copy Chapter

AutoGPT Platform — public, hosted, and managed Copy Section

The hosted Platform is publicly available. We manage the infrastructure, model access, credentials, reliability, and updates so you can focus on the work your agents perform.

Get started on AutoGPT Platform →

Take the interactive tour →

• AutoPilot, Agents, Marketplace, and Build
• 45+ connected platforms and hundreds of AI models
• No model API keys or infrastructure setup
• Agents that run on demand, on schedules, and from triggers

The hosted Platform is a paid service with usage-based agent runs. Compare plans and pricing →

Self-host AutoGPT Copy Section

[!NOTE]
Self-hosting is the free path. You provide the infrastructure and model API keys, and you maintain the deployment. If you want zero setup, use the managed Platform.

The Linux and macOS single-container release installer is coming with the next
appliance release. Until the public installer endpoint and image tags pass the
documented release gates,
use the manual self-hosting guide.

The release installer will require an already-running local Docker daemon using
Linux containers on amd64 or arm64. It pulls the published appliance and
runs its immutable digest; it does not install Docker or build from source.
Windows users should continue with the manual self-hosting guide for now.

Read the self-hosting guide →

Managed Platform vs. self-hosting Copy Chapter

Both paths use the same repository. Choose the managed Platform when you want agents running immediately; self-host when infrastructure control matters more than operational convenience.

Why the hosted Platform is paid Copy Chapter

Every agent run consumes real model usage, compute, storage, secrets management, and operational support. The managed Platform covers that infrastructure and funds continued development of the open-source project.

Self-hosting remains available without a license fee for people and teams that want to provide and operate those resources themselves.

What you can automate Copy Chapter

Integrations Copy Chapter

Connect the apps that are yours. AutoGPT provides access to hundreds of AI models and connects agents to 45+ platforms, including:

Gmail · Google Calendar · Google Docs · Google Sheets · GitHub · Slack · Discord · Notion · HubSpot · Linear · Airtable · Jira · Salesforce · Stripe · Webflow

Explore the integrations →

Community and support Copy Chapter

License Copy Chapter

AutoGPT Classic Copy Chapter

Looking for the original standalone AutoGPT agent? It remains available in classic/ under the MIT License.

• Build an agent with Forge
• Benchmark an agent with agbenchmark
• Explore the Classic project

Contributors Copy Chapter

Deutsch |
Español |
français |
日本語 |
한국어 |
Português |
Русский |
中文

Content Index (`docs/content/index.md`) Copy Section

AutoGPT Documentation

Welcome to the AutoGPT Documentation.

What is the AutoGPT Platform? Copy Chapter

The AutoGPT Platform is a groundbreaking system that revolutionizes AI utilization for businesses and individuals. It enables the creation, deployment, and management of continuous agents that work tirelessly on your behalf, bringing unprecedented efficiency and innovation to your workflows.

Key Features Copy Section

• Seamless Integration and Low-Code Workflows: Rapidly create complex workflows without extensive coding knowledge.
• Autonomous Operation and Continuous Agents: Deploy cloud-based assistants that run indefinitely, activating on relevant triggers.
• Intelligent Automation and Maximum Efficiency: Streamline workflows by automating repetitive processes.
• Reliable Performance and Predictable Execution: Enjoy consistent and dependable long-running processes.

Platform Architecture Copy Chapter

The AutoGPT Platform consists of two main components:

1. AutoGPT Server Copy Section

The powerhouse of our platform, containing:

• Source Code: Core logic driving agents and automation processes.
• Infrastructure: Robust systems ensuring reliable and scalable performance.
• Marketplace: A comprehensive marketplace for pre-built agents.

2. AutoGPT Frontend Copy Section

The user interface where you interact with the platform:

• Agent Builder: Design and configure your own AI agents.
• Workflow Management: Build, modify, and optimize automation workflows.
• Deployment Controls: Manage the lifecycle of your agents.
• Ready-to-Use Agents: Select from pre-configured agents.
• Agent Interaction: Run and interact with agents through a user-friendly interface.
• Monitoring and Analytics: Track agent performance and gain insights.

Platform Components Copy Chapter

Agents and Workflows Copy Section

In the platform, you can create highly customized workflows to build agents. An agent is essentially an automated workflow that you design to perform specific tasks or processes. Create customized workflows to build agents for various tasks, including:

• Data processing and analysis
• Task scheduling and management
• Communication and notification systems
• Integration between different software tools
• AI-powered decision making and content generation

Blocks as Integrations Copy Section

Blocks represent actions and are the building blocks of your workflows, including:

• Connections to external services
• Data processing tools
• AI models for various tasks
• Custom scripts or functions
• Conditional logic and decision-making components

You can learn more under: Build your own Blocks

Available Language Models Copy Chapter

The platform comes pre-integrated with cutting-edge LLM providers:

• OpenAI - https://openai.com/
• Anthropic - https://www.anthropic.com/
• Groq - https://groq.com/
• Llama - https://llamaindex.ai/
• AI/ML API - https://aimlapi.com/
  • AI/ML API provides 300+ AI models including Deepseek, Gemini, ChatGPT. The models run at enterprise-grade rate limits and uptimes.

License Overview Copy Chapter

We've adopted a dual-license approach to balance open collaboration with sustainable development:

• MIT License: The majority of the AutoGPT repository remains under this license.
• Polyform Shield License: Applies to the new autogpt_platform folder.

This strategy allows us to share previously closed-source components, fostering a vibrant ecosystem of developers and users.

Ready to Get Started? Copy Chapter

• Read the Getting Started docs to self-host
• Join the waitlist for the cloud-hosted beta
• Contribute

Engineering README (`docs/engineering/README.md`) Copy Section

Engineering notes

Working documents for the team and the agents that work on AutoGPT: analytics and tracking plans, rollout plans, runbooks, internal references, and design and architecture notes.

Nothing in this folder is on the docs site. The site at agpt.co/docs is built from docs/home/, docs/platform/ and docs/integrations/, and shows the pages listed in each folder's SUMMARY.md. A page written for people outside the team, whether they use, self-host or contribute to AutoGPT, goes there. Everything else goes here.

These notes are still public. The repository is public, and AutoPilot's documentation search indexes every Markdown file under docs/, this folder included.

• Don't list a file from this folder in a SUMMARY.md.
• To link to a note from a published page, use its GitHub URL on dev. The relative path does not exist on the docs site.

Home README (`docs/home/README.md`) Copy Section

cover: .gitbook/assets/Banner_image.png
coverY: 56.53835084561286
layout:
width: wide
cover:
visible: true
size: full
title:
visible: false
visible: false
tableOfContents:
visible: false
outline:
visible: false
pagination:
visible: false
metadata:
visible: true

Developer Platform

AutoGPT Documentation

{% columns %}
{% column valign="middle" %}

{% endcolumn %}

{% column %}

{% endcolumn %}
{% endcolumns %}

Join a community of 65,000+ developers

Integrations README (`docs/integrations/README.md`) Copy Section

layout:
width: default
title:
visible: true
visible: true
tableOfContents:
visible: false
outline:
visible: true
pagination:
visible: true
metadata:
visible: true

AutoGPT Blocks Overview

AutoGPT uses a modular approach with various "blocks" to handle different tasks. These blocks are the building blocks of AutoGPT workflows, allowing users to create complex automations by combining simple, specialized components.

{% hint style="info" %}
Creating Your Own Blocks

Want to create your own custom blocks? Check out our guides:

• Build your own Blocks - Step-by-step tutorial with examples
• Block SDK Guide - Advanced SDK patterns with OAuth, webhooks, and provider configuration
  {% endhint %}

Below is a comprehensive list of all available blocks, categorized by their primary function. Click on any block name to view its detailed documentation.

Basic Operations Copy Chapter

Data Processing Copy Chapter

Text Processing Copy Chapter

AI and Language Models Copy Chapter

Search and Information Retrieval Copy Chapter

Social Media and Content Copy Chapter

Communication Copy Chapter

Developer Tools Copy Chapter

Media Generation Copy Chapter

Productivity Copy Chapter

Logic and Control Flow Copy Chapter

Input/Output Copy Chapter

Agent Integration Copy Chapter

CRM Services Copy Chapter

AI Safety Copy Chapter

Issue Tracking Copy Chapter

Hardware Copy Chapter

Platform Getting Started (`docs/platform/getting-started.md`) Copy Section

Getting Started with AutoGPT: Self-Hosting Guide

Introduction Copy Chapter

This guide will help you setup the server and builder for the project.

!!! warning
DO NOT FOLLOW ANY OUTSIDE TUTORIALS AS THEY WILL LIKELY BE OUT OF DATE

Prerequisites Copy Chapter

The single-container appliance's only product prerequisite is an installed,
running Docker CLI and daemon. Select a local Docker endpoint using Linux
containers on amd64 or arm64. The Unix bootstrap also uses Bash, curl, and
sha256sum or shasum. Docker Compose, Git, Node.js, and NPM are not required
for the appliance installer.

Install Docker from the official Docker documentation,
start it, then verify the selected daemon:

docker -v
docker info

Quick Setup with the Appliance Installer Copy Chapter

The release installer pulls and starts the published single-container
appliance: one Docker container, one loopback port, no source checkout. It
needs a running Docker daemon with Linux containers on amd64 or arm64; it
does not install Docker or build AutoGPT from source. See
the installer reference for details.

The hosted installer is not live yet: setup.agpt.co/install.sh still serves
the Compose installer, and the appliance image tags are not public until the
release gates pass. This first release
supports Linux and macOS. Until then, and on Windows, use the
from-source setup below, which is also the path that supports
a fully offline install with a local LLM.

Manual Setup Copy Chapter

Development prerequisites Copy Section

The manual source checkout requires
Git,
Node.js and NPM, Docker, and
Docker Compose. Verify them before
continuing:

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

Cloning the Repository Copy Section

The first step is cloning the AutoGPT repository to your computer.
To do this, open a terminal window in a folder on your computer and run:

git clone https://github.com/Significant-Gravitas/AutoGPT.git

If you get stuck, follow this guide.

Once that's complete you can continue the setup process.

Running the AutoGPT Platform Copy Section

To run the platform, follow these steps:

• Navigate to the autogpt_platform directory inside the AutoGPT folder:
  bash Copy

  cd AutoGPT/autogpt_platform

• Create the .env files and generate your local secrets:

  text Copy

  make init-env

  This copies each .env.default to .env (for autogpt_platform, backend
  and frontend) and fills in the secrets that .env.default deliberately
  leaves blank — ENCRYPTION_KEY, UNSUBSCRIBE_SECRET_KEY and
  BETTER_AUTH_SECRET — with values generated for your machine. Those files
  are public, so shipping working values in them would mean every install in
  the world shared one publicly-readable key. It is safe to re-run: it never
  overwrites an existing .env or a value you set yourself. You can then edit
  the .env files to add your own environment variables.

  The backend refuses to start while ENCRYPTION_KEY is empty, so run this
  before bringing the stack up.

• Run the platform services:

  text Copy

  docker compose up -d --build

  This command will start all the necessary backend services defined in the docker-compose.yml file in detached mode.

🛠️ Using the Makefile for Common Tasks Copy Section

The repository includes a Makefile with helpful commands to streamline setup and development. You may use make commands as an alternative to calling Docker or scripts directly.

Most-used Makefile commands

Inside the autogpt_platform directory, you can use:

Example usage:

make init-env
make start-core
make migrate
make publish-skills
make run-backend
make run-frontend

docker compose up runs the migrations and the skills catalog publish for you: the publish_skills service downloads the public Significant-Gravitas/skills-catalog repository after migrate finishes, so the Skills Hub and the roster experts are there on first start. It needs network access to GitHub; offline, point SKILLS_CATALOG_PATH in backend/.env at a local checkout of that repository.

make init-env matters when running the frontend outside Docker: Next.js
only reads .env (not .env.default), and the frontend's embedded auth
service needs DATABASE_URL and BETTER_AUTH_SECRET from it.

You can always check available Makefile recipes by running:

make help

(or just inspecting the Makefile in the repo root).

Checking if the application is running Copy Section

You can check if the server is running by visiting http://localhost:3000 in your browser.

Notes:

By default the application for different services run on the following ports:

Frontend UI Server: 3000
Backend Websocket Server: 8001
Execution API Rest Server: 8006

Upgrading: secrets are generated per install Copy Section

ENCRYPTION_KEY, UNSUBSCRIBE_SECRET_KEY and BETTER_AUTH_SECRET used to
come with a value in .env.default, so every install that did not set its own
ran on the same three values. They are now blank there and generated for each
install, and the backend does not start without an ENCRYPTION_KEY or
with the one .env.default used to contain.

A fresh install needs nothing beyond make init-env (or the installer script,
which does the same). An install that already set its own values needs
nothing either. Follow the steps below if you are upgrading an install that

• has no autogpt_platform/backend/.env, or one without an ENCRYPTION_KEY
  line — it was running on the value from .env.default; or
• stops on startup with ENCRYPTION_KEY is set to a value that was published…
  or ENCRYPTION_KEY is not set.

Your connected integrations are encrypted with ENCRYPTION_KEY, so the steps
move them to the new key instead of losing them. Run everything from
autogpt_platform/.

1. Stop the stack:

   bash Copy

   docker compose down

2. Keep the key your data is currently encrypted with. If you never set one,
   it is the value .env.default contained up to release v0.7.4:

   bash Copy

   export OLD_ENCRYPTION_KEY=$(git show autogpt-platform-beta-v0.7.4:autogpt_platform/backend/.env.default \
     | grep '^ENCRYPTION_KEY=' | cut -d= -f2-)

   If you did set one and are replacing it, export that value instead, and keep
   a copy of the file outside the checkout until step 4 reports nothing
   unreadable, because step 3 removes the only other place the key is written
   down:

   bash Copy

   cp backend/.env ~/autogpt-backend.env.$(date +%Y%m%d-%H%M%S)

3. Generate the new values. make init-env creates any missing .env file
   and fills in every secret whose line is present but empty; it never
   overwrites a value. So in backend/.env make sure these two lines exist
   with nothing after the =, and do the same for BETTER_AUTH_SECRET= in
   frontend/.env:

   text Copy

   ENCRYPTION_KEY=
   UNSUBSCRIBE_SECRET_KEY=

   Then:

   bash Copy

   make init-env

   Without make, these are the same steps by hand. Copy a .env.default
   only where no .env exists yet:

   bash Copy

   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

   Do not re-run the installer script for this: it also starts the stack,
   which is step 5.

4. Re-encrypt what is stored. Build the new images and bring the database up
   to date first; migrate starts the database on its own:

   bash Copy

   docker compose build migrate rest_server
   docker compose run --rm migrate

   Then run the command, first as a dry run that only reports what it would
   change, then with --apply to write it. --no-deps keeps it from waiting
   on the rest of the stack, which it does not need:

   bash Copy

   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

   It is safe to run more than once: values already under the new key are left
   alone, and a value that neither key can read is listed and not touched.
   Running the backend outside Docker, the same command is
   poetry run cli rotate-encryption-key in autogpt_platform/backend.

5. Start the stack again. If BETTER_AUTH_SECRET changed in step 3, first
   clear the token signing key the frontend stored under the old value: it can
   no longer be decrypted, and until it is removed nobody can reach the
   backend, even after signing in again. A new one is created on the next
   sign-in. --build brings the remaining services to the release you built
   in step 4:

   bash Copy

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

Two smaller effects of the new values: unsubscribe links in emails sent before
the upgrade stop working (UNSUBSCRIBE_SECRET_KEY), and everyone signs in
again once (BETTER_AUTH_SECRET).

Do step 4 before step 5. On a new key the stored values are still in the
database but read as empty, and a user who connects an integration in that
state replaces their stored set: their other credentials are marked revoked.
If the stack already ran on the new key, stop it and run step 4 now. Whatever
nobody touched is recovered; a user who connected something in between gets
their older credentials re-encrypted but still revoked, and reconnects those.

Upgrading an existing (Supabase-based) installation Copy Section

Older versions of the platform ran authentication on a bundled Supabase
stack. If you self-hosted before the switch to the built-in auth service,
three things changed:

1. Environment files: refresh your .env files against the new
   .env.defaults. make init-env copies .env.default → .env for
   autogpt_platform, backend and frontend, but only where no .env
   exists yet (it uses cp -n): it creates missing .env files and never
   overwrites an existing one. It does not merge newly-added variables
   into an .env you already have — for an existing install, diff each
   .env against its .env.default and copy the new keys across yourself.
   The SUPABASE_* URL/key variables are gone; the frontend now uses
   BETTER_AUTH_SECRET and DATABASE_URL.

   ENCRYPTION_KEY, UNSUBSCRIBE_SECRET_KEY and BETTER_AUTH_SECRET are no
   longer filled in by .env.default: follow
   Upgrading: secrets are generated per install
   as part of this step.

2. Database location: the database now lives in a plain Postgres
   container (pgvector/pgvector:pg15) with its data in
   autogpt_platform/data/db/data. Your old data is untouched at
   autogpt_platform/db/docker/volumes/db/data but is no longer mounted.

   If you already booted the new stack while that folder was still called
   volumes/, move your data across before starting it again:

   sh Copy

   mkdir -p autogpt_platform/data/db
   mv autogpt_platform/volumes/db/data autogpt_platform/data/db/data

   To carry the old Supabase data over, pick one of the two routes below.
   Neither has been validated against a real old volume yet, so back up
   autogpt_platform/db/docker/volumes/db/data before you start.

   The old bundled stack ran supabase/postgres:15.8.1.049 and the new db
   service runs pgvector/pgvector:pg15 — the same Postgres major, so
   reusing the data directory as-is is plausible rather than impossible. It
   is not guaranteed: a data directory is only portable between servers on
   the same major and with a compatible extension set /
   shared_preload_libraries. The Supabase image ships extensions and roles
   (supabase_admin, pgjwt, pgsodium, pg_graphql, …) that the plain
   pgvector image does not have, so a moved directory can fail to start, or
   start and then fail on objects that reference the missing extensions.

   Fast path — reuse the data directory:

   sh Copy

   cd autogpt_platform
   docker compose down
   mkdir -p data/db
   rm -rf data/db/data                            # discards a freshly-initialised new DB
   cp -a db/docker/volumes/db/data data/db/data   # copy, so the old dir stays intact
   docker compose up -d db
   docker compose logs -f db

   On Linux the data directory is mode 0700 owned by the container's
   postgres user, so the copy needs sudo cp -a (the plain Postgres
   entrypoint fixes ownership on first boot). On Docker Desktop for
   macOS/Windows the plain cp -a is enough.
   It worked if the log settles on database system is ready to accept connections and your data is there:

   sh Copy

   docker compose exec db psql -U postgres -c '\dn'
   docker compose exec db psql -U postgres -c 'select count(*) from platform."User"'

   It did not work if the container restart-loops with errors such as
   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 — Postgres
   is either missing something the Supabase image provided, or can't read the
   copied files. In that case rm -rf data/db/data and use the fallback.

   Fallback — same-major dump and restore:

   Step 1 starts a real Postgres server against your original data
   directory, read-write. Make sure you took the backup above first.

   sh Copy

   cd autogpt_platform
   # 1. Bring the OLD image up against the OLD data directory, on a spare port.
   docker run --rm -d --name old-db -p 5433:5432 \
     -e POSTGRES_PASSWORD=your-super-secret-and-long-postgres-password \
     -v "$(pwd)/db/docker/volumes/db/data:/var/lib/postgresql/data" \
     supabase/postgres:15.8.1.049
   # 2. Dump without Supabase-owned ownership/ACL metadata.
   docker exec old-db pg_dump -U postgres -d postgres \
     --no-owner --no-privileges -Fc -f /tmp/old.dump
   docker cp old-db:/tmp/old.dump ./old.dump
   docker stop old-db
   # 3. Restore into the new db service (fresh volume).
   docker compose up -d db
   # A fresh volume runs db/init/00-init.sql, which creates an EMPTY auth.users
   # shim with only the columns the migrations need. Drop it first, or the
   # restore of your real auth.users collides with it and copies no users.
   docker compose exec db psql -U postgres -c 'DROP SCHEMA IF EXISTS auth CASCADE;'
   docker compose cp ./old.dump db:/tmp/old.dump
   docker compose exec db pg_restore -U postgres -d postgres \
     --no-owner --no-privileges /tmp/old.dump
   # 4. Confirm your accounts actually landed BEFORE migrating.
   docker compose exec db psql -U postgres -c 'select count(*) from auth.users'

   pg_restore reports errors for objects belonging to Supabase-only
   extensions and roles (storage, realtime, supabase_admin, pgsodium,
   …). Those are harmless. An error on auth.users is not: that table is
   where your accounts live, and the migration in step 3 below copies them out
   of it. If the count above is 0 — or pg_restore failed on auth.users —
   stop and fix the restore before continuing, or you will bring the stack up
   with no user accounts.

   Either way, finish with the migrations before bringing up the rest:

   sh Copy

   docker compose run --rm migrate
   docker compose up -d

3. User accounts and sessions: a normal upgrade (stack stopped, then
   restarted on the new version) needs no extra step here.

   • Existing users are copied from the Supabase auth.users table into the
     Better Auth tables by the backend Prisma migration
     20260716120000_copy_supabase_users_to_better_auth, which runs as part
     of the docker compose run --rm migrate step above.
   • Existing browser sessions keep working because the frontend recognises
     old Supabase JWT cookies and swaps them for a Better Auth session on
     the user's next visit. Keep SUPABASE_JWT_SECRET set in
     frontend/.env for as long as you want that bridge open.
   • frontend/scripts/migrate-supabase-auth.ts is optional and only
     applies to a live cutover, where Supabase kept accepting signups
     while the new stack was already running. It is a re-runnable sweep for
     those stragglers; if you stopped the stack to upgrade, skip it.
     sh Copy

     cd frontend && DATABASE_URL=postgresql://postgres:<password>@localhost:5432/postgres npx tsx scripts/migrate-supabase-auth.ts

A fresh install (empty database) needs none of this.

Additional Notes Copy Section

make init-env already generates a unique ENCRYPTION_KEY for your install, so
there is normally nothing to change here. To rotate it — for example if you
carried a key over from an older checkout, back when .env.default shipped a
working (and therefore public) one — generate a new key in python:

from cryptography.fernet import Fernet;Fernet.generate_key().decode()

Or run the following command in the autogpt_platform/backend directory:

poetry run cli gen-encrypt-key

Then replace the value in autogpt_platform/backend/.env and re-encrypt the
stored integration credentials under it, with the previous value as
OLD_ENCRYPTION_KEY — steps 4 and 5 of
Upgrading: secrets are generated per install.
Without that step the credentials stored under the previous key are unreadable
and those integrations need reconnecting.

Auth transport security (JWKS over untrusted networks)

The backend verifies login tokens using signing keys it fetches from the frontend at JWT_JWKS_URL (.../api/auth/jwks). It trusts whatever keys that URL returns, so the fetch must run over a trusted path:

• Plain http is fine for localhost and for container-to-container traffic on a single host (the default http://frontend:3000 over the Docker network) — there is no network segment for an attacker to sit on.
• Use https on an untrusted network. If you split the backend and frontend across separate machines on a LAN, or expose them publicly, a cleartext JWKS fetch can be intercepted: an attacker who swaps the published keys can forge tokens for any user. Put the frontend behind TLS (a reverse proxy), or issue locally-trusted certificates (e.g. mkcert), and point JWT_JWKS_URL at the https:// URL.

The backend refuses to start if JWT_JWKS_URL is a cleartext http:// URL pointing at a non-local host. If your network path is trusted (e.g. an isolated private LAN), set JWKS_ALLOW_INSECURE_TRANSPORT=true to boot anyway — a startup warning stays on record so the tradeoff is visible in logs.

This is a property of stateless JWT/JWKS verification in general, not something specific to AutoGPT. On a standard single-host Docker install you don't need to change anything.

📌 Windows Installation Note Copy Section

When installing Docker on Windows, it is highly recommended to select WSL 2 instead of Hyper-V. Using Hyper-V can cause compatibility issues with the platform's containers, leading to the db (Postgres) container being marked as unhealthy.

**Steps to enable WSL 2 for Docker:**

1. Install WSL 2.
2. Ensure that your Docker settings use WSL 2 as the default backend:
   • Open Docker Desktop.
   • Navigate to Settings > General.
   • Check Use the WSL 2 based engine.
3. Restart Docker Desktop.

**Already Installed Docker with Hyper-V?**

If you initially installed Docker with Hyper-V, you don’t need to reinstall it. You can switch to WSL 2 by following these steps:

1. Open Docker Desktop.
2. Go to Settings > General.
3. Enable Use the WSL 2 based engine.
4. Restart Docker.

🚨 Warning: Enabling WSL 2 may erase your existing containers and build history. If you have important containers, consider backing them up before switching.

For more details, refer to Docker's official documentation.

⚠️ Podman Not Supported Copy Section

AutoGPT requires Docker (Docker Desktop or Docker Engine). Podman and podman-compose are not supported and may cause path resolution issues, particularly on Windows.

If you see errors like:

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

This indicates you're using Podman instead of Docker. Please install Docker Desktop and use docker compose instead of podman-compose.

Development Copy Chapter

Frontend Development Copy Section

Running the frontend locally

To run the frontend locally, you need to have Node.js and PNPM installed on your machine.

Install Node.js to manage dependencies and run the frontend application.

Install PNPM to manage the frontend dependencies.

Run the service dependencies (backend, database, message queues, etc.):

docker compose --profile local up deps_backend --build --detach

Go to the autogpt_platform/frontend directory:

cd frontend

Install the dependencies:

pnpm install

Generate the API client:

pnpm generate:api-client

Run the frontend application:

pnpm dev

Formatting & Linting

Auto formatter and linter are set up in the project. To run them:

Format the code:

pnpm format

Lint the code:

pnpm lint

Or for both frontend and backend, from the root:

make format

Testing

To run the tests, you can use the following command:

pnpm test

Backend Development Copy Section

Running the backend locally

To run the backend locally, you need to have Python 3.10 or higher installed on your machine.

Install Poetry to manage dependencies and virtual environments.

Run the backend dependencies (database, message queues, etc.):

docker compose --profile local up deps --build --detach

Or equivalently with Makefile:

make start-core

Go to the autogpt_platform/backend directory:

cd backend

Install the dependencies:

poetry install --with dev

Run the backend server:

poetry run app

Or from within autogpt_platform:

make run-backend

Formatting & Linting

Auto formatter and linter are set up in the project. To run them:

Format the code:

poetry run format

Lint the code:

poetry run lint

Or format both frontend and backend at once:

make format

Testing

To run the tests:

poetry run pytest -s

Adding a New Agent Block Copy Chapter

To add a new agent block, you need to create a new class that inherits from Block and provides the following information:

• All the block code should live in the blocks (backend.blocks) module.
• input_schema: the schema of the input data, represented by a Pydantic object.
• output_schema: the schema of the output data, represented by a Pydantic object.
• run method: the main logic of the block.
• test_input & test_output: the sample input and output data for the block, which will be used to auto-test the block.
• You can mock the functions declared in the block using the test_mock field for your unit tests.
• Once you finish creating the block, you can test it by running poetry run pytest backend/blocks/test/test_block.py -s.
• Create a Pull Request to the dev branch of the repository with your changes so you can share it with the community :)

Content Classic Index (`docs/content/classic/index.md`) Copy Section

AutoGPT Agent

🔧 Setup
 | 
💻 User guide
 | 
🐙 GitHub

Location: classic/original_autogpt/ in the GitHub repo

Maintance Notice: AutoGPT Classic is not supported from a security perspective.
Dependencies will not be updated, nor will issues be fixed. If someone wishes to
contribute to novel development, we will give best effort merging to the changes that
pass the existing CI.

AutoGPT Classic was conceived when OpenAI published their GPT-4 model accompanied by a paper
outlining the advanced reasoning and task-solving abilities of the model. The concept
was (and still is) fairly simple: let an LLM decide what to do over and over, while
feeding the results of its actions back into the prompt. This allows the program to
iteratively and incrementally work towards its objective.

The fact that this program is able to execute actions on behalf of its user makes
it an agent. In the case of AutoGPT Classic, the user still has to authorize every action,
but as the project progresses we'll be able to give the agent more autonomy and only
require consent for select actions.

AutoGPT Classic is a generalist agent, meaning it is not designed with a specific task in
mind. Instead, it is designed to be able to execute a wide range of tasks across many
disciplines, as long as it can be done on a computer.

AutoGPT Classic Documentation

Welcome to the AutoGPT Classic Documentation.

The AutoGPT Classic project consists of four main components:

• The Agent – also known as just "AutoGPT Classic"
• The Benchmark – AKA agbenchmark
• The Forge
• The Frontend

To tie these together, we also have a CLI at the root of the project.

🤖 Agent Copy Chapter

📖 About AutoGPT Classic
 | 
🔧 Setup
 | 
💻 Usage

The former heart of AutoGPT, and the project that kicked it all off: a semi-autonomous agent powered by LLMs to execute any task for you*.

We continue to develop this project with the goal of providing access to AI assistance to the masses, and building the future transparently and together.

• 💡 Explore - See what AI can do and be inspired by a glimpse of the future.

• 🚀 Build with us - We welcome any input, whether it's code or ideas for new features or improvements! Join us on Discord and find out how you can join in on the action.

If you'd like to see what's next, check out the AutoGPT Platform.

* it isn't quite there yet, but that is the ultimate goal that we are still pursuing

🎯 Benchmark Copy Chapter

🗒️ Readme

Measure your agent's performance! The agbenchmark can be used with any agent that supports the agent protocol, and the integration with the project's CLI makes it even easier to use with AutoGPT Classic and forge-based agents. The benchmark offers a stringent testing environment. Our framework allows for autonomous, objective performance evaluations, ensuring your agents are primed for real-world action.

• 📦 agbenchmark on Pypi

• 🔌 Agent Protocol Standardization - AutoGPT Classic uses the agent protocol from the AI Engineer Foundation to ensure compatibility with many agents, both from within and outside the project.

🏗️ Forge Copy Chapter

📖 Introduction
 | 
🚀 Quickstart

Forge your own agent! The Forge is a ready-to-go template for your agent application. All the boilerplate code is already handled, letting you channel all your creativity into the things that set your agent apart.

• 🛠️ Building with Ease - We've set the groundwork so you can focus on your agent's personality and capabilities. Comprehensive tutorials are available here.

💻 Frontend Copy Chapter

🗒️ Readme

An easy-to-use and open source frontend for any Agent Protocol-compliant agent.

• 🎮 User-Friendly Interface - Manage your agents effortlessly.

• 🔄 Seamless Integration - Smooth connectivity between your agent and our benchmarking system.

🔧 CLI Copy Chapter

The project CLI makes it easy to use all of the components of AutoGPT Classic in the repo, separately or
together. To install its dependencies, simply run ./run setup, and you're ready to go!

$ ./run
Usage: cli.py [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  agent      Commands to create, start and stop agents
  benchmark  Commands to start the benchmark and list tests and categories
  setup      Installs dependencies needed for your system.

Common commands:

• ./run agent start autogpt – runs the AutoGPT Classic agent
• ./run agent create <name> – creates a new Forge-based agent project at agents/<name>
• ./run benchmark start <agent> – benchmarks the specified agent

🤔 Join the AutoGPT Discord server for any queries:
discord.gg/autogpt

Glossary of Terms Copy Section

• Repository: Space where your project resides.
• Forking: Copying a repository under your account.
• Cloning: Making a local copy of a repository.
• Agent: The AutoGPT you'll create and develop.
• Benchmarking: Testing your agent's skills in the Forge.
• Forge: The template for building your AutoGPT agent.
• Frontend: The UI for tasks, logs, and task history.

Content Contribute Index (`docs/content/contribute/index.md`) Copy Section

Contributing to the Docs

We welcome contributions to our documentation! Our docs are hosted on GitBook and published from GitHub.

How It Works Copy Chapter

• Documentation lives in the docs/ directory and changes like any other code: through a pull request to dev
• The published docs match master. When a release reaches master, its docs/ directory is copied to the gitbook branch, and GitBook publishes that
• The gitbook branch belongs to that copy. Don't open pull requests against it, and don't edit pages in GitBook: the next copy overwrites anything that isn't in master

Editing Docs Locally Copy Chapter

1. Clone the repository and create a branch from dev:

   shell Copy

   git clone https://github.com/Significant-Gravitas/AutoGPT.git
   cd AutoGPT
   git checkout -b my-docs-change origin/dev

2. Make your changes to markdown files in docs/

3. Preview changes with any markdown preview tool

Adding a New Page Copy Chapter

1. Create a new markdown file in the appropriate docs/ subdirectory
2. Add the new page to the relevant SUMMARY.md file to include it in the navigation
3. Submit a pull request to the dev branch

Submitting a Pull Request Copy Chapter

When you're ready to submit your changes, create a pull request targeting the dev branch. We will review your changes and merge them if appropriate. They appear on the published docs with the next release.

Platform Changelog README (`docs/platform/changelog/README.md`) Copy Section

Changelog

What's new in AutoPilot and the AutoGPT Platform. We ship updates regularly and document everything here.

Release windows reflect how changes were grouped for publication and may overlap when work spans consecutive releases.

2026 Copy Chapter

Content Classic Setup Index (`docs/content/classic/setup/index.md`) Copy Section

AutoGPT Agent setup

🐋 Set up & Run with Docker
 | 
👷🏼 For Developers

📋 Requirements Copy Chapter

Linux / macOS Copy Section

• Python 3.10 or later
• Poetry (instructions)

Windows (WSL) Copy Section

• WSL 2
  • See also the requirements for Linux
• Docker Desktop

Windows Copy Section

!!! attention
We recommend setting up AutoGPT with WSL. Some things don't work exactly the same on
Windows and we currently can't provide specialized instructions for all those cases.

• Python 3.10 or later (instructions)
• Poetry (instructions)
• Docker Desktop

Setting up AutoGPT Copy Chapter

Getting AutoGPT Copy Section

Since we don't ship AutoGPT as a desktop application, you'll need to download the
project from GitHub and give it a place on your computer.

• To get the latest bleeding edge version, use master.
• If you're looking for more stability, check out the latest AutoGPT release.

!!! note
These instructions don't apply if you're looking to run AutoGPT as a docker image.
Instead, check out the Docker setup guide.

Completing the Setup Copy Section

Once you have cloned or downloaded the project, you can find the AutoGPT Agent in the
original_autogpt/ folder.
Inside this folder you can configure the AutoGPT application with an .env file and (optionally) a JSON configuration file:

• .env for environment variables, which are mostly used for sensitive data like API keys
• a JSON configuration file to customize certain features of AutoGPT's Components

See the Configuration reference for a list of available environment variables.

1. Find the file named .env.template. This file may
   be hidden by default in some operating systems due to the dot prefix. To reveal
   hidden files, follow the instructions for your specific operating system:
   Windows and macOS.

2. Create a copy of .env.template and call it .env;
   if you're already in a command prompt/terminal window:

   shell Copy

   cp .env.template .env

3. Open the .env file in a text editor.

4. Set API keys for the LLM providers that you want to use: see below.

5. Enter any other API keys or tokens for services you would like to use.

   !!! note
   To activate and adjust a setting, remove the # prefix.

6. Save and close the .env file.

7. Optional: run poetry install to install all required dependencies. The
   application also checks for and installs any required dependencies when it starts.

8. Optional: configure the JSON file (e.g. config.json) with your desired settings.
   The application will use default settings if you don't provide a JSON configuration file.
   Learn how to set up the JSON configuration file

You should now be able to explore the CLI (./autogpt.sh --help) and run the application.

See the user guide for further instructions.

Setting up LLM providers Copy Chapter

You can use AutoGPT with any of the following LLM providers.
Each of them comes with its own setup instructions.

AutoGPT was originally built on top of OpenAI's GPT-4, but now you can get
similar and interesting results using other models/providers too.
If you don't know which to choose, you can safely go with OpenAI*.

* subject to change

OpenAI Copy Section

!!! attention
To use AutoGPT with GPT-4 (recommended), you need to set up a paid OpenAI account
with some money in it. Please refer to OpenAI for further instructions (link).
Free accounts are limited to GPT-3.5 with only 3 requests per minute.

1. Make sure you have a paid account with some credits set up: Settings > Organization > Billing

2. Get your OpenAI API key from: API keys

3. Open .env

4. Find the line that says OPENAI_API_KEY=

5. Insert your OpenAI API Key directly after = without quotes or spaces:

   ini Copy

   OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

   !!! info "Using a GPT Azure-instance"
   If you want to use GPT on an Azure instance, set USE_AZURE to True and
   make an Azure configuration file.
   
   Rename azure.yaml.template to azure.yaml and provide the relevant
   azure_api_base, azure_api_version and deployment IDs for the models that you
   want to use.
   
   E.g. if you want to use gpt-3.5-turbo and gpt-4-turbo:
   
   yaml # Please specify all of these values as double-quoted strings # Replace string in angled brackets (<>) to your own deployment Name azure_model_map: gpt-3.5-turbo: "<gpt-35-turbo-deployment-id>" gpt-4-turbo: "<gpt-4-turbo-deployment-id>" ...
   
   Details can be found in the openai/python-sdk/azure, and in the [Azure OpenAI docs] for the embedding model.
   If you're on Windows you may need to install an MSVC library.

!!! important
Keep an eye on your API costs on the Usage page.

Anthropic Copy Section

1. Make sure you have credits in your account: Settings > Plans & billing
2. Get your Anthropic API key from Settings > API keys
3. Open .env
4. Find the line that says ANTHROPIC_API_KEY=
5. Insert your Anthropic API Key directly after = without quotes or spaces:
   ini Copy

   ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

6. Set SMART_LLM and/or FAST_LLM to the Claude 3 model you want to use.
   See Anthropic's models overview for info on the available models.
   Example:
   ini Copy

   SMART_LLM=claude-3-opus-20240229

!!! important
Keep an eye on your API costs on the Usage page.

Groq Copy Section

!!! note
Although Groq is supported, its built-in function calling API isn't mature.
Any features using this API may experience degraded performance.
Let us know your experience!

1. Get your Groq API key from Settings > API keys
2. Open .env
3. Find the line that says GROQ_API_KEY=
4. Insert your Groq API Key directly after = without quotes or spaces:
   ini Copy

   GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

5. Set SMART_LLM and/or FAST_LLM to the Groq model you want to use.
   See Groq's models overview for info on the available models.
   Example:
   ini Copy

   SMART_LLM=llama3-70b-8192

Llamafile Copy Section

With llamafile you can run models locally, which means no need to set up billing,
and guaranteed data privacy.

For more information and in-depth documentation, check out the llamafile documentation.

!!! warning
At the moment, llamafile only serves one model at a time. This means you can not
set SMART_LLM and FAST_LLM to two different llamafile models.

!!! warning
Due to the issues linked below, llamafiles don't work on WSL. To use a llamafile
with AutoGPT in WSL, you will have to run the llamafile in Windows (outside WSL).

Instructions

1. Get the `llamafile/serve.py` script through one of these two ways:
    1. Clone the AutoGPT repo somewhere in your Windows environment,
       with the script located at `classic/original_autogpt/scripts/llamafile/serve.py`
    2. Download just the [serve.py] script somewhere in your Windows environment
2. Make sure you have `click` installed: `pip install click`
3. Run `ip route | grep default | awk '{print $3}'` *inside WSL* to get the address
   of the WSL host machine
4. Run `python3 serve.py --host {WSL_HOST_ADDR}`, where `{WSL_HOST_ADDR}`
   is the address you found at step 3.
   If port 8080 is taken, also specify a different port using `--port {PORT}`.
5. In WSL, set `LLAMAFILE_API_BASE=http://{WSL_HOST_ADDR}:8080/v1` in your `.env`.
6. Follow the rest of the regular instructions below.

[serve.py]: https://github.com/Significant-Gravitas/AutoGPT/blob/master/classic/original_autogpt/scripts/llamafile/serve.py


* [Mozilla-Ocho/llamafile#356](https://github.com/Mozilla-Ocho/llamafile/issues/356)
* [Mozilla-Ocho/llamafile#100](https://github.com/Mozilla-Ocho/llamafile/issues/100)

!!! note
These instructions will download and use mistral-7b-instruct-v0.2.Q5_K_M.llamafile.
mistral-7b-instruct-v0.2 is currently the only tested and supported model.
If you want to try other models, you'll have to add them to LlamafileModelName in
llamafile.py.
For optimal results, you may also have to add some logic to adapt the message format,
like LlamafileProvider._adapt_chat_messages_for_mistral_instruct(..) does.

1. Run the llamafile serve script:

   shell Copy

   python3 ./scripts/llamafile/serve.py

   The first time this is run, it will download a file containing the model + runtime,
   which may take a while and a few gigabytes of disk space.

   To force GPU acceleration, add --use-gpu to the command.

2. In .env, set SMART_LLM/FAST_LLM or both to mistral-7b-instruct-v0.2

3. If the server is running on different address than http://localhost:8080/v1,
   set LLAMAFILE_API_BASE in .env to the right base URL

AGENTS (`docs/AGENTS.md`) Copy Section

Documentation Guidelines

Where a Document Goes Copy Chapter

• Published pages live in docs/home/, docs/platform/ and docs/integrations/. GitBook publishes them at agpt.co/docs, and a page appears on the site once that folder's SUMMARY.md lists it. Put a page there only if it is written for people outside the team: people using, self-hosting or contributing to AutoGPT.
• Engineering notes live in docs/engineering/: the team's working documents, such as analytics and tracking plans, rollout plans, runbooks, internal references, and design and architecture notes. They are not on the docs site. Don't list one in a SUMMARY.md.

docs/engineering/ is not private. The repository is public and AutoPilot's documentation search indexes the folder, so keep secrets and confidential material out of it, as with any file in the repository.

When unsure, write the document in docs/engineering/. Listing a page in a SUMMARY.md publishes it, so do that only for a page meant for the site.

The site follows master. .github/workflows/docs-gitbook-sync.yml copies master's docs/ to the gitbook branch, and GitBook publishes that branch. Change docs through a pull request to dev. Never commit to gitbook, open a pull request against it, or edit pages in GitBook: the next copy overwrites anything that isn't on master.

Every Markdown page under docs/platform/ must be listed in docs/platform/SUMMARY.md: every .md file other than SUMMARY.md itself and GitBook's own files under a .gitbook/ directory. A SUMMARY.md may list only pages inside its own folder. .github/workflows/scripts/test_docs_layout.py checks those two things on every pull request. It cannot tell whether a listed page is meant for the public; that is for the author and the reviewer to judge.

Block Documentation Manual Sections Copy Chapter

When updating manual sections (``) in block documentation files (e.g., docs/integrations/basic.md), follow these formats:

How It Works Section Copy Section

Provide a technical explanation of how the block functions:

• Describe the processing logic in 1-2 paragraphs
• Mention any validation, error handling, or edge cases
• Use code examples with backticks when helpful (e.g., [[1, 2], [3, 4]] becomes [1, 2, 3, 4])

Example:

The block iterates through each list in the input and extends a result list with all elements from each one. It processes lists in order, so `[[1, 2], [3, 4]]` becomes `[1, 2, 3, 4]`.

The block includes validation to ensure each item is actually a list. If a non-list value is encountered, the block outputs an error message instead of proceeding.

Use Case Section Copy Section

Provide 3 practical use cases in this format:

• Bold Heading: Short one-sentence description

Example:

**Paginated API Merging**: Combine results from multiple API pages into a single list for batch processing or display.

**Parallel Task Aggregation**: Merge outputs from parallel workflow branches that each produce a list of results.

**Multi-Source Data Collection**: Combine data collected from different sources (like multiple RSS feeds or API endpoints) into one unified list.

Style Guidelines Copy Section

• Keep descriptions concise and action-oriented
• Focus on practical, real-world scenarios
• Use consistent terminology with other blocks
• Avoid overly technical jargon unless necessary

Engineering Activation Metrics (`docs/engineering/activation-metrics.md`) Copy Section

Activation Metrics & Experiments

How the platform measures activation, retention and unit economics across
every surface (classic agents, Autopilot, experts, schedules), and how to run
an A/B/C experiment whose results can be sliced in both PostHog and Looker.

This page is the contract between engineering and go-to-market: the event
names, the SQL views and the definitions below are the ones dashboards should
be built on. Change a definition here and in every view that repeats it: the
task predicate is spelled out in user_task_daily, user_lifecycle,
retention_task_weekly and unit_economics_monthly until a shared base view
exists, so a change to one must be made in all four.

Where each tool fits Copy Chapter

Definitions Copy Chapter

• Task: a unit of work a person asked for now. Either a human-started
  agent run (triggerSource in manual, api) or a human chat turn (a
  user message in an Autopilot or expert session whose origin is not
  automation). A run the copilot tool started (triggerSource = copilot)
  is counted once, through the chat turn that asked for it. Dry runs, nested
  sub-graph runs and dream/memory sessions are never tasks.
• Automated task: a schedule fire, a webhook trigger, or a scheduled
  follow-up turn. Counted separately so "people doing things" and "agents
  running" can be compared.
• Activated: at least 3 tasks on at least 2 distinct days within 14 days
  of signup. (analytics.user_lifecycle.activated)
• Last active: latest of last task, last visit, last scheduled run,
  falling back to signup. Because a scheduled run counts, an account whose
  schedule fires daily is never stale_* or churned_30d while it keeps
  firing; retention_task_weekly deliberately ignores schedules and measures
  people coming back. Use the one that matches the question.
• Login / visit: a session row, from auth.sessions (Supabase, history
  up to the Better Auth cutover on 2026-07-30) or platform.UserAuthSession
  (Better Auth, everything since). Every login column reads both.
• Stale: no activity in 14 / 30 days (stale_14d, stale_30d).
• Churned (30d): had at least one task ever, signed up more than 30 days
  ago, no activity in the last 30 days.
• Never activated (30d): signed up more than 30 days ago and never did a task.
• Cost to us: PlatformCostLog.costMicrodollars, our real provider spend,
  split into agent (block runs), copilot (turns) and background (dream passes).
• Credits charged: CreditTransaction USAGE rows, in cents. A run
  billed to an organisation writes OrgCreditTransaction instead; the credit
  columns in user_task_daily, user_lifecycle and unit_economics_monthly
  include those rows under the user who initiated them (initiatedByUserId),
  while cost stays with the acting user, so per-user margin stays comparable
  for org members.

Activation events (PostHog) Copy Chapter

Emitted server-side by backend/util/product_analytics.py with
distinct_id = user id, so they join the frontend's posthog.identify.
Every event carries environment and source: "platform".

credential_oauth_started, integration_connected (method: oauth) and
credential_oauth_exchange_failed give started / connected / failed per
provider. They are sent by the backend so they are not held back by the
browser's analytics consent. failure_class says where the callback failed:

An unexpected error (not an HTTP error we raise, e.g. a database error) keeps
the class of the step it happened in, with only the exception class as
detail and no status_code: the app's exception handlers pick the response
status later (ValueError is a 400, for example).

A granted scope set narrower than the one requested is not a callback
failure: the credential is stored and integration_connected fires.

The event names follow the product analytics plan; the chat events
(chat_tool_called, chat_outcome, ...) and billing events (topup_completed,
trial_*, subscription_*, ...) are listed there too. Every PostHog event, its sender, its properties and whether it is live,
planned or removed is listed in the PostHog Tracking Plan.

SQL views (Looker) Copy Chapter

New or extended in this change. Existing views (retention_login_*,
retention_execution_*, users_activities, platform_cost_log, ...) are
untouched.

Apply them to a database with:

cd autogpt_platform/backend
poetry run analytics-views

Then add each new view as a data source in Looker Studio (the header of every
.sql file documents its columns and example queries). triggerSource is
NULL on runs created before September 2026; the views expose those as
agent_runs_untagged and count them as human tasks.

One identity across LaunchDarkly, PostHog and the database Copy Chapter

The two tools used to disagree about who a visitor is. LaunchDarkly only
knew a user after login (every logged-out visitor shared the literal key
anonymous, so it could not bucket pre-signup at all), while PostHog minted
its own anonymous id and merged it into the user id at identify. Nothing
tied a pre-signup arm to a post-signup person, and nothing tied either to
the DataFast visitor that marketing sees.

Now the frontend owns one first-party anonymous id
(src/services/analytics/anonymous-id.ts, stored in localStorage, adopting
an existing PostHog device id when there is one) and hands it to everything:

• PostHog is bootstrapped with it as the anonymous distinct id, so
  identify(user.id) merges it into the person as usual.
• LaunchDarkly gets it as the anonymous user key before login, and as
  a device context alongside the user context after login. Rules on the
  user kind are unchanged; a rule that buckets by device keeps the same
  arm across signup.
• The database stores it on the user at first login (UserAttribution,
  reported by the browser to POST /api/analytics/attribution) together
  with the PostHog device id, the DataFast visitor and session ids (from the
  request headers the frontend already sends), the first landing page, UTM
  tags and the signup method. analytics.user_attribution exposes it.

Rule of thumb: LaunchDarkly gates, PostHog measures, the database joins.
Server-side flag evaluation stays keyed by user id (the backend has no
device context yet), so bucket pre-login experiments on the client.

Running an experiment Copy Chapter

1. Create a multivariate feature flag in PostHog with the arm keys you want
   (control, variant-a, variant-b, ...) and make it an experiment there.
2. In the frontend, read it through useExperiment(key) from
   src/services/experiments/useExperiment.ts. It returns { variant, isResolved }:
   render the control experience until isResolved, and do not fire one-shot
   side effects before then, or a late variant is mis-recorded as control.
   The hook reports the arm to POST /api/experiments/assignments once per
   user and experiment; the backend keeps the first arm it sees.
3. Backend-decided experiments can call
   backend.data.experiments.record_assignment(user_id, key, variant, source="backend").
4. Read results in PostHog (exposure + the activation events above as goals),
   and in Looker by joining analytics.experiment_assignment to
   user_lifecycle, user_task_daily or unit_economics_monthly.

The onboarding paywall experiment (subscription-pricing-page-initial-state)
is already wired this way.

Deploying this change Copy Chapter

1. Run the migrations 20260902120000_add_execution_trigger_source (adds
   AgentGraphExecution.triggerSource / triggerRef),
   20260902120100_add_experiment_assignment (the ExperimentAssignment
   table) and 20260902120200_add_user_attribution (the UserAttribution
   table). Existing analytics.* views are unaffected: no column they select
   from changes type.
2. Deploy the backend. From that moment every run row carries its trigger and
   every activation event flows to PostHog.
3. Nick Tindle runs poetry run analytics-views against production right
   after the deploy that carries this change, before any Looker source is
   added. Before that, on staging: EXPLAIN (ANALYZE, BUFFERS) on
   user_lifecycle, user_lifecycle_funnel_weekly, experiment_assignment
   and user_attribution. user_lifecycle has no date bound (it is a
   per-user lifetime table), so every refresh aggregates the full history of
   AgentGraphExecution, ChatMessage, PlatformCostLog and
   CreditTransaction; if staging shows that hurting, the follow-up is a
   nightly-refreshed materialized view (a generate_views.py change), not a
   Looker source on the live view. Then wire the new views into Looker Studio.
4. Confirm in PostHog that agent_run_started, chat_message_sent,
   schedule_created and agent_run_finished are arriving with
   source = platform.

The questions GTM will ask next Copy Chapter

The list GTM gave us is the first layer. These are the questions that follow
once they see the data, with where the answer already lives or what is still
missing.

Activation

• Which first action predicts retention: an agent run, an Autopilot chat, an
  expert, or a schedule? — user_lifecycle has the first-time timestamps
  and early counts per surface; group by the earliest one and compare
  churned_30d.
• How long from signup to first task, and where do people stall? —
  hours_to_first_task plus the onboarding funnel view; combine with PostHog
  session replay on users with never_activated_30d.
• Does connecting an integration change activation? —
  integrations_connected_total and first_integration_connected_at in
  user_lifecycle (from IntegrationCredential), connected_integration in
  the funnel, and the integration_connected event in PostHog.
• Which marketing channel brings activated users? — join
  user_attribution (UTM tags, referrer, landing page, DataFast visitor id)
  to user_lifecycle. For channels only DataFast knows, export DataFast by
  visitor id and join on datafast_visitor_id.

Retention and churn

• Are we retaining people, or just their schedules? — retention_task_weekly
  (people) next to retention_execution_weekly (all runs incl. automated).
• Which early behaviours separate churned from retained users? — the
  example query on user_lifecycle; the next step is a proper model, which
  needs the same table exported to a notebook.
• Who is about to churn? — stale_14d users with tasks_28d dropping vs
  their prior 28 days; agent_health.idle_7d and failing are the earliest
  per-agent signals. Gap: a weekly "at-risk" list is a view away, but
  acting on it (email, in-product nudge) needs the alerts pipeline.
• Do failures cause churn? — agent_runs_failed_total and
  agent_runs_no_credits_total in user_lifecycle; failure_reason in
  graph_execution. Insufficient balance is already separated because it is
  a pricing problem, not a product problem.

Cost and pricing

• What will a free trial with card on file cost us? —
  unit_economics_monthly by tier and by month-of-life; the
  PERCENTILE_CONT example shows the tail, which is what a trial cap must
  cover.
• Cost per task by surface and model? — split exists by surface in
  user_task_daily; per-model cost is in platform_cost_log. Gap: chat
  turns are not linked to the exact cost rows (copilot cost rows carry the
  session id in graphExecId), so cost per turn is an average, not exact.
• Gross margin per user and per tier? — gross_margin_usd in
  unit_economics_monthly, with the caveat that credits are prepaid.
• How much do we spend on users who never come back? — join
  unit_economics_monthly to user_lifecycle.churned_30d.
• Background cost (dream/memory passes) as a share of total? —
  background_cost_usd in user_task_daily and unit_economics_monthly.

Experiments

• Did the pricing-page arm change activation or retention, not just
  conversion? — experiment_assignment joined to user_lifecycle.
• Can we A/B backend behaviour (model routing, default expert, prompt)? —
  yes via record_assignment(source="backend"); LaunchDarkly stays the
  gate, PostHog and the assignment table hold the arm.
• Can the team keep using LaunchDarkly for arms? — not in the browser
  today: the unused useLaunchDarklyExperiment bridge and its
  experiment_exposed event were removed (SECRT-2722), so a LaunchDarkly arm
  reaches the assignment table only through record_assignment. Gap: the
  backend's LaunchDarkly context has no device kind yet, so server-evaluated
  flags cannot bucket by the anonymous id.

Experts and schedules

• Do hired experts get used after day one? — expert_turns_total,
  expert_workflow_runs_total, experts_active in user_lifecycle;
  expert_hired event in PostHog for the funnel.
• How many schedules are created and then silently stop? — creations are in
  ActivityEvent, fires are in graph_execution.triggerSource = 'schedule'.
  Gap: schedules live only in the APScheduler job store, so there is no
  durable schedule row to join pauses and deletions to; a Schedule table
  would make schedule health first-class.

Operational gaps to close next

• No lastActiveAt on User; user_lifecycle derives it, which is fine for
  dashboards but not for real-time gating.
• Frontend PostHog is not bootstrapped with flags, so experiment variants
  resolve after first paint. useExperiment.isResolved papers over this;
  server-side bootstrap would remove the delay.
• DataFast goals fire only after analytics consent, so they undercount
  relative to the server-side events. Use the server-side numbers as truth
  and DataFast for channel attribution only.

Engineering Codex Subscription Preview (`docs/engineering/codex-subscription-preview.md`) Copy Section

ChatGPT/Codex subscription transport preview

This private preview lets a user connect a ChatGPT account and use that
account's Codex allowance for three explicit execution paths:

• The existing Code Generation block through the codex_app_server
  transport.
• A newly created AutoPilot chat session when ChatGPT/Codex is the only
  connected subscription transport, or is selected from multiple connected
  subscription transports.
• An AutoPilot graph block with an explicitly selected ChatGPT/Codex
  connection.

codex is the credential provider and Codex App Server is the execution
runtime. A ChatGPT plan is not unlimited inference: these calls consume the
connected account's Codex allowance or credits and remain subject to its rate
limits. Subscription-backed usage records tokens and
billing_mode=user_subscription; it is not reported as AutoGPT provider USD
spend.

The preview does not route Orchestrator, shared LLM blocks, image generation,
or background system work through the connected account. Existing graphs and
AutoPilot sessions keep their stored route. New AutoPilot sessions use a
connected subscription transport automatically when exactly one is available.

Run locally Copy Chapter

From autogpt_platform:

docker compose up -d --build

Codex pairing and its supported execution routes are available without feature
flag environment variables. The stack mounts /run/autogpt-codex as a
memory-backed temporary filesystem for REST, executor, and Copilot executor
processes.

Open http://localhost:3000, then open Settings > Integrations, choose
OpenAI, select ChatGPT, and click Sign in with ChatGPT. In the sign-in
window, open the ChatGPT verification page and enter the one-time code.

Test the Code Generation block Copy Section

1. Add a Code Generation block to a graph.
2. Set Transport to Codex App Server.
3. Select the connected ChatGPT for Codex credential.
4. Run the graph.

Existing graphs continue to default to the OpenAI API transport. The block's
model dropdown applies to that API transport. The subscription transport uses
App Server's current account-compatible default; its live catalog can change
independently of public API model names.

Test AutoPilot Copy Section

1. Open AutoPilot and start a new task.
2. If ChatGPT/Codex is the only connected subscription transport, it is used
   automatically and no connection selector is shown. If multiple subscription
   transports are connected, choose the desired connection before sending the
   first message.
3. Choose Balanced or Advanced as available, then send the message. Text and
   permitted AutoGPT tool calls stream through the existing AutoPilot event
   surface.

The route and credential are stored on the new session and are immutable for
that session. Start another task to use a different connected subscription
transport. The server reloads the authoritative session route before each
queued turn; queued messages carry only the credential ID, never the OAuth
tokens. A missing, revoked, or busy Codex credential fails visibly. There is no
silent fallback to an AutoGPT-funded model or another user's credential.

The visible model tier and the server-selected execution path select a Codex
route from the shared model catalog, then validate it against the models
advertised by the connected account.

If the account does not expose the mapped model, the transport uses the visible
account default. File attachments, agent-building tools, and SDK sub-sessions
use the same Claude Agent SDK path as platform-funded AutoPilot.
Builder-panel-bound sessions remain platform-funded in this preview because
their persistent session is created without an AI connection selector.

The Copilot executor keeps one exclusive credential lease and one Codex runtime
per connected account, then multiplexes overlapping chats onto separate Codex
threads. Canceling or finishing one chat does not stop its siblings. This pool
is process-local: a request routed to another executor process or replica cannot
join the owner yet and still fails with the bounded, retryable
codex_credential_busy error. A hosted multi-replica rollout therefore needs
credential-owner routing or a dedicated bridge. The normal platform AutoPilot
route is unchanged.

Test the AutoPilot graph block Copy Section

1. Add an AutoPilot block to a graph.
2. Select the saved connection under ChatGPT / Codex connection.
3. Run the graph.

The credential field is a reference-only credential input: graph validation
checks ownership and export strips the credential ID, while the graph executor
does not hold the outer credential lease. The Copilot executor acquires the
single runtime lease when it consumes the queued turn. This preserves normal
credential rebinding without deadlocking the nested execution path. Leaving the
field empty preserves the existing platform-funded behavior.

Claude Agent SDK transport Copy Chapter

AutoPilot keeps the existing Claude Agent SDK and Claude Code CLI as its agent
harness. A request-scoped loopback Anthropic Messages endpoint translates model
rounds to the pinned Codex App Server's experimental dynamicTools protocol.
Claude Code still owns the MCP tool loop, permission hooks, builder behavior,
transcript, resume, compaction, and sub-session machinery. Codex supplies the
model response using the selected user's ChatGPT/Codex credential.

The loopback endpoint is bound to 127.0.0.1 on an ephemeral port and accepts
only a random capability generated for that turn. The capability is placed in
the Claude CLI child environment; ChatGPT access, refresh, and ID tokens are
never placed there. Anthropic text and tool-use events are mapped to the same
Claude SDK response adapter used by normal AutoPilot.

The App Server process itself is fail-closed: native shell, filesystem, web
search, apps, plugins, environments, workspace roots, and approval requests are
disabled, and its sandbox is read-only. Any side effect comes only through a
tool that Claude Code was already permitted to invoke through AutoGPT's MCP and
security hooks.

ChatGPT is reached over HTTPS: sign-in, refresh, the model catalog and
inference all run against auth.openai.com and chatgpt.com, so no Codex
binary ships in the image and there is no version to pin. The Claude Agent SDK
and its CLI are still pinned by the backend lock. Because the compatibility
surface is version-sensitive, updates require the focused protocol and Messages
conformance tests to pass before rollout.

Verify an existing local login Copy Chapter

To test an existing local Codex login before starting the stack, run this from
autogpt_platform/backend:

poetry run python -m scripts.codex_preview_smoke

The smoke test reads ~/.codex/auth.json without writing to it, checks the
account and model catalog, and performs one subscription-backed turn with a tool
call over HTTPS -- failing if the model never calls the tool or returns no text.
It reports the quota the turn's response headers carried. It does consume a
small amount of the connected account's usage.

Deploy a private cloud preview Copy Chapter

Codex pairing and supported execution routes do not require availability flags
or frontend build-time overrides. Scope a private preview with the deployment's
ordinary access controls instead of hiding device login with environment
variables. The transport selector is driven by the connected, compatible
subscription providers: it is hidden for zero or one and shown when more than
one is available.

REST, executor, and Copilot executor must share the normal AutoGPT credential
database, encryption configuration, and Redis cluster. Give every process that
may launch App Server an isolated, memory-backed CODEX_TEMP_ROOT; never mount
it on a persistent volume.

Set FRONTEND_BASE_URL, NEXT_PUBLIC_FRONTEND_BASE_URL, and BETTER_AUTH_URL
to the exact public origin of the preview, including its https:// scheme and
without a path. REST deliberately builds the device-login URL from this
configured origin instead of trusting forwarded host headers. Leaving a
production or localhost origin in a cloud preview sends the popup to a host
that does not have the preview's Better Auth cookie.

NEXT_PUBLIC_FRONTEND_BASE_URL is compiled into the frontend bundle. Pass it as
a frontend image build argument, then set BETTER_AUTH_URL on the frontend at
runtime and FRONTEND_BASE_URL on REST at runtime. The development Compose file
forwards all three exported values and keeps http://localhost:3000 as their
local default.

Device-login status and ownership are Redis-backed, so polling and cancellation
can reach different REST replicas. The active App Server login actor is still
process-local, however: an owner-pod restart interrupts the login and another
replica cannot take it over or resume it. Keep rolling deploys away from active
sign-ins and ask the user to restart an interrupted login. Broad cloud rollout
requires moving the login actor into the dedicated bridge described below.

The containers need outbound HTTPS access to OpenAI's ChatGPT/Codex endpoints.
No callback ingress from OpenAI is required because Codex App Server polls for
device-code completion.

Preview safety boundary Copy Chapter

• The encrypted, USER-scoped IntegrationCredential row remains the source of
  truth.
• Raw ChatGPT tokens do not enter Redis, RabbitMQ, frontend responses,
  container-wide environment variables, or AutoPilot session records.
• Tokens are held in memory for the life of a turn and never written to disk:
  there is no on-disk auth home, because there is no process to hand one to.
  A client is built per turn and never cached, so one user's subscription can
  never serve another's request. Refresh is owned by the credentials manager
  and serialized behind its Redis mutex, since OpenAI rotates the refresh token
  on every exchange.
• Code Generation turns expose no dynamic tools or host workspace. AutoPilot
  exposes only the tools registered by its existing Claude SDK/MCP harness.
• Runtime reuse is scoped to the exact user and credential. Credentials are
  never pooled across users or substituted for another account.
• There is no silent platform-key fallback.

The current implementation launches Codex App Server in-process from the
ordinary REST, executor, and Copilot executor containers. Those containers
currently run as root and retain the backend services' broader database, Redis,
filesystem, and network privileges. The temporary-home and fail-closed thread
configuration reduce exposure, but they do not make this a safe boundary for a
broad external cloud rollout.

Treat the current shape as local development or a tightly access-controlled
staff/private preview only. Before enabling external users, move runtime and
device-login supervision into a dedicated unprivileged bridge with a non-root
user, read-only root filesystem, dropped capabilities, memory-only credential
homes, process and concurrency limits, narrowly restricted egress, and a
least-privilege internal credential lease interface. The bridge must also own
login actor takeover or explicit restart semantics. Complete the commercial
and policy review for hosted subscription passthrough before broader rollout.

Engineering Feature Flags (`docs/engineering/feature-flags.md`) Copy Section

Feature flags

Which vendor answers a flag read is set per deployment by FEATURE_FLAG_BACKEND:
launchdarkly (the default), posthog, or dual — evaluate both, serve
LaunchDarkly's answer, and log every disagreement. Call sites are unaffected by
the choice; they read through evaluate_feature_flag() on the backend and
useGetFlag / useFlagStatus on the frontend.

One PostHog project per environment Copy Chapter

Dev and Prod each have their own PostHog project, and each project holds its
own flags. A deployment reads its flags from the same project its analytics go
to, the one POSTHOG_API_KEY names, and evaluates them locally with that
project's Feature Flags Secure API Key in POSTHOG_SECRET_KEY. Where local
evaluation can't decide a read, the SDK asks PostHog's /flags endpoint
instead, unless the read is local-only, as a signed-out visitor's own read is.

PostHog has no environments within a project, so a flag both deployments read
is defined in each project. The Projects tab on the
flag list
and on each flag's page shows a flag across both projects side by side.

Until Prod switches to PostHog, Prod serves LaunchDarkly's answers
(FEATURE_FLAG_BACKEND=dual only compares PostHog's against them), so a change
to a Prod flag is made in LaunchDarkly and mirrored in the Prod PostHog project.

The browser. With NEXT_PUBLIC_FEATURE_FLAG_BACKEND=server the browser
gets its flags from the backend's GET /api/feature-flags, which evaluates
them through the same path as the backend's own reads, so the browser and the
backend give one answer from one project. A Vercel preview in server mode
gets the answer of the backend it calls. The other values read flags in the
browser itself: launchdarkly (the default) from LaunchDarkly, and posthog /
dual from the project NEXT_PUBLIC_POSTHOG_KEY names. useExperiment reads
posthog-js in every mode.

The environment property. Every PostHog flag read the backend makes, its
own and the browser's in server mode, carries the person property
environment: the backend's APP_ENV (local, dev or prod), the same
value its analytics events carry. A release condition can use it in either
project like any other person property. It is only an evaluation input, never
stored on a person. Browser reads through posthog-js (posthog / dual mode)
don't carry it: they send buildFlagPersonProperties (email, email domain,
role, created at) only, so a condition on environment matches only the
backend's reads there.

Splitting signed-out visitors. A visitor who allowed analytics is bucketed
under visitor:, but only by conditions their read can
decide: a rollout percentage, environment and is_anonymous, with no email.
A condition group on another person property or a cohort (the migrated
"email in employees", for one) can't be decided for a visitor, so a visitor
whom no decidable group matches gets the shared signed-out answer instead.
"Employees OR 20%" is then all or nothing for visitors, whichever side the
shared anonymous key lands on. For a real 20% of visitors, add
is_anonymous is not true to the rollout group: the shared answer is then
off, and only each visitor's own bucket turns the flag on.

Sharing PostHog's flag definitions Copy Chapter

PostHog evaluates flags locally, in the process, from a set of flag definitions
it polls for every 30 seconds. PostHog
bills one definitions fetch as ten flag requests,
so a poller in every process makes that bill scale with replica count: at two
polls a minute, each process costs 28,800 flag requests a day whether or not it
reads a single flag.

So one process is elected to refresh the definitions and write them to Redis,
and every other process evaluates from that shared copy. The fleet then costs
one process's worth of polling — 28,800 flag requests a day in total, instead of
28,800 per replica.

This is PostHog's own FlagDefinitionCacheProvider interface; the SDK calls it
from its polling thread, never from a flag read, so no request can block on
Redis.

Settings Copy Section

None of them is read unless FEATURE_FLAG_BACKEND is posthog or dual and
POSTHOG_SECRET_KEY is set — without that key the SDK evaluates over the
wire and has no definitions to share.

Per environment. Leave the defaults on dev and prod: both run several
replicas against a shared Redis, which is what the cache is for. Local
development and CI run FEATURE_FLAG_BACKEND=launchdarkly, so none of this is
reached; set POSTHOG_FLAG_DEFINITION_CACHE=memory if you want to exercise
PostHog locally without Redis.

What the refresher is Copy Section

Every process tries SET <key> NX PX on one Redis key each time it polls.
The one that gets it fetches the definitions from PostHog and writes them to
Redis; the others read that copy. The winner renews its own lock on every poll,
so it keeps the job. The lock expires two poll intervals after its last renewal,
and the next process to poll takes it, so a refresher that dies is replaced
within 90 seconds at the defaults. One shutting down cleanly releases the lock
immediately, and is replaced on the next poll.

Telling it is working Copy Section

One process logs, once, when it takes the job:

This process now refreshes the shared PostHog flag definitions (<host>:<pid>:<id>)

and the others log Another process now refreshes the shared PostHog flag definitions when they lose it.

The counter autogpt_posthog_flag_definition_cache_events_total on /metrics
carries the same story, by outcome:

Healthy, with N replicas: stored increments once per poll on exactly one
process, cached once per poll on each of the other N−1, and empty and
error stay flat.

Failure modes Copy Section

Nothing here can make a flag read wait on Redis: evaluation reads the
definitions already in the process, and only a read they can't decide waits on
PostHog's /flags.

Engineering Hosted Mcp Catalog (`docs/engineering/hosted-mcp-catalog.md`) Copy Section

Maintaining MCP Integrations

mcp_catalog.json defines the official services shown in Integrations and the AutoPilot MCP guide. mcp_catalog.py validates the records and exposes them through get_mcp_catalog().

Add or update a service Copy Chapter

• Keep a stable mcp_... ID and link directly to the vendor's setup documentation.
• Describe the server's purpose and required plan, admin approval, region, endpoint, and credentials in description and setup_instructions.
• Choose the connection setup that matches the vendor's server; see Choose how users connect.
• Order the supported auth_methods by preference; the first method is selected initially. Choices are oauth, bearer, basic, and none.
• Set oauth_server_url when the vendor supplies a separate signed-in endpoint.
• Set documented oauth_scopes for the initial grant and separate oauth_write_scopes for the optional Allow changes choice. An empty default list omits the scope parameter; omission/null uses discovery defaults.

Choose how users connect Copy Chapter

Match the entry to where the vendor runs its MCP server. Every URL must be a public HTTPS URL.

• One public URL for every customer: use connection_mode: hosted with server_url. The connect dialog shows the URL locked, and AutoPilot uses it. Examples: PostHog, Notion.
• One public URL, and the service can also be self-hosted: use hosted with server_url and allow_custom_url: true. The dialog opens on server_url, and users can replace it with their own instance's URL. AutoPilot still uses server_url. Say in setup_instructions how to connect a self-hosted instance, including any sign-in setup it needs. Example: OpenSEO.
• A separate URL per region: use connection_mode: custom with one server_url_options entry per region and no server_url. Users pick their region, and the picker's Custom URL option covers self-hosted instances. Prefer this to one entry per region. Don't make it a hosted entry that defaults to one region, because users in the other regions would connect to the wrong one. Examples: Amplitude, Langfuse.
• A URL unique to each customer account: use connection_mode: custom with no server_url and no options. Say in setup_instructions where users find their URL. The dialog opens with an empty URL field. Examples: Chargebee, Sourcegraph.

Both custom setups show Setup required in the integrations list. AutoPilot tells users to add their URL under Settings → Integrations before it can use the server.

Validate the change Copy Chapter

Check the vendor's current endpoint and authentication contract. Verify initialization and tool listing with the MCP client, then a benign read using the intended permissions. For OAuth, check registration, consent, and refresh with the deployment's callback and an authorized test account.

Update affected catalog, provider, guide, and page integration tests. Cover changes to region selection, custom URLs, token handling, or optional grants. Regenerate API types when the metadata schema changes, and run the relevant backend and frontend checks.

Engineering Oauth Integration Flow (`docs/engineering/oauth-integration-flow.md`) Copy Section

OAuth Integration Flow Documentation

Overview Copy Chapter

The AutoGPT platform implements OAuth 2.0 in two distinct contexts:

1. User Authentication (SSO): Handled by Better Auth, embedded in the Next.js frontend at /api/auth/*
2. API Integration Credentials: Custom OAuth implementation for third-party service access

This document focuses on the API Integration OAuth flow used for connecting to external services. For the list of supported providers, see autogpt_platform/backend/backend/integrations/providers.py. For user authentication documentation, see autogpt_platform/frontend/src/lib/auth/SESSION_VALIDATION.md.

Trust Boundaries Copy Chapter

1. Frontend Trust Boundary Copy Section

• Location: Browser/Client-side application
• Components:
  • CredentialsInput component (autogpt_platform/frontend/src/components/contextual/CredentialsInput/CredentialsInput.tsx)
  • OAuth callback route (autogpt_platform/frontend/src/app/(platform)/auth/integrations/oauth_callback/route.ts)
• Trust Level: Untrusted - user-controlled environment
• Security Measures:
  • CSRF protection via state tokens
  • Popup-based flow to prevent URL exposure
  • Message validation for cross-window communication

2. Backend API Trust Boundary Copy Section

• Location: Server-side FastAPI application
• Components:
  • Integration router (autogpt_platform/backend/backend/api/features/integrations/router.py)
  • OAuth handlers (autogpt_platform/backend/backend/integrations/oauth/)
  • Credentials store (autogpt_platform/backend/backend/integrations/credentials_store.py)
• Trust Level: Trusted - server-controlled environment
• Security Measures:
  • JWT-based authentication
  • Encrypted credential storage
  • Token refresh handling
  • Scope validation

3. External Provider Trust Boundary Copy Section

• Location: Third-party OAuth providers
• Components: Provider authorization endpoints
• Trust Level: Semi-trusted - external services
• Security Measures:
  • HTTPS-only communication
  • Provider-specific security features
  • Token revocation support

Component Architecture Copy Chapter

Frontend Components Copy Section

1. CredentialsInput Component

• Purpose: UI component for credential selection and OAuth initiation
• Key Functions:
  • Displays available credentials
  • Initiates OAuth flow via popup window
  • Handles OAuth callback messages
  • Manages credential selection state

2. OAuth Callback Route

• Path: /auth/integrations/oauth_callback
• Purpose: Receives OAuth authorization codes from providers
• Flow:
  1. Receives code and state parameters from provider
  2. Posts message to parent window with results
  3. Auto-closes popup window

Backend Components Copy Section

1. Integration Router

• Base Path: /api/integrations
• Key Endpoints:
  • GET /{provider}/login - Initiates OAuth flow
  • POST /{provider}/callback - Exchanges auth code for tokens
  • GET /credentials - Lists user credentials
  • DELETE /{provider}/credentials/{id} - Revokes credentials

2. OAuth Base Handler

• Purpose: Abstract base class for provider-specific OAuth implementations
• Key Methods:
  • get_login_url() - Constructs provider authorization URL
  • exchange_code_for_tokens() - Exchanges auth code for access tokens
  • refresh_tokens() - Refreshes expired access tokens
  • revoke_tokens() - Revokes tokens at provider

3. Credentials Store

• Purpose: Manages credential persistence and state
• Key Features:
  • Redis-backed mutex for concurrent access control
  • OAuth state token generation and validation
  • PKCE support with code challenge generation
  • Default system credentials injection

OAuth Flow Sequence Copy Chapter

1. Flow Initiation Copy Section

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    participant Redis
    participant Provider

    User->>Frontend: Click "Sign in with Provider"
    Frontend->>Backend: GET /api/integrations/{provider}/login
    Backend->>Redis: Store state token + code verifier
    Backend->>Frontend: Return login URL + state token
    Frontend->>Frontend: Open popup window
    Frontend->>Provider: Redirect to authorization URL

2. Authorization Copy Section

sequenceDiagram
    participant User
    participant Provider
    participant Callback
    participant Frontend
    participant Backend

    User->>Provider: Authorize application
    Provider->>Callback: Redirect with code + state
    Callback->>Frontend: PostMessage with code + state
    Frontend->>Backend: POST /api/integrations/{provider}/callback
    Backend->>Provider: Exchange code for tokens
    Provider->>Backend: Return access + refresh tokens
    Backend->>Backend: Store credentials
    Backend->>Frontend: Return credential metadata

3. Token Refresh Copy Section

sequenceDiagram
    participant Application
    participant Backend
    participant Provider

    Application->>Backend: Request with credential ID
    Backend->>Backend: Check token expiry
    Backend->>Provider: POST refresh token
    Provider->>Backend: Return new tokens
    Backend->>Backend: Update stored credentials
    Backend->>Application: Return valid access token

System Architecture Diagram Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Data Flow Diagram Copy Chapter

graph LR
    subgraph "Data Types"
        ST[State Token]
        CV[Code Verifier]
        CC[Code Challenge]
        AC[Auth Code]
        AT[Access Token]
        RT[Refresh Token]
    end
    
    subgraph "Frontend Flow"
        U1[User Initiates]
        U2[Receives State]
        U3[Opens Popup]
        U4[Receives Code]
        U5[Sends to Backend]
    end
    
    subgraph "Backend Flow"
        B1[Generate State]
        B2[Store in Redis]
        B3[Validate State]
        B4[Exchange Code]
        B5[Store Credentials]
    end
    
    U1 --> B1
    B1 --> ST
    B1 --> CV
    CV --> CC
    B2 --> U2
    U3 --> AC
    AC --> U4
    U5 --> B3
    B3 --> B4
    B4 --> AT
    B4 --> RT
    AT --> B5
    RT --> B5

Security Architecture Copy Chapter

graph TB
    subgraph "Security Layers"
        subgraph "Transport Security"
            HTTPS[HTTPS Only]
            CSP[Content Security Policy]
        end
        
        subgraph "Authentication"
            JWT[JWT Tokens]
            STATE[CSRF State Tokens]
            PKCE[PKCE Challenge]
        end
        
        subgraph "Storage Security"
            ENC[Encrypted Credentials]
            SEC[SecretStr Type]
            MUTEX[Redis Mutex Locks]
        end
        
        subgraph "Access Control"
            USER[User Scoped]
            SCOPE[OAuth Scopes]
            EXPIRE[Token Expiration]
        end
    end
    
    HTTPS --> JWT
    JWT --> USER
    STATE --> PKCE
    PKCE --> ENC
    ENC --> SEC
    SEC --> MUTEX
    USER --> SCOPE
    SCOPE --> EXPIRE

Credential Lifecycle Copy Chapter

stateDiagram-v2
    [*] --> Initiated: User clicks sign-in
    Initiated --> Authorizing: Popup opened
    Authorizing --> Authorized: User approves
    Authorizing --> Failed: User denies
    Authorized --> Active: Tokens stored
    Active --> Refreshing: Token expires
    Refreshing --> Active: Token refreshed
    Refreshing --> Expired: Refresh fails
    Active --> Revoked: User deletes
    Failed --> [*]
    Expired --> [*]
    Revoked --> [*]
    
    note right of Active: Credentials can be used
    note right of Refreshing: Automatic process
    note right of Revoked: Tokens revoked at provider

OAuth Types Comparison Copy Chapter

User Authentication (SSO) via Better Auth Copy Section

• Purpose: Authenticate users to access the AutoGPT platform
• Provider: Better Auth, embedded in the Next.js frontend (supports Google, GitHub, and Discord SSO)
• Flow Path: /login → /api/auth/* (Better Auth) → provider OAuth → back to the app
• Session Storage: Better Auth-managed cookies
• Token Management: Automatic by Better Auth; the Python backend validates JWTs via the JWKS endpoint (/api/auth/jwks)
• User Experience: Single sign-on to the platform

API Integration Credentials Copy Section

• Purpose: Grant AutoGPT access to user's third-party services
• Providers: Examples include GitHub, Google APIs, Notion, and others
  • Full list in autogpt_platform/backend/backend/integrations/providers.py
  • OAuth handlers in autogpt_platform/backend/backend/integrations/oauth/
• Flow Path: Integration settings → /api/integrations/{provider}/login → /auth/integrations/oauth_callback
• Credential Storage: Encrypted in PostgreSQL
• Token Management: Custom refresh logic with mutex locking
• User Experience: Connect external services to use in workflows

Data Flow and Security Copy Chapter

1. State Token Flow Copy Section

• Generation: Random 32-byte token using secrets.token_urlsafe()
• Storage: Redis with 10-minute expiration
• Validation: Constant-time comparison using secrets.compare_digest()
• Purpose: CSRF protection and request correlation

2. PKCE Implementation Copy Section

• Code Verifier: Random string generated using secrets.token_urlsafe(128) (approximately 171 characters when base64url encoded, though RFC 7636 recommends 43-128 characters)
• Code Challenge: SHA256 hash of verifier, base64url encoded
• Storage: Stored with state token in database (encrypted) with 10-minute expiration
• Usage: Enhanced security for public clients (currently used by Twitter provider)

3. Credential Storage Copy Section

• Structure:

  python Copy

  OAuth2Credentials:
    - id: UUID
    - provider: ProviderName
    - access_token: SecretStr (encrypted)
    - refresh_token: Optional[SecretStr]
    - scopes: List[str]
    - expires_at: Optional[int]
    - username: Optional[str]

• Persistence: PostgreSQL via Prisma ORM

• Access Control: User-scoped with mutex locking

4. Token Security Copy Section

• Storage: Tokens stored as SecretStr type
• Transport: HTTPS-only, never logged
• Refresh: Automatic refresh 5 minutes before expiry
• Revocation: Supported for providers that implement it

Provider Implementations Copy Chapter

Supported Providers Copy Section

The platform supports various OAuth providers including GitHub, Google, Notion, Twitter, and others. For the complete list, see:

• autogpt_platform/backend/backend/integrations/providers.py - All supported providers
• autogpt_platform/backend/backend/integrations/oauth/ - OAuth implementations

Provider-Specific Security Considerations Copy Section

• GitHub: Supports optional token expiration - tokens may be non-expiring by default
• Linear: Returns scopes as space-separated string, requiring special parsing
• Google: Requires explicit offline access scope for refresh tokens
• Twitter: Uses PKCE for enhanced security on public clients

Each provider handler implements the security measures defined in BaseOAuthHandler, ensuring consistent token management and refresh logic across all integrations.

Security Best Practices Copy Chapter

1. Frontend Security Copy Section

• Use popup windows to prevent URL tampering
• Validate state tokens before processing callbacks
• Clear sensitive data from window messages
• Implement timeout for OAuth flows (5 minutes)

2. Backend Security Copy Section

• Store client secrets in environment variables
• Use HTTPS for all OAuth endpoints
• Implement proper scope validation
• Log security events without exposing tokens
• Use database transactions for credential updates

3. Token Management Copy Section

• Refresh tokens proactively (5 minutes before expiry)
• Revoke tokens when credentials are deleted
• Never expose tokens in logs or error messages
• Use constant-time comparison for token validation

Error Handling Copy Chapter

Common Error Scenarios Copy Section

1. Invalid State Token: 400 Bad Request
2. Provider Configuration Missing: 501 Not Implemented
3. Token Exchange Failure: 400 Bad Request with hint
4. Webhook Conflicts: 409 Conflict, requires confirmation
5. Credential Not Found: 404 Not Found

Error Response Format Copy Section

{
  "detail": {
    "message": "Human-readable error description",
    "hint": "Actionable suggestion for resolution"
  }
}

Testing Considerations Copy Chapter

Unit Testing Copy Section

• Mock OAuth providers for flow testing
• Test state token generation and validation
• Verify PKCE implementation
• Test concurrent access scenarios

Integration Testing Copy Section

• Use provider sandboxes when available
• Test full OAuth flow with real providers
• Verify token refresh mechanisms
• Test error scenarios and recovery

Logging Guidelines Copy Section

• Log flow initiation and completion
• Log errors with context (no tokens)
• Track provider-specific issues
• Monitor for suspicious patterns

Engineering Org Feature Map (`docs/engineering/org-feature-map.md`) Copy Section

Organization Feature Map

A capability map for org/team tenancy on the AutoGPT Platform: what the
foundation shipped in the org-workspace PR series provides, and the feature
surface we expect to build on top of it. Each section lists the existing
hooks in the codebase that a feature would attach to, so scoping starts from
real anchor points instead of a blank page.

Foundation (shipped) Copy Chapter

• Schema: Organization, Team, OrgMember, TeamMember,
  OrgInvitation, TeamInvite, OrganizationProfile, OrganizationAlias,
  OrgBalance, OrgCreditTransaction, OrganizationSubscription,
  OrganizationSeatAssignment, TransferRequest, AuditLog
• Request context: RequestContext (org_id, team_id, role flags,
  seat_status) resolved per-request via get_request_context, with
  X-Org-Id / X-Team-Id header overrides and personal-org fallback
• Execution context: ExecutionContext.organization_id / team_id
  threaded through graph executions, webhooks, schedules, copilot runs
• Billing: get_credit_model(user_id, org_id) routes to
  OrgCreditModel when an org is active; executor charging follows
• Resources: graphs, executions, API keys, chat sessions, store
  listings carry organizationId / teamId; marketplace listings support
  org ownership and cross-org transfers
• Frontend: org/team switcher in the navbar, OrgTeamProvider
  bootstraps context on login, zustand store persists the active org/team
• Migration: idempotent personal-org bootstrap
  (create_orgs_for_existing_users) behind a Redis lock at startup

Deferred from the foundation series: seat enforcement (paywall/subscription
gating work owns this) and the NOT-NULL cutover migration for
organizationId columns.

1. Governance & policy controls Copy Chapter

The headline ask: org/team admins control what members can do and which
capabilities agents may use.

2. Identity & access Copy Chapter

3. Resource management & collaboration Copy Chapter

4. Billing & finance Copy Chapter

5. Marketplace Copy Chapter

6. Observability & compliance Copy Chapter

Suggested build order Copy Chapter

1. Block/provider policy (per-team enable/disable) — highest admin demand,
   clear enforcement choke points, no schema risk beyond one table
2. Audit log write coverage + viewer — prerequisite trust layer for
   everything else admins touch
3. Team-shared library + org credentials — turns tenancy from isolation
   into collaboration; biggest day-to-day user value
4. Budgets/caps + cost attribution — natural follow-on to org billing
   already in place
5. RBAC generalization — only when boolean roles demonstrably block a
   customer; cutover is contained in get_request_context
6. SSO/SCIM — enterprise gate; heavy lift, schedule against real demand

Engineering Tests (`docs/engineering/tests.md`) Copy Section

Testing

The AutoGPT Platform uses several test frameworks at different layers:

• Backend tests use pytest.
• Frontend integration tests use Vitest, React Testing Library, and MSW. These
  are the primary frontend tests.
• End-to-end browser tests use Playwright.
• Design system components use Storybook stories for visual coverage.

Run these Bash commands from the repository root after installing dependencies:

Backend tests require Docker running and the platform environment files. Run
make -C autogpt_platform init-env to create them with fresh local secrets.
Playwright requires the backend running; pnpm test builds
and starts the frontend, reusing an existing server when available.

(cd autogpt_platform/backend && poetry run test)
(cd autogpt_platform/autogpt_libs && poetry run pytest)
(cd autogpt_platform/frontend && pnpm test:unit) # no servers required
(cd autogpt_platform/frontend && pnpm test) # E2E: start the backend first

For the frontend's fast edit/test loop, run pnpm test:unit:watch from its workspace.

See the backend testing guide
and frontend testing guide
for patterns, commands, and guidance on choosing integration or end-to-end
coverage.

Before you start Copy Chapter

Playwright tests require the backend server. pnpm test builds and starts the
frontend for you, or reuses an existing server. Wait for the backend to be ready
before running browser tests.

Running the Playwright tests Copy Chapter

To run the tests, you can use the following commands:

Running the tests without the UI, and headless:

pnpm test

If you want to run the tests in a UI where you can identify each locator used you can use the following command:

pnpm test-ui

You can also pass --debug to the test command to open the browsers in view mode rather than headless. This works with both the pnpm test and pnpm test-ui commands.

pnpm test --debug

In CI, the full-stack workflow
runs the Chromium project headlessly with --retries=0 --trace=retain-on-failure,
overriding the shared config's CI defaults. Its JSON validator requires every test to have exactly one successful
attempt and rejects skipped, flaky, unexpected, or missing results and top-level
errors. See the shared settings in
playwright.config.ts.

Failure traces and test artifacts may contain requests, cookies, and session
state. Use isolated test accounts, never production accounts, and avoid exposing
credentials in traced requests or application output.

Continuous integration Copy Chapter

Sharding Copy Section

The backend workflow
and frontend workflow
define the shard matrix. CI divides the backend and frontend integration suites into disjoint parallel
shards. Backend shards select data, copilot, and util/executor paths; the
remainder uses normal workspace discovery excluding those paths, including new
top-level test files and directories. All shards explicitly load the backend's
pytest configuration. Backend shards use real PostgreSQL, RabbitMQ, and Redis,
with an isolated database, virtual host, and Redis cluster for each shard.
Each shard pays its own service-startup cost, so adding shards also multiplies setup work.

Caching Copy Section

Dependency and browser caches are keyed to their lockfiles. Browser caches can
fall back to a previous cache for the same runner OS, then install missing versions.
Docker builds reuse unchanged layers. Full-stack cache export is limited to trusted dev pushes or an
explicit cache-publishing dispatch. Single-container builds use GHCR caches per
architecture instead of the repository Actions cache. Pull requests read the shared
dev validation cache but never write one; on a pull request a failed GHCR login
or an unreadable cache gives a cold build, not a failed job. Manual dispatches read and update a
branch-specific cache, with the shared dev validation cache as a read-only fallback.
The helper writes that shared tag only on a push to dev, but repository workflows
with package-write permission can overwrite it. Release publication therefore
builds each platform digest cold, without importing this cache, and smoke-tests
and scans the exact pushed digest before publishing the multi-platform manifest.
Validation cache exports are best-effort; failed image builds, smoke tests, and
security scans still fail validation.
The generated E2E seed-data cache is keyed to the files that determine the
seeded data, so it restores across commits that do not change them. Warm
caches may avoid repeated dependency downloads, seed generation, or cache
export, but they never bypass tests, linting, type checks, coverage collection, image builds, image
smoke tests, or security scans.

Test reports Copy Section

Every test job in the validation workflows uploads a JUnit XML or JSON report,
plus coverage artifacts where applicable; this does not describe release-only
publication jobs. The JUnit validator
and Playwright validator
fail validation on missing or malformed reports,
zero discovered tests, count mismatches, failures, and errors. Frontend
integration and Playwright reports also reject skipped tests; the
single-container appliance workflow
allows one exact test ID to skip when Bash 3 is unavailable. The
unittest reporter
enforces this policy, including class, module, and subtest skips. Backend skips must match exact test IDs in
.github/scripts/backend-allowed-skips.json, seeded from the 136 existing skips
per Python version in run 33918906861; a new skip fails validation. Do not add an
ID merely to make CI green: investigate and review the changed skip policy.
An entirely skipped backend shard also fails.
Wrapped commands and malformed backend/frontend reports produce a synthetic
machine-readable error. Single-container validation instead uploads its original
reports and leaves status.json marked validated: false if verification fails.

Manual dispatch Copy Section

The backend, frontend, full-stack, single-container, Classic, CodeQL, and block-docs
workflows have no required manual-dispatch inputs. The separate advisory PR-overlap
workflow still requires pr_number; it is not a CI-status checker. Backend
dispatches can refresh a stacked PR's backend coverage with
gh workflow run platform-backend-ci.yml --ref -f pr_number=;
the optional pr_number only selects the Codecov upload target. Full-stack
dispatches import caches by default; set publish_build_cache only when a test
commit should deliberately refresh them. A manually dispatched single-container
run builds, smoke-tests, and scans the image but cannot publish it; publication
jobs are reachable only from a release event. Single-container validation also
runs on every dev push and release, while pull requests trigger it only when
appliance packaging inputs change.

When CI fails Copy Section

Open the failed Actions run and download its test-report and coverage artifacts
from the run summary. JUnit failures identify the test and traceback; validator
errors identify missing, malformed, or unexpected skipped results. Do not treat
a successful upload as proof the tests passed.

To reproduce a backend shard after configuring the same local services, run
poetry run pytest -c pyproject.toml backend/copilot from the backend workspace
(substitute the failing shard's paths). For a frontend shard, run
pnpm test:unit --shard=1/4 from the frontend workspace, using its CI shard number.

Debugging tests Copy Section

There's a lot of different ways to debug tests.

My preferred is a mix of playwright's test editor and vscode.

No matter what you do, you should always double check that your locators are correct. Playwright will often "time out" and not give you the error message that the locator is incorrect because it can't find the element. You can do this via devtools on your browser and they should be visible on the elements tab when you use the inspect and select elements tools.

Using the playwright test editor

If you need to debug a test, you can use the below command to open the test in the playwright test editor. This is helpful if you want to see the test in the browser and see the state of the page as the test sees it and the locators it uses.

pnpm test --debug --test-name-pattern="test-name"

Using vscode

You can install the Playwright Test for VSCode extension to get autocomplete for the playwright api (id: ms-playwright.playwright).

Installing this will enable the Test Explorer view in vscode which allows you to run, debug, and view all tests in the current project. Adding breakpoints to your tests and running them will automatically open the test editor with the correct context.

Setting up for generating tests Copy Chapter

With playwright, you can generate tests from existing recordings of user sessions. This is useful for creating tests that are more representative of how a user would interact with the application. We generally use this for checking what ids stuff will have and what needs ids to be added.

It is super annoying to continuously login so I highly recommend using a saved session for your tests.
This will save a file called .auth/gentest-user.json that can be loaded for all future gentests so that you don't have to login every time.

Saving a session for gen tests to always use Copy Section

pnpm gentests --save-storage .auth/gentest-user.json

Stop your session with CTRL + C after you are logged in and swap the --save-storage flag with --load-storage to load the session for all future tests.

Loading a session for gen tests to always use Copy Section

pnpm gentests --load-storage .auth/gentest-user.json

How to make a new test Copy Chapter

Tests are composed of page objects and test files.

Do not commit skipped or todo Vitest/Playwright tests. Fix the prerequisite or
ask maintainers to review an explicit policy exception; do not hide a failing
test behind an environment check.

The current Playwright config discovers *-happy-path.spec.ts files under
autogpt_platform/frontend/src/playwright/. Other filenames are not collected;
follow that naming pattern for tests intended to run in CI.

A page object is a class that contains methods for interacting with a page.

A test file is a file that contains tests for a page or a set of pages.

Making a new Page Object Copy Section

For tests, we use the page object model. This is a pattern where each page is a class that contains all the methods and locators for that page.
This is useful for keeping your tests organized and easy to read as well as ensuring that your tests only need to be updated in one place when the UI changes.

You should make a new page object (only when needing to add a new page, or UI element that is across multiple tests) using the following example.

We extend the BasePage class which contains shared methods for pages that have the common functionality like a navbar. If you add something like that (for example a sidebar) you should add it to the BasePage class. Otherwise, you should make a new page object.

Each page object should be in its own file and be named like page-name.page.ts.
A page object should contain methods that are actions that a user can do on that page. For example, clicking a button, filling out a form, etc. It should also contain the various helpful abstractions that are unique to that page. For example, the BuildPage has a method to connect blocks together.

This is a shortened example of a page object for the profile page:

--8<-- "autogpt_platform/frontend/src/playwright/pages/profile.page.ts:ProfilePageExample"
}

Making a new Test File Copy Section

For tests, we use our page objects to create tests. Each test file should be in autogpt_platform/frontend/src/playwright/ and be named like test-name-happy-path.spec.ts. A test file can contain multiple tests. Each of which should be related to the same conceptual function. For example, a test file for the build page could have tests for building agents, creating inputs and outputs, and connecting blocks. If you wanted to specifically test building agents, you could make a new test called building-agents-happy-path.spec.ts.

Tests can inherit from one or more page objects, have pre-actions, and have post-actions, as well as many other features. You can learn more about the different features and how to use them here.

A good focused (unit or single concept) test will:

• Have a short name that describes what it is testing
• Have a single concept (building a agent, adding all blocks, connecting two blocks, etc.)
• Check pre-conditions, actions, and post-conditions, as well as have multiple validations along the way

A good non-focused (integration or multiple concepts) test will:

• Have a short name that describes what it is testing
• Have multiple concepts (building agents, creating-?exporting->importing->running an agent, connecting blocks in multiple ways with multiple inputs and outputs, etc.)
• Have a clear user experience that they are making sure works (for example, clicking the build button and making sure the agent is built, or clicking the export button and making sure the agent is exported and shows up in the monitoring system)
• Not focus on a single concept, but instead test the flow of the application as a whole. Remember you're not testing the pixel perfect UI, but the user experience.

A good test suite will have a healthy mix of focused and non-focused tests.

Example focused test Copy Section

This uses the current coverage fixture and builder page object. Save new cases
under autogpt_platform/frontend/src/playwright/ using the
*-happy-path.spec.ts filename pattern.

import { expect, test } from "./coverage-fixture";
import { E2E_AUTH_STATES } from "./credentials/accounts";
import { BuildPage } from "./pages/build.page";

test.use({ storageState: E2E_AUTH_STATES.builder });

test("builder saves an agent", async ({ page }) => {
  const buildPage = new BuildPage(page);
  await buildPage.createAndSaveSimpleAgent("Example Agent");

  await expect(page).toHaveURL(/flowID=/);
  expect(await buildPage.isRunButtonEnabled()).toBeTruthy();
});

The coverage fixture preserves coverage collection. The storage state supplies
an isolated test account, the page object encapsulates UI interactions, and the
assertions verify both navigation and the saved agent's runnable state.
See the current
builder tests
for full scenarios and timeout choices.

Passing information within a test Copy Section

Keep tests independent: do not make one test consume an ID created by another.
Use local variables or fixtures to share setup within a test, and use
testInfo.attach for safe diagnostics. Avoid attaching credentials or session
state. See Playwright's
fixtures guide
and TestInfo API.

See Also Copy Chapter

• Writing Tests
• Code Generation
• Test UI Mode
• Trace Viewer
• Getting Started with VSCode
• Debugging Tests
• Test Fixtures
• Global Setup and Teardown
• Test Parameterization
• Test Events
• Test Components
• Test Sharding
• Accessibility Testing
• Authentication
• Mocking
• Mock Browser APIs
• Code Generation
• Pages
• Test Annotations

Engineering Tracking Plan (`docs/engineering/tracking-plan.md`) Copy Section

PostHog Tracking Plan

The single list of PostHog events: for every user action, one event name, one
sender and one set of properties. Activation Metrics & Experiments
explains how PostHog fits next to the SQL views, Looker, LaunchDarkly and
DataFast; this page is the event contract.

Event names follow the product analytics plan, Every Second Counts (owner:
Toran), section "What we will record". Where that plan names an event for an
action, this list uses its name; Differences from the analytics plan
lists what is not aligned yet.

In code the names live in two modules. Browser call sites may still pass a
literal (trackBrainDump("brain_dump_started")), which is type-checked
against these modules, and backend funnel data_index keys embed the name
too (briefing_generated:, briefing_delivered:). A
rename therefore has to search for the old string, not just edit the modules:

Rules Copy Chapter

Naming Copy Section

• Use the analytics plan's name. When the plan names an event for an
  action, that is the name, even if we used to send something else.
• Otherwise the name is object_action, snake_case, action in the past
  tense: signup_completed, checkout_started, paywall_viewed.
• Chat (Autopilot) events start with chat_, never copilot_. The trial
  lifecycle is trial_*.
• Rename once, then never again. PostHog stores the raw string, so a
  rename empties every insight, funnel and cohort built on the old name, and
  past events cannot be backfilled. The live names that differed from the
  plan were renamed together in SECRT-2722 (see Renamed); the
  pin tests reserve the old names and fail on any change to a live one.
• Put a new name in PlannedPostHogEvent when it is agreed, and move it into
  the live list in the change that starts sending it.

Who sends it Copy Section

• Outcomes are sent by the backend: something was created, charged, run,
  hired or delivered. The backend sees every path (web, API, copilot, Slack,
  Telegram, webhooks), cannot be blocked by an ad blocker, and is what the
  analytics.* SQL views count.
• Interactions are sent by the browser: views, clicks, dismissals and
  client-side timings that the backend never sees.
• One action has one event. Where two emitters describe the same action,
  the backend event survives and the other stops being sent (see
  Removed).

Base properties Copy Section

Every event must carry:

Every backend event goes through capture() in
backend/util/posthog_client.py, which applies both last, so a caller cannot
overwrite them. The browser registers them once as PostHog super properties
(src/services/analytics/posthog-base-properties.ts), again after reset()
at logout; a Vercel preview reports environment: preview, while the dev
deployment, which is Vercel's staging custom environment rather than a
preview, reports environment: dev.

source is reserved for the emitter. The three events that used it for
something else now use hire_started.surface,
expert_recommended.team_source and workflow_installed_on_expert.workflow_source.

Identity Copy Section

• distinct_id is the platform user id for every backend event, the same
  id the browser passes to posthog.identify(user.id), so both halves land
  on one person.
• Before login the browser uses the first-party anonymous id
  (src/services/analytics/anonymous-id.ts), passed to posthog.init as the
  bootstrap distinctID. identify merges it into the user at login, and
  resetAnalyticsIdentity mints a fresh one at logout.
• The browser waits for analytics consent (Cookiebot,
  src/providers/posthog/posthog-consent.ts). PostHog starts opted out:
  without consent, browser events are dropped, identify is not called and
  the anonymous id lasts only for the page load. Backend events do not
  depend on it.
• No synthetic ids. A backend event with no user is dropped
  (posthog_client.capture does it for every emitter), since a made-up id
  creates a person nobody can merge.
• No email or name in event properties. Identify ids only. The email and
  display name are person properties set by identify and nowhere else.
  (expert_hired.name is the expert's display name, not a person's.)

What counts as a task Copy Chapter

The analytics.* views (user_task_daily, user_lifecycle,
retention_task_weekly, unit_economics_monthly) define a task as a unit of
work a person asked for now:

• a top-level, non-dry-run agent run whose triggerSource is manual or
  api (or NULL, for rows older than the column), expert workflow runs
  included; or
• a user message in an Autopilot or expert chat whose session origin is not
  automation and whose kind is not dream.

A run the copilot started (triggerSource = copilot) is not a second
task: the chat turn that asked for it already counts. agent_run_started does fire
for copilot-started runs (with trigger: copilot), because it measures
human-initiated runs, not tasks. user_lifecycle.agent_runs_human_total is
its SQL twin and includes copilot runs too.

The same definition as a PostHog filter:

event IN ('agent_run_started', 'chat_message_sent')
AND coalesce(properties.via, '') != 'copilot'

In the insight UI: events agent_run_started and chat_message_sent,
filtered by via "is not" copilot. Chat turns carry no via, so
the filter must keep events where it is unset. The emitters already leave
out dry runs, sub-graph runs, schedule and webhook runs, and automation-origin
turns.

Automated work is measured separately: schedule_fired and trigger_fired.

Status legend Copy Chapter

Events that are no longer sent are listed under Removed, with
what replaced them.

Acquisition Copy Chapter

Sidebar CTA clicks retain the tour event names for compatibility. Filter
surface to distinguish the marketplace from the tour; older sidebar events
do not carry this property. For tour-only sidebar reports after deployment,
require surface = tour. The signup CTA uses free-trial in cloud mode and
signup on self-hosted installations, where creating an account starts no trial.

The tour funnel also goes to DataFast (tour_start, tour_scenario_start,
tour_scenario_complete, tour_cta_click); the PostHog events mirror it with
the same properties and nothing identifying in them: /tour is public and
pre-signup, so they land on the visitor's anonymous id. /tour sends the
DataFast goals without consent (SECRT-2713), but the PostHog events wait for
analytics consent like every browser event, so the two funnels count
differently.

Onboarding and activation Copy Chapter