> For the complete documentation index, see [llms.txt](https://agpt.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://agpt.co/docs/platform/self-hosting/getting-started.md). # Setting Up AutoGPT (Self-Host) ## Introduction This guide will help you set up AutoGPT on your own machine. There are two ways to do it: * [**Quick Setup with Docker**](#quick-setup-with-docker) runs the published image from Docker Hub: one container and no source checkout. Start here if you want to use AutoGPT. * [**Manual Setup**](#manual-setup) clones the repository and builds every service with Docker Compose. Use it to develop AutoGPT, or to run each service in its own container. {% hint style="warning" %} **DO NOT FOLLOW ANY OUTSIDE TUTORIALS AS THEY WILL LIKELY BE OUT OF DATE** {% endhint %} ## Quick Setup with Docker The quickest way to self-host is the single-container image on Docker Hub, [`significantgravitas/autogpt`](https://hub.docker.com/r/significantgravitas/autogpt). It bundles the web app, APIs, workers, PostgreSQL, RabbitMQ, Valkey, and FalkorDB-backed memory, and keeps all of its data in one Docker volume. The image is meant for local and small installations, not high-availability deployments. ### Prerequisites You only need Docker: Docker Engine or Docker Desktop running Linux containers on `amd64` or `arm64`. Git, Node.js, and Docker Compose are not required. Test installations use about 5–6 GiB of memory, so plan for at least 8 GB of RAM and about 25 GB of free disk. Docker Desktop caps its VM's memory: raise the limit under **Settings β†’ Resources**, or in `.wslconfig` on Windows with the WSL 2 backend. Install Docker from the [official Docker documentation](https://docs.docker.com/get-docker/), start it, then verify that it is running: ```console docker -v docker info ``` ### Running the image ```bash docker run -d \ --name autogpt \ --restart unless-stopped \ --shm-size 2g \ --ulimit nofile=65536:65536 \ --log-driver json-file \ --log-opt max-size=50m \ --log-opt max-file=5 \ -p 127.0.0.1:3000:3000 \ -e AUTOGPT_PUBLIC_URL=http://localhost:3000 \ -v autogpt-data:/data \ significantgravitas/autogpt:latest ``` `AUTOGPT_PUBLIC_URL` must match the address in your browser, so change both if you publish a different port. On Windows, put the command on one line in PowerShell, or run it from a WSL 2 terminal. The first boot applies database migrations and can take several minutes. Don't stop the container until Docker reports it as `healthy`: ```console docker inspect --format '{{.State.Health.Status}}' autogpt ``` Then open , create your account, and make it the administrator: ```bash docker exec autogpt autogpt-admin promote you@example.com ``` Sign out and back in so your session picks up the administrator role. Signup stays open to anyone who can reach the app, which is why the command above publishes the port on `127.0.0.1` only. To close signup, remove the container: ```bash docker stop autogpt docker rm autogpt ``` Then run the `docker run` command again with `-e AUTH_ALLOW_NEW_ACCOUNTS=false` added. Keep the `autogpt-data` volume whenever you replace the container: it holds your accounts, agents, memory, and generated secrets. `latest` tracks the newest verified release. To pin a version, use an immutable `vX.Y.Z` tag instead. [Run AutoGPT in One Docker Container](/docs/platform/self-hosting/single-container.md) covers model providers, another port or a public URL, backups, upgrades, and troubleshooting. ### Appliance installer The [appliance installer](/docs/platform/self-hosting/installer.md#install) wraps these steps in one command for Linux, macOS, and Windows: it checks your Docker setup, pins the pulled image by digest, and keeps its configuration in a private directory. ## Manual Setup The manual setup clones the repository, builds every service from source, and runs each one in its own container with Docker Compose. The `setup-autogpt.sh` and `setup-autogpt.bat` scripts described in [the installer reference](/docs/platform/self-hosting/installer.md#installing-from-source-compose) run the same steps for you and can also set up a local Ollama model. {% hint style="warning" %} Docker Compose publishes the frontend (port 3000), the REST API (8006) and the WebSocket server (8001) on all network interfaces, and signup is open. Run the stack on a machine and network you trust. PostgreSQL, Redis, RabbitMQ, FalkorDB and ClamAV are published on `127.0.0.1` only, and all but ClamAV require a password `make init-env` generates for your install. {% endhint %} ### Development prerequisites The manual setup needs [Git](https://git-scm.com/downloads), Docker with [Docker Compose](https://docs.docker.com/compose/install/), `make`, and Python 3, which `make init-env` uses to generate your secrets. Node.js is only needed to run the frontend outside Docker (see [Development](#development)) or to migrate an older Supabase-based install. Verify the rest before continuing: ```console git --version docker -v docker compose version make --version python3 --version ``` On Windows, where `make` is usually not installed, clone the repository as below, then run `autogpt_platform\installer\setup-autogpt.bat` instead of the remaining steps. It creates the `.env` files, generates the secrets, and starts the stack. ### Cloning the Repository 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](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository). Once that's complete you can continue the setup process. ### Running the AutoGPT Platform To run the platform, follow these steps: * Navigate to the `autogpt_platform` directory inside the AutoGPT folder: ```bash cd AutoGPT/autogpt_platform ``` * Create the `.env` files and generate your local secrets: ``` 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`, `INTERNAL_API_KEY`, `BETTER_AUTH_SECRET`, and the passwords of the database, RabbitMQ, Redis and FalkorDB β€” 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 never overwrites an existing `.env` or a value you set yourself, and you can then edit the `.env` files to add your own environment variables. To upgrade an install that is already running, follow [Upgrading: service passwords are generated per install](#upgrading-service-passwords-are-generated-per-install) instead: there this command replaces the passwords this repository used to publish, and the restart after it empties RabbitMQ's queues. The backend **refuses to start** while `ENCRYPTION_KEY` is empty, and Docker Compose refuses to start without the database password, so run this before bringing the stack up. * Run the platform services: ``` 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 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: | Command | What it Does | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `make init-env` | Create missing `.env` files from `.env.default` (`autogpt_platform`, `backend`, and `frontend`) and generate the secrets they leave blank | | `make start-core` | Start the services the backend needs (Postgres, Redis, RabbitMQ, ClamAV, FalkorDB) in background and apply the database migrations | | `make stop-core` | Stop every running service in the stack | | `make logs-core` | Tail the logs for core services | | `make format` | Format & lint backend (Python) and frontend (TypeScript) code | | `make migrate` | Run backend database migrations | | `make publish-skills` | Publish the skills catalog (marketplace skills and the expert roster) into your database; run `make load-store-agents` first if you want the experts' preload workflows too | | `make run-backend` | Run the backend FastAPI server | | `make run-frontend` | Run the frontend Next.js development server | *Example usage:* ```sh 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: ```sh make help ``` (or just inspecting `autogpt_platform/Makefile`). *** ### Checking if the application is running You can check if the server is running by visiting 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 `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. This applies to Docker Compose installs; the Docker Hub image generates its own secrets on first boot and keeps them in its data volume. A fresh install needs nothing beyond `make init-env` (or `installer/setup-autogpt.sh` / `setup-autogpt.bat`, which do 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. Empty RabbitMQ's queues, then stop the stack and update it. The restart in step 5 recreates RabbitMQ, and a recreated RabbitMQ starts with empty queues, so while the version you have now is still running, first follow steps 1 to 3 of [Upgrading: service passwords are generated per install](#upgrading-service-passwords-are-generated-per-install), which leave the queues empty and only RabbitMQ running. The steps here take the place of its step 4. Then: ```bash docker compose stop -t 60 git pull ``` Use `stop`, not `down`: `down` would also throw away Redis's data. 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 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 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 one of these keys. 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`: ``` ENCRYPTION_KEY= UNSUBSCRIBE_SECRET_KEY= ``` Then: ```bash make init-env ``` Without `make`, these are the same steps by hand. Copy a `.env.default` only where no `.env` exists yet: ```bash cp -n .env.default .env cp -n backend/.env.default backend/.env cp -n frontend/.env.default frontend/.env python3 single-container/runtime_config.py fill-env \ --path .env --path backend/.env --path frontend/.env ``` Do not re-run `setup-autogpt.sh` or `setup-autogpt.bat` for this: they also start 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 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 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 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: service passwords are generated per install The database, RabbitMQ and FalkorDB used to take their passwords from the `.env.default` files, Redis had none, and Docker Compose published all of them on every network interface. They are now published on `127.0.0.1` only, and their passwords are generated per install, like the secrets above. The upgrade recreates the RabbitMQ container, and a recreated RabbitMQ starts with empty queues: workflow runs waiting to start, chat turns, scheduled runs and emails still queued there are lost. So empty the queues first, while the version you have now is still running, and upgrade by these steps rather than by running the setup script again, which recreates RabbitMQ the same way. Run them from `autogpt_platform/`, in PowerShell on Windows: 1. Stop the services that queue new work, so that those working through the queues can catch up. Leave out any your version doesn't have: ```bash docker compose stop frontend rest_server websocket_server scheduler_server platform_linking_manager ``` A backend you run outside Docker (`poetry run app`) does both, so leave it running for now. 2. Run this about once a minute. For each of RabbitMQ's virtual hosts (usually only `/`, but versions differ in which one the platform's queues end up in, so it checks them all), it lists the queues, how many messages each holds, and how many services read it: ```bash docker compose exec rabbitmq sh -c 'set -f; IFS=; rabbitmqctl -s list_vhosts | while read -r vhost; do echo == virtual host $vhost; rabbitmqctl -q list_queues -p $vhost name messages consumers; done' ``` Go on once every queue shows `0` messages on two checks in a row, apart from those nothing reads (the last case below). A queue that keeps its messages: * with a consumer is still being worked through: wait. * with none has lost its reader. Look for a service that isn't running (`docker compose ps -a`, and the `poetry run app` process if you run the backend outside Docker) or that keeps logging errors as it retries (`docker compose logs --since 5m`), get it going again, and wait. * is read by nothing in the version you run if it is a dead-letter queue, whose name starts with `failed_notifications` (it keeps emails that already failed to send), or if it has had no consumer for ten minutes while the services still running log no errors (an earlier version used it). RabbitMQ can't carry what these hold over to the new version: note which queues they are, and go on only if you can do without their messages. 3. Stop everything but RabbitMQ, and the backend too if you run it outside Docker. `-t 60` gives Redis a minute to write its data out as it stops. On Linux and macOS: ```bash services=$(docker compose ps --services | grep -vx rabbitmq) [ -z "$services" ] || docker compose stop -t 60 $services ``` In PowerShell: ```powershell $services = @(docker compose ps --services | Where-Object { $_ -ne "rabbitmq" }) if ($services) { docker compose stop -t 60 $services } ``` Wait ten seconds, since RabbitMQ updates these counts only every five, then run the command from step 2 once more. With nothing else running, nothing can add a message or take one, so this is the check that counts: every queue must show `0`, apart from those you noted in step 2. If any other queue holds a message, start everything again with `docker compose start` (and `poetry run app` in `backend/`, if you run the backend outside Docker) and go back to step 1. 4. Update the stack, generate the passwords, and rebuild and start it: ```bash git pull make init-env docker compose up -d --build ``` On Windows, where `make` is usually not installed, run `installer\setup-autogpt.bat` in place of `make init-env`, then `docker compose up -d --build`. The script generates the passwords before anything reads them and starts the stack on the images you have; the second command rebuilds them and restarts what changed. Compose stops before it builds anything if `.env` has no `POSTGRES_PASSWORD`, which an install from before that setting existed lacks, so don't build first. With the queues empty and the stack stopped, neither restart loses anything. Don't run `docker compose down` during the upgrade: it throws away Redis's data, which holds work in progress such as AutoPilot's batch requests, while `up` keeps it. If `docker compose ps -a` listed a service named `redis` rather than `redis-0` to `redis-2`, your version predates the Redis cluster. The cluster starts empty, and what the old Redis held stays behind in its stopped container. `make init-env` replaces each password that still holds the published value, adds the ones your `.env` files predate (`REDIS_PASSWORD`, for one), and keeps the database password the same in the three files that hold it: `POSTGRES_PASSWORD` in `.env`, `DB_PASS` in `backend/.env` and `DATABASE_URL` in `frontend/.env`. Passwords you set yourself are kept, but it stops with an error on one that Compose would take from the environment when the stack starts (`$NAME`, `${NAME}`, or the name alone on a line): write the password itself. The database applies `POSTGRES_PASSWORD` every time it starts, so its data stays where it is. A database, Redis, RabbitMQ or FalkorDB that `backend/.env` points at another host is a service of your own, and `make init-env` leaves its password as it is. The host that counts is the one the backend reads: `DB_HOST`; `REDIS_CLUSTER_HOST`, or else `REDIS_HOST`; `RABBITMQ_CLUSTER_HOST`, or else `RABBITMQ_HOST`; and `GRAPHITI_FALKORDB_HOST`. If you upgraded without emptying the queues, workflow runs that were waiting to start stay **Queued**. An hour later an admin can start them again from **Admin β€Ί Diagnostics**, tab **Stuck Queued**, with **Requeue All**. Don't skip `make init-env`. Without it, the stack goes on using only the passwords its `.env` files hold, and the backend logs a warning at startup while one of them is a value this repository published. A password an older file has no line for came from `.env.default`, which now leaves it blank: * Compose refuses to start without `POSTGRES_PASSWORD` in `autogpt_platform/.env`. * FalkorDB doesn't start without `GRAPHITI_FALKORDB_PASSWORD`, which a `backend/.env` created before v0.6.55 lacks. * The backend can't log in to RabbitMQ without `RABBITMQ_DEFAULT_PASS`, which a `backend/.env` created before v0.4.10 lacks. `make init-env` adds each of them, and the backend's startup log names the last two while they are missing. If something outside the stack logs in to one of these services, such as a backup job or a database tool, give it the new password from those files. To reach a service from another machine, forward its port over SSH (for example `ssh -L 5432:127.0.0.1:5432 `) rather than publishing it on the network again. Docker Engine 28 and later keep other machines away from ports published on `127.0.0.1`; older versions let a machine on the same local network reach them, so update Docker if yours is older. If your database's `pg_hba.conf` asks local connections for a password, the database can't change its own password with only the new one, so it doesn't start and logs why. Start it once with `PGPASSWORD` set to its current password, for example in a `docker-compose.override.yml`: ```yaml services: db: environment: PGPASSWORD: ``` Remove the override once it has started. ### Upgrading an existing (Supabase-based) installation 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.default`s. `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. Apart from the service passwords (see [Upgrading: service passwords are generated per install](#upgrading-service-passwords-are-generated-per-install)), 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](#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 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 cd autogpt_platform docker compose stop -t 60 # not down: that drops RabbitMQ's queues and Redis's data 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 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 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 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 cd frontend && DATABASE_URL=postgresql://postgres:@localhost:5432/postgres npx tsx scripts/migrate-supabase-auth.ts ``` A fresh install (empty database) needs none of this. ### Additional Notes `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: ```python from cryptography.fernet import Fernet;Fernet.generate_key().decode() ``` Or run the following command in the `autogpt_platform/backend` directory: ```bash 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](#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](https://github.com/FiloSottile/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 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](https://learn.microsoft.com/en-us/windows/wsl/install). 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](https://docs.docker.com/desktop/windows/wsl/). ### ⚠️ Podman Not Supported 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](https://docs.docker.com/desktop/) and use `docker compose` instead of `podman-compose`. ## Development ### Frontend Development #### Running the frontend locally To run the frontend locally, you need to have Node.js and PNPM installed on your machine. Install [Node.js](https://nodejs.org/en/download/) to manage dependencies and run the frontend application. Install [PNPM](https://pnpm.io/installation) to manage the frontend dependencies. Run the service dependencies (backend, database, message queues, etc.): ```sh docker compose --profile local up deps_backend --build --detach ``` Go to the `autogpt_platform/frontend` directory: ```sh cd frontend ``` Install the dependencies: ```sh pnpm install ``` Generate the API client: ```sh pnpm generate:api-client ``` Run the frontend application: ```sh pnpm dev ``` #### Formatting & Linting Auto formatter and linter are set up in the project. To run them: Format the code: ```sh pnpm format ``` Lint the code: ```sh pnpm lint ``` *Or for both frontend and backend, from the root:* ```sh make format ``` #### Testing To run the tests, you can use the following command: ```sh pnpm test ``` ### Backend Development #### Running the backend locally To run the backend locally, you need Python 3.11, 3.12 or 3.13 installed on your machine. Install [Poetry](https://python-poetry.org/docs/#installation) to manage dependencies and virtual environments. Run the backend dependencies (database, message queues, etc.): ```sh docker compose --profile local up deps --build --detach ``` *Or equivalently with Makefile:* ```sh make start-core ``` Go to the `autogpt_platform/backend` directory: ```sh cd backend ``` Install the dependencies: ```sh poetry install --with dev ``` Run the backend server: ```sh poetry run app ``` *Or from within `autogpt_platform`:* ```sh make run-backend ``` #### Formatting & Linting Auto formatter and linter are set up in the project. To run them: Format the code: ```sh poetry run format ``` Lint the code: ```sh poetry run lint ``` *Or format both frontend and backend at once:* ```sh make format ``` #### Testing To run the tests: ```sh poetry run pytest -s ``` ## Adding a New Agent Block 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 :) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://agpt.co/docs/platform/self-hosting/getting-started.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.