DrowAI
Product Demo Use Cases Roadmap Docs View on GitHub

User guide

DrowAI user guide

Product documentation for installing DrowAI, setting up Runner services, and understanding the main workspaces. Use it as a practical reference before running the application or preparing a task workflow.

Setup

Local development

Download MD

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:

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:

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

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

Image preview