Local Dev Setup

Use this page for a fresh checkout or a new machine. If an existing environment is stuck, go to Local Troubleshooting.

What This Page Gets You

Local env and database credentials aligned.
MongoDB, Redis, and Qdrant running in Docker.
The Auth, Web, API, Customer CMS, and Leverage CMS apps running.
One initial admin in each local CMS.
One Better Auth web user that can sign in.

Fresh Checkout Checklist

Install dependencies with bun install.
Run bun run init to create local env files.
Set the values it reports, then run bun run env:refresh.
Rerun bun run init to start local infrastructure and finish setup.
Start the apps with bun run dev.
Create both CMS admins, then complete the first web access request.

The rest of this page supplies the exact files, URLs, and clicks.

Prerequisites

Git and access to this repository.
Bun, using the version in the root package.json.
Python 3.11 or newer for the project-managed Meltano virtual environment.
Docker Desktop or Docker Engine.
Node/npm only if you want Agent Browser.

bun run init creates and manages the Meltano virtual environment, but it uses an installed Python 3.11+ interpreter. A configured mise Python is supported.

Install The Repo

git clone <repo-url>
cd ai
bun install

Create And Configure Local Env Files

Run:

bun run init

On a fresh checkout, init creates .env.common plus the missing root and app .env files, then pauses before database-backed setup if required values are blank, placeholders, or inconsistent. Its output groups the variable names under the exact file to edit.

The first-run values are split deliberately:

File	Set here
Root `.env`	`MONGO_INITDB_ROOT_USERNAME`, `MONGO_INITDB_ROOT_PASSWORD`, and `REDIS_PASSWORD`
Root `.env.common`	`AUTH_DATABASE_URL`, `BETTER_AUTH_SECRET`, `INTERNAL_SERVICE_API_KEY`, and `CMS_CUSTOMER_SERVICE_API_KEY`
`apps/api/.env`	`DATABASE_URL` and `REDIS_URL`
`apps/cms-customer/.env`	`CMS_CUSTOMER_DATABASE_URL`
`apps/cms-leverage/.env`	`CMS_LEVERAGE_DATABASE_URL`

Generate a separate value for each local password or secret. openssl rand -hex 32 produces a strong URL-safe value when OpenSSL is available.

Use the same Mongo username and password from the root .env in every local Mongo URL. Use the root Redis password in apps/api/.env REDIS_URL. Keep authSource=admin on authenticated Mongo URLs; the API DATABASE_URL also needs the replica-set query parameters shown in its example. Keep the raw password in the root .env, but percent-encode URL-reserved characters when you place that password inside a Mongo or Redis URL.

Shared values are edited once in .env.common, but apps read only their own .env files. Copy the shared values into those app files by running:

bun run env:refresh

env:refresh backs up the current local files and asks before rewriting them. It does not replace app-specific DATABASE_URL, REDIS_URL, or CMS_*_DATABASE_URL values, so edit those in their owning app files first. Use each adjacent .env.example for comments and examples.

Set the Docker credentials before rerunning bun run init or manually running bun run docker:up. Mongo creates its root account only when its data volume is first initialized; changing the root .env password later does not change the account already stored in that volume. If that already happened, use Local Troubleshooting instead of repeatedly changing passwords.

Do not commit local env files, and do not export a global DATABASE_URL; a shell value can override the app-local value unexpectedly.

Finish Init And Start Infrastructure

Rerun initialization after fixing the reported env values:

bun run init

The successful run starts MongoDB, Redis, and Qdrant, reconciles local Auth setup, generates stable local Payload secrets when needed, seeds Customer CMS connector and public-chat catalogs, prepares the local Leverage CMS feedback handoff, and prepares the project-managed Meltano runtime. It ends with the real next commands and browser guidance. Use bun run init --skip-docker only when you intentionally manage local infrastructure yourself.

Start The Apps

bun run dev

Keep this guide running in another terminal if needed:

bun run dev:support

Main-checkout URLs:

Surface	URL
Auth health	`http://localhost:3001/health`
Web	`http://localhost:3002/`
Customer CMS	`http://localhost:3003/admin`
Support Dev	`http://localhost:3004/`
Leverage CMS	`http://localhost:3005/admin`
API health	`http://localhost:4111/health`

Linked worktrees use unique ports. Run this in the worktree and use the reported CMS, Web, Support, Auth, and API URLs:

bun run worktree:ports

The root bun run dev command prints the same active port profile before starting the Turborepo TUI.

Create The Initial CMS Users

Each CMS has its own native Payload account store. Opening /admin against an empty CMS database shows Payload’s first-user form:

CMS	Main-checkout URL	Create
Customer CMS	`http://localhost:3003/admin`	The initial Customer CMS admin
Leverage CMS	`http://localhost:3005/admin`	The initial user, explicitly selecting the `Admin` role

For a linked worktree, append /admin to the Customer CMS and Leverage CMS URLs from bun run worktree:ports.

Create both accounts. They are not shared with each other or with Better Auth web users, even if you use the same email address. Payload auto-verifies the first user in an empty database; later CMS users must complete email verification. Selecting Admin for the first Leverage CMS user keeps user administration and account recovery available.

AGENT_BROWSER_CMS_* credentials sign in to existing accounts. They do not create CMS users. See CMS Users And Web Users for bootstrap rules in local, test, staging, production, and recovery environments.

Create The First Web User

Open the Web sign-in page. A fresh checkout enables email/password by default, so the form renders without workforce SSO credentials. Direct public signup is intentionally disabled; the first web user completes an approved access request.

Recommended path:

Open Web /auth/request-access and submit the request.
In Customer CMS, open Web Access Requests, select the pending request, and approve it.
Use Copy completion link in the approval result.
Open the link, set the web password, and sign in.

Customer CMS can also start the invitation: open Web Access Requests, choose Create New, and save the request. On the saved approved request, use Regenerate completion link, then Copy completion link. Open that URL to set the password and finish the Better Auth account.

The Customer CMS record is an operator command and read-only mirror of Auth-owned state; it is not a CMS login and does not make the web user a CMS operator.

Optional Browser Automation

Install Agent Browser once per machine:

npm i -g agent-browser
agent-browser install

After the three accounts above exist, put their local automation credentials in the root .env and use the repo helpers:

bun run agent-browser:login:web
bun run agent-browser:login:cms-customer
bun run agent-browser:login:cms-leverage

Open a saved session with the matching agent-browser:open:* command. The helpers use separate web, Customer CMS, and Leverage CMS sessions and launch headed Chrome with the repo theme.

Optional Codex Setup

If you use Codex, accept its trust prompt from the repo root so the repo-scoped .codex/config.toml can load. For non-interactive setup, add the exact checkout path to your user-level ~/.codex/config.toml:

[projects."/absolute/path/to/ai"]
trust_level = "trusted"

Do not commit machine paths or trust settings to the repo-local config. Verify the generated MCP configuration with codex mcp list.

Optional Local Apps And Diagnostics

Token replacer: bun run dev:token-replacer
Startup sequencing diagnostics: bun run dev:diagnose-startup
Docker Meltano mode: stop the normal profile, then use bun run docker:up:meltano
Qdrant dashboard: http://localhost:17533/dashboard

Normal development uses bun run dev, host-managed Meltano, and the local-only server bindings.