---
title: "Local development"
description: "Run the DrowAI backend, managed Runner, and frontend from a source checkout."
section: "Setup"
updated: 2026-08-04
tags: ["installation","setup","development","contributor"]
source: "/user-guide/local-development"
---

# Local development

Run the DrowAI backend, managed Runner, and frontend from a source checkout.

Local development starts the backend, managed Runner, and frontend through the
same control-channel architecture used by a single-host deployment. Use this
path for contributing and parity testing, not as a production deployment.

## Prerequisites

- Python 3.11 or newer.
- Node.js 20.19 or newer with npm.
- PostgreSQL 15 or newer with the `pgvector` extension available.
- Docker Engine or Docker Desktop for the managed Runner and task runtimes.

The launcher does not install or start PostgreSQL, and it does not install the
`pgvector` server extension. SQLite is not supported for this setup.

## 1. Install dependencies

From the repository root:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
npm install
```

`requirements-dev.txt` includes the application, contributor, and test
dependencies. Production images install only `requirements.txt`.

## 2. Prepare PostgreSQL

By default, local development connects to `localhost:5432` using database
`drowai` and role `drowai_user`.

You can prepare the database before starting the stack:

```bash
python3 scripts/local_dev.py bootstrap-db
```

The launcher checks the role, database, and `pgvector` extension first. If
anything is missing, it shows the proposed administrative changes and asks for
confirmation before applying them. If the current local administrator identity
is unavailable, it asks for a PostgreSQL administrator username and password.
Those credentials are used only for the bootstrap connection and are not
stored.

For a custom application database, set `DATABASE_URL` in your shell or an
optional root `.env` file. Remote databases should normally be provisioned by
their administrator. Use the one-time `DROWAI_POSTGRES_ADMIN_URL` override only
when bootstrap requires a specific administrator connection; never commit or
retain that credential.

## 3. Start DrowAI

```bash
python3 scripts/local_dev.py up
```

Accept the database bootstrap prompt if it appears. The launcher applies
migrations after the database is ready and stores generated local configuration
and secrets under `.drowai-local`. A root `.env` file is read only for
development overrides.

After first-run setup and sign-in, configure model-provider credentials under
**Settings -> API**.

## Useful URLs

Replace `<development-host>` with the host name or IP address of the machine
running DrowAI. Use `localhost` when opening the URLs on that same machine.

- Frontend: `http://<development-host>:5000`
- Backend API: `http://<development-host>:8000`
- API documentation: `http://<development-host>:8000/docs`