AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.
Getting Started with AutoGPT: Self-Hosting Guide
Introduction
This guide will help you set up AutoGPT on your own machine. There are two ways to do it:
- 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 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.
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, start it, then verify that it is running:
docker -v
docker info
Running the image
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:
docker inspect --format '{{.State.Health.Status}}' autogpt
Then open http://localhost:3000, create your account, and make it the administrator:
docker exec autogpt autogpt-admin promote [email protected]
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:
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 covers model providers, another port or a public URL, backups, upgrades, and troubleshooting.
Appliance installer
The appliance installer 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 run the
same steps for you and can also set up a local Ollama model.
{% hint style="warning" %} Docker Compose publishes PostgreSQL, Redis, RabbitMQ, and every backend service port on all network interfaces. Redis has no password, PostgreSQL and RabbitMQ use the default passwords from this repository, and signup is open. Run the stack on a machine and network you trust. {% endhint %}
Development prerequisites
The manual setup needs Git, Docker with
Docker Compose, 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) or
to migrate an older Supabase-based install. Verify the rest before continuing:
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.
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_platformdirectory inside the AutoGPT folder:cd AutoGPT/autogpt_platform
Create the
.envfiles and generate your local secrets:make init-envThis copies each
.env.defaultto.env(forautogpt_platform,backendandfrontend) and fills in the secrets that.env.defaultdeliberately leaves blank —ENCRYPTION_KEY,UNSUBSCRIBE_SECRET_KEY,INTERNAL_API_KEYandBETTER_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.envor a value you set yourself. You can then edit the.envfiles to add your own environment variables.The backend refuses to start while
ENCRYPTION_KEYis empty, so run this before bringing the stack up.Run the platform services:
docker compose up -d --buildThis command will start all the necessary backend services defined in the
docker-compose.ymlfile 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:
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-envmatters when running the frontend outside Docker: Next.js only reads.env(not.env.default), and the frontend's embedded auth service needsDATABASE_URLandBETTER_AUTH_SECRETfrom it.
You can always check available Makefile recipes by running:
make help
(or just inspecting autogpt_platform/Makefile).
Checking if the application is running
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
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 anENCRYPTION_KEYline — it was running on the value from.env.default; or - stops on startup with
ENCRYPTION_KEY is set to a value that was published…orENCRYPTION_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/.
Stop the stack:
docker compose downKeep the key your data is currently encrypted with. If you never set one, it is the value
.env.defaultcontained up to releasev0.7.4: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:
cp backend/.env ~/autogpt-backend.env.$(date +%Y%m%d-%H%M%S)Generate the new values.
make init-envcreates any missing.envfile and fills in every secret whose line is present but empty; it never overwrites a value. So inbackend/.envmake sure these two lines exist with nothing after the=, and do the same forBETTER_AUTH_SECRET=infrontend/.env:ENCRYPTION_KEY= UNSUBSCRIBE_SECRET_KEY=Then:
make init-envWithout
make, these are the same steps by hand. Copy a.env.defaultonly where no.envexists yet: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/.envDo not re-run
setup-autogpt.shorsetup-autogpt.batfor this: they also start the stack, which is step 5.Re-encrypt what is stored. Build the new images and bring the database up to date first;
migratestarts the database on its own:docker compose build migrate rest_server docker compose run --rm migrateThen run the command, first as a dry run that only reports what it would change, then with
--applyto write it.--no-depskeeps it from waiting on the rest of the stack, which it does not need: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 --applyIt 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-keyinautogpt_platform/backend.Start the stack again. If
BETTER_AUTH_SECRETchanged 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.--buildbrings the remaining services to the release you built in step 4: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
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:
Environment files: refresh your
.envfiles against the new.env.defaults.make init-envcopies.env.default→.envforautogpt_platform,backendandfrontend, but only where no.envexists yet (it usescp -n): it creates missing.envfiles and never overwrites an existing one. It does not merge newly-added variables into an.envyou already have — for an existing install, diff each.envagainst its.env.defaultand copy the new keys across yourself. TheSUPABASE_*URL/key variables are gone; the frontend now usesBETTER_AUTH_SECRETandDATABASE_URL.ENCRYPTION_KEY,UNSUBSCRIBE_SECRET_KEYandBETTER_AUTH_SECRETare no longer filled in by.env.default: follow Upgrading: secrets are generated per install as part of this step.Database location: the database now lives in a plain Postgres container (
pgvector/pgvector:pg15) with its data inautogpt_platform/data/db/data. Your old data is untouched atautogpt_platform/db/docker/volumes/db/databut 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:mkdir -p autogpt_platform/data/db mv autogpt_platform/volumes/db/data autogpt_platform/data/db/dataTo 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/databefore you start.The old bundled stack ran
supabase/postgres:15.8.1.049and the newdbservice runspgvector/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:
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 dbOn Linux the data directory is mode
0700owned by the container'spostgresuser, so the copy needssudo cp -a(the plain Postgres entrypoint fixes ownership on first boot). On Docker Desktop for macOS/Windows the plaincp -ais enough. It worked if the log settles ondatabase system is ready to accept connectionsand your data is there: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, orPermission denied— Postgres is either missing something the Supabase image provided, or can't read the copied files. In that caserm -rf data/db/dataand 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.
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_restorereports errors for objects belonging to Supabase-only extensions and roles (storage,realtime,supabase_admin,pgsodium, …). Those are harmless. An error onauth.usersis not: that table is where your accounts live, and the migration in step 3 below copies them out of it. If the count above is0— orpg_restorefailed onauth.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:
docker compose run --rm migrate docker compose up -dUser 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.userstable into the Better Auth tables by the backend Prisma migration20260716120000_copy_supabase_users_to_better_auth, which runs as part of thedocker compose run --rm migratestep 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_SECRETset infrontend/.envfor as long as you want that bridge open. frontend/scripts/migrate-supabase-auth.tsis 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.cd frontend && DATABASE_URL=postgresql://postgres:<password>@localhost:5432/postgres npx tsx scripts/migrate-supabase-auth.ts
- Existing users are copied from the Supabase
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:
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
httpis fine forlocalhostand for container-to-container traffic on a single host (the defaulthttp://frontend:3000over the Docker network) — there is no network segment for an attacker to sit on. - Use
httpson 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 pointJWT_JWKS_URLat thehttps://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:
- Install WSL 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.
- 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:
- Open Docker Desktop.
- Go to Settings > General.
- Enable Use the WSL 2 based engine.
- 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
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
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 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
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 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
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.runmethod: 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_mockfield 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
devbranch of the repository with your changes so you can share it with the community :)