NoUI Setup

One-time environment setup for the NoUI project. Run this before any other NoUI skill.

All commands run from the noui/ directory (the repo root).

---

Critical Rules (Never Violate)

• ALWAYS use .venv/bin/python cli/main.py for all CLI invocations — never the system python or python3
• NEVER run pip install individual packages — all deps are managed by poetry install --no-root
• NEVER run pip install -e . — the project uses package-mode = false in pyproject.toml and does not support editable installs
• ALWAYS copy .env.example to .env and set ANTHROPIC_API_KEY before running the backend
• ALWAYS load the extension from noui/extension/ in Developer mode — the packed install path does not work

---

Step 1 — Create the Virtual Environment

python3 -m venv .venv

Creates .venv/ in the repo root. All subsequent commands use .venv/bin/python.

If python3 --version returns something older than 3.11, use python3.11 -m venv .venv or python3.12 -m venv .venv explicitly (both are supported; the project requires >=3.11).

---

Step 2 — Install Dependencies

.venv/bin/python -m pip install poetry
.venv/bin/python -m poetry install --no-root

--no-root is required because pyproject.toml sets package-mode = false. All runtime deps (FastAPI, FastMCP, Anthropic SDK, SQLAlchemy, httpx, etc.) are installed into .venv.

Common errors:

Error	Fix
ModuleNotFoundError: No module named 'poetry'	Re-run the pip install poetry step above
python3: command not found or version < 3.11	Install Python 3.11 or 3.12 via your OS package manager, then re-create the venv with that interpreter
This build backend cannot be used in 'editable' mode	You ran pip install -e . — use poetry install --no-root instead

---

Step 3 — Configure Environment Variables

cp .env.example .env

Open .env and fill in:

Variable	Required	Purpose
ANTHROPIC_API_KEY	Yes	Powers the MCP compiler's LLM calls
TABBY_API_HOST	Auth flows only	Tabby endpoint (default: http://localhost:8080)
TABBY_ADMIN_TOKEN	Auth flows only	Admin token for provisioning Tabby profiles
NOUI_PORT	No	Backend port (default: 8002)

If you only need unauthenticated app support, ANTHROPIC_API_KEY is the only required field.

---

Step 4 — Load the Chrome Extension

1. Open Chrome and navigate to chrome://extensions/
2. Enable Developer mode (toggle, top-right corner)
3. Click Load unpacked
4. Select the noui/extension/ directory
5. The NoUI Workflow Recorder icon appears in the Chrome toolbar

If the icon does not appear, click the puzzle-piece Extensions menu and pin it.

Verify: Click the icon — you should see the NoUI popup with recording mode options.

---

Step 5 — Verify the Installation

.venv/bin/python cli/main.py status

Expected output when the backend has not yet been started:

NoUI backend:
  Not reachable at http://localhost:8002

This confirms Python, the venv, and all imports are working. The backend not running at this point is expected.

---

Decision Flow

Start
  │
  ├─ Does .venv/ exist?
  │     ├─ No  → Step 1: python3 -m venv .venv
  │     └─ Yes → skip
  │
  ├─ Are deps installed?
  │     ├─ No  → Step 2: pip install poetry + poetry install --no-root
  │     └─ Yes → skip
  │
  ├─ Does .env exist?
  │     ├─ No  → Step 3: cp .env.example .env + fill in ANTHROPIC_API_KEY
  │     └─ Yes → verify ANTHROPIC_API_KEY is set
  │
  ├─ Is Chrome extension loaded?
  │     ├─ No  → Step 4: Load unpacked from noui/extension/
  │     └─ Yes → skip
  │
  └─ Step 5: .venv/bin/python cli/main.py status
       └─ Ready → proceed to /record-login or /record-workflow

---

CLI Command Reference

Command	Purpose
.venv/bin/python cli/main.py status	Verify backend reachability and session counts
.venv/bin/python cli/main.py start	Start the FastAPI backend on port 8002
.venv/bin/python cli/main.py stop	Stop the backend
.venv/bin/python cli/main.py tabby status	Check Docker Compose services and Tabby API liveness
.venv/bin/python cli/main.py tabby start	Start Docker Compose infra and Tabby API
.venv/bin/python cli/main.py tabby stop [--infra]	Stop the Tabby API (and optionally Docker Compose)
.venv/bin/python cli/main.py tabby setup	Full Tabby provisioning: agent client + ServiceProfiles + write TABBY_* to .env
.venv/bin/python cli/main.py tabby session status	Show browser session state for configured profiles
.venv/bin/python cli/main.py tabby session ensure	Ensure a HEALTHY browser session exists
.venv/bin/python cli/main.py tabby session stop	Stop the locally-running worker

Tabby setup — for authenticated app workflows, run tabby start then tabby setup (interactive) to provision agent credentials and ServiceProfiles. This writes TABBY_CLIENT_ID, TABBY_CLIENT_SECRET, and TABBY_API_URL to .env. You still need TABBY_ADMIN_TOKEN (or ADMIN_BOOTSTRAP_EMAIL/ADMIN_BOOTSTRAP_PASSWORD in tabby/.env.local) for the provisioning step.

---

Troubleshooting

Symptom	Fix
ImportError or ModuleNotFoundError on cli/main.py	Deps not installed — re-run poetry install --no-root
.env not found error from backend	Run cp .env.example .env from the noui/ directory
Extension shows "Manifest file is missing"	Confirm you selected noui/extension/ (the dir containing manifest.json)
Extension loads but popup is blank	Check chrome://extensions/ for errors; remove and re-load unpacked
Port 8002 already in use on start	lsof -i :8002 to find conflicting process; set NOUI_PORT=8003 in .env to use another port
Generated tool raises "No Tabby page matching ..."	Open the target site in the Tabby browser, or tabby session ensure --profile <slug>
Generated tool raises Connection refused on port 9222	Tabby's CDP endpoint is down — tabby session ensure --profile <slug>