Run Flagsmith Locally with a Coding Agent

Paste the prompt below into Claude Code, or any coding agent that can run shell commands, and it will bring up a complete Flagsmith instance on your machine with Docker:

1. Checks that Docker is installed and running, and that the ports Flagsmith needs are free.
2. Downloads the Flagsmith Docker Compose file, starts it and waits for it to become healthy.
3. Creates your admin account, an organisation, a project, and Development and Production environments.
4. Connects both environments to the Flagsmith database, so you can try out experiments straight away.
5. Installs the Flagsmith CLI and authenticates it against your instance.
6. Prints a summary with your login, environment keys and URLs.

Prerequisites

• Docker with Docker Compose v2, and at least 4 GB of memory allocated to Docker.
• Ports 8000 and 8001 free on your machine.
• Claude Code or another coding agent.

The prompt

Prompt: run Flagsmith locally

Set up a local Flagsmith instance with experimentation for me, using Docker. Work step by step. After each step,
verify that it worked. If something fails, stop and show me the exact error; don't guess or work around it.

1. Prerequisites. Check that Docker is running (`docker info`) and Docker Compose v2 is available
   (`docker compose version`), and that ports 8000 and 8001 are free. If anything is missing or a port is taken,
   tell me how to fix it and stop. Never stop or kill anything that is already running.

2. Start Flagsmith. In a new `flagsmith` directory, download
   https://raw.githubusercontent.com/Flagsmith/flagsmith/main/docker-compose.yml and run `docker compose up -d`.
   The first run pulls the images and can take a few minutes. Wait until http://localhost:8000/health/liveness/
   returns 200 and `docker compose ps -a` shows the one-off `migrate-db` service exited with code 0. If a service
   fails, show me its last log lines.

3. Create the admin account. Ask me for my name and email address (or use Admin User / admin@example.com if I
   don't mind) and generate a strong password. There is no CLI bootstrap: the dashboard's onboarding screen does
   this while `GET http://localhost:8000/version/` reports `self_hosted_data.has_users: false`, and you do the same
   through the API:
   - `POST /api/v1/auth/users/` with `{"email", "password", "re_password", "first_name", "last_name",
     "superuser": true}`. `superuser` is only accepted while no users exist. The response's `key` authenticates
     the next calls as `Authorization: Token <key>`. If `has_users` is already true, ask me for the existing
     credentials and get a key from `POST /api/v1/auth/login/` with `{"email", "password"}` instead.
   - Create an organisation (`POST /api/v1/organisations/` with `{"name"}`), a project (`POST /api/v1/projects/`
     with `{"name", "organisation"}`) and two environments, Development and Production
     (`POST /api/v1/environments/` with `{"name", "project"}`). Reuse any that already exist.

4. Connect each environment to the Flagsmith database, which stores events in Flagsmith's own PostgreSQL, with
   `POST /api/v1/environments/<environment key>/warehouse-connections/` and this body:
   {"warehouse_type": "postgres", "config": {"source": "flagsmith_database"}}
   Each should come back with `"status": "connected"`. If `/version/` reports `experimentation_enabled: false`, skip
   this step and tell me.

5. Set up the Flagsmith CLI. If `flagsmith --version` doesn't report v2 or later, install it with
   `curl -fsSL https://get.flagsmith.com | sh`, which puts it in `$HOME/.local/bin`, or with
   `brew install Flagsmith/tap/flagsmith`; use `npm install -g @flagsmith/cli` only as a fallback. Check the version
   again. Authenticate the CLI with an organisation API key, not `flagsmith login`: create one with
   `POST /api/v1/organisations/<id>/master-api-keys/` and `{"name": "Flagsmith CLI", "is_admin": true}`; its `key`
   is only returned once. Against a self-hosted instance the CLI only reads host-scoped keys, so write these two
   lines to `flagsmith/flagsmith.env`, with file permissions 600:
   export FLAGSMITH_API_URL=http://localhost:8000
   export FLAGSMITH_API_KEY_localhost_8000=<key>
   Then load the file and check that `flagsmith auth status` and `flagsmith project list` work.

6. Finish with a summary: the dashboard URL (http://localhost:8000) with my email and password; the organisation,
   project and environment names with each environment's key; the events URL for SDKs
   (http://localhost:8000/api/); how to load the CLI credentials (`source flagsmith/flagsmith.env`); and how to stop
   Flagsmith (`docker compose down`) or delete everything (`docker compose down -v`).

What you get

Service	URL
Dashboard and API	http://localhost:8000
Task processor	http://localhost:8001
Events URL for SDKs	http://localhost:8000/api/

The instance stores its data in Docker volumes, so it survives restarts until you run docker compose down -v. Treat it as a local playground: the Compose file uses default secrets that you should change before exposing it anywhere, and the Flagsmith database is only meant for trying out experimentation. For production deployments, see Deployment and Self-hosting.

Next steps

To run your first A/B test against this instance, open your application's repository and use the experiment set-up prompt.