clawdi AGENTS.md

Clawdi

The best home for all your AI agents. Run them in the cloud or connect your own—with their context and tools in one place. This repository contains the CLI, FastAPI backend, TanStack dashboard, shared types, agent adapters, channels, and sync.

Maintain agent-facing repository docs with docs/agent-docs-guide.md.

OSS Boundary

Hosted infrastructure is owned outside this repo by first-party hosted control planes. Do not add hosted service runbooks, private addresses, or internal deployment details here.

Repository Map

apps/web/          TanStack Start dashboard
backend/           FastAPI backend, async PostgreSQL, Alembic
packages/cli/      TypeScript/Bun CLI, adapters, MCP stdio server
packages/shared/   Shared types, constants, generated API client
packages/whatsapp-baileys-sidecar/  WhatsApp Baileys sidecar package
docs/              Contributor docs, ADRs, plans, scenarios

For architecture and ownership, read docs/architecture.md.

Local End-to-End

Install dependencies once:

bun install

Terminal 1, backend:

docker compose up -d postgres
cd backend
cp .env.example .env
uv sync
python3 - <<'PY'
import secrets
for name in ("VAULT_ENCRYPTION_KEY", "ENCRYPTION_KEY", "ADMIN_API_KEY"):
    print(f"{name}={secrets.token_hex(32)}")
PY

Set those three generated values in backend/.env. Also set:

DEV_AUTH_BYPASS=true
DEV_AUTH_TOKEN=dev-bypass

Run backend:

pdm migrate
pdm dev

Done: curl -sS http://localhost:8000/health returns {"status":"ok"}.

Terminal 2, web:

cd apps/web
cp .env.example .env.local

Set:

VITE_CLAWDI_API_URL=http://localhost:8000
VITE_DEV_AUTH_BYPASS=true
VITE_DEV_AUTH_TOKEN=dev-bypass

Run:

bun run dev

Done: http://localhost:3000 opens the dashboard without Clerk login.

Terminal 3, CLI:

export ADMIN_API_KEY="<value-from-backend-env>"
curl -sS -X POST http://localhost:8000/v1/admin/auth/keys \
  -H "X-Admin-Key: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"target_clerk_id":"dev_browser","label":"local-cli"}' \
  | jq -r .raw_key