Local setup

Prereqs

• macOS or Linux (Windows works via WSL2 but isn’t first-class)
• Python 3.12 via uv or pyenv
• Node 22+ via nvm
• Docker Desktop or OrbStack
• gcloud CLI (optional, for Cloud Run work)
• 1Password CLI (for secrets: op run --env-file=.env.1password -- make dev)

Clone the workspace

gh repo clone tappass/tappass
gh repo clone tappass/tappass-sdk
gh repo clone tappass/docs
gh repo clone tappass/docs-internal
# Optional
gh repo clone tappass/assess
gh repo clone tappass/license-server
gh repo clone tappass/tappass-examples

Put them all at the same level — the root CLAUDE.md assumes that layout.

First boot — core server

cd tappass/
cp .env.example .env              # or: op run ... for live keys
docker compose up -d postgres     # Postgres on :5432
uv venv && source .venv/bin/activate
uv pip install -e '.[dev]'
alembic upgrade head              # migrate
make dev                          # server on :9620

Verify:

curl http://localhost:9620/healthz  # {"status":"ok"}

SDK against local server

cd tappass-sdk/
uv pip install -e '.[dev]'
python -c "from tappass import Agent; a = Agent('http://localhost:9620', 'tp_dev_...'); print(a.chat('hi').content)"

Public docs locally

cd docs/
npm ci && npm run dev        # http://localhost:4321

Internal docs (this site) locally

cd docs-internal/
npm ci && npm run dev        # http://localhost:4321

Troubleshooting

Symptom	Fix
psycopg import error	Missing libpq — brew install libpq && brew link --force libpq
Port 9620 in use	lsof -i :9620 and kill the process
Alembic fails on first run	Drop the DB and re-up Docker: docker compose down -v && docker compose up -d postgres
SDK gets 401	Your tp_ key wasn’t seeded — run make seed-dev-keys