dograh/.conductor

Conductor workspace setup

This directory makes Conductor workspaces (git worktrees) self-contained: each one installs its own deps and runs its own backend + UI on a dedicated port range, so you can develop several branches at once without collisions.

How it works

Conductor gives every workspace a block of 10 ports starting at $CONDUCTOR_PORT. We use:

Port	Service	Script
CONDUCTOR_PORT	UI (Next.js)	run-ui.sh
CONDUCTOR_PORT + 1	Backend (uvicorn)	run-backend.sh
+2 .. +9	reserved	—

The UI sits on the base port so Conductor's Open button (preview_urls) lands on it directly — preview templates only substitute $CONDUCTOR_PORT, with no +1 arithmetic. The UI is wired to its own workspace's backend (NEXT_PUBLIC_BACKEND_URL, BACKEND_URL) and the backend's CORS / UI_APP_URL point back at its own UI — all derived from $CONDUCTOR_PORT, so no two workspaces interfere.

Shared, NOT per-workspace

Postgres, Redis, and MinIO run as a single shared Docker stack (compose project dograh). setup.sh brings it up idempotently with COMPOSE_PROJECT_NAME=dograh so every workspace reuses the same one instead of fighting over the fixed 5432/6379/9000 ports. All workspaces therefore share one database — fine for app servers, but it means the Arq worker should run in only one workspace (run-worker.sh), since a single worker drains the shared queue for everyone.

The Run menu

Important: a Conductor workspace runs one run script at a time. run_mode = "concurrent" lets different workspaces run simultaneously — it does not let you click two run buttons in the same workspace. That's why dev starts the UI and backend together instead of relying on two buttons.

The Run dropdown offers:

• dev (default) — UI ($CONDUCTOR_PORT) and backend ($CONDUCTOR_PORT+1) together, via concurrently. Use this day to day.
• ui — Next.js only, for debugging the frontend alone.
• backend — uvicorn only, for debugging the API alone.
• worker — Arq worker; start in just one workspace.

Hit dev and both servers come up; click Conductor's Open button to launch the UI. Start worker once (e.g. in your primary workspace) when you need background jobs — the same way you used to run a single arq worker in VS Code.

Proving you're in the right worktree

run-ui.sh exports NEXT_PUBLIC_WORKSPACE_NAME=$CONDUCTOR_WORKSPACE_NAME, which ui/src/components/WorkspaceBadge.tsx renders as a small color-coded pill in the bottom-left corner (e.g. ⬡ pattaya :8200). The color is derived from the workspace name, so two worktrees are instantly distinguishable. The badge is invisible in production and in a plain npm run dev (no env var set).

Creating a new workspace

In Conductor: New Workspace → pick a branch. Conductor first copies the gitignored env files listed in ../.worktreeinclude (api/.env, ui/.env, ui/.env.local, …) from your main checkout, then setup.sh runs automatically and:

1. checks out the pipecat submodule,
2. builds venv (Python 3.13) + installs backend/pipecat deps,
3. npm install for the UI,
4. ensures the shared Docker stack is up,
5. runs alembic upgrade head.

The first setup is slow (deps); afterwards the Run buttons are instant.

Files

File	Purpose
settings.toml	Conductor config: setup + run scripts, preview_urls
setup.sh	One-time workspace bootstrap
run-dev.sh	Default run: UI + backend together (concurrently)
run-ui.sh	Foreground Next.js on $CONDUCTOR_PORT
run-backend.sh	Foreground uvicorn on $CONDUCTOR_PORT + 1
run-worker.sh	Foreground Arq worker (run in one workspace only)
../.worktreeinclude	Gitignored env files Conductor copies per workspace

Need machine-local tweaks (e.g. a different port base or skipping the worker)? Put them in .conductor/settings.local.toml, which is personal and not committed.