corvid/CLAUDE.md

corvid

⚠ DEPRECATED — 2026-06-16. Ticket management has moved to Domus (domus.welvaert.org, repo domus). The Domus tickets app reached corvid feature parity and now backs the homelab-tickets MCP, served over the network at domus-mcp.welvaert.org (authenticated with a Domus API key). corvid is retained read-only for historical data and reference — do not build new work on it. See domus/docs/rewrite/mcp.md.

Standalone ticket-management service for AI agents. FastAPI + Postgres + MCP server.

Extracted from homelab-dashboard — the homelab-dashboard app continues to use corvid as a pip package (Option A integration).

Package

corvid/
  models.py    — Ticket, TicketAttachment, Base (SQLAlchemy ORM)
  router.py    — make_router(api_key, get_db, require_user=None) → APIRouter
  config.py    — DATABASE_URL, TICKETS_API_KEY env vars
  main.py      — standalone FastAPI app (no web UI)
  database.py  — engine, get_db
alembic/       — migration chain for standalone deployments
mcp_server.py  — FastMCP server; primary agent interface

MCP server

mcp_server.py is the centralized homelab MCP server. It exposes:

• Ticket CRUD + attachments (via HOMEDASH_URL API)
• Homelab system logs (/api/logs)

Configure in ~/.claude/mcp.json:

"homelab-tickets": {
  "command": "python3",
  "args": ["/home/caoimhinr/Projects/corvid/mcp_server.py"],
  "env": {
    "HOMEDASH_URL":   "https://homedash.welvaert.org",
    "HOMEDASH_API_KEY": "<TICKETS_API_KEY>"
  }
}

TICKETS_API_KEY value is in pve/ansible/host_vars/hetzner.yml (gitignored).

Standalone deployment

cp .env.example .env   # set DATABASE_URL and TICKETS_API_KEY
docker compose up -d

Default port: 8090 (maps to internal 8080).

homelab-dashboard integration

The dashboard depends on corvid via Forgejo:

# requirements.txt
corvid @ git+https://forgejo.welvaert.org/caoimhinr/corvid.git@main

Local dev: pip install -e ~/Projects/corvid

Push corvid to Forgejo before rebuilding the dashboard image — the Docker build pulls @main at build time. See homelab-dashboard/CLAUDE.md for the full deploy procedure.

Local dev

pip install -e ".[dev,mcp]"
TICKETS_API_KEY="" DATABASE_URL="sqlite+aiosqlite:///dev.db" \
  uvicorn corvid.main:app --reload --port 8090

IaC sync

Corvid runs embedded inside the homelab-dashboard Docker image — it is not deployed as a standalone service via Ansible. However, its config surface (env vars, ports, API key) is reflected in pve/ansible/roles/homedash/templates/env.j2 and pve/ansible/host_vars/hetzner.yml. If corvid's env requirements change (new vars, renamed keys), update those files to prevent drift flagged by the compliance runner.

DB migrations

Alembic runs at startup (entrypoint.sh). Add new migrations in alembic/versions/ following the NNNN_<slug>.py naming convention.

The dashboard keeps its own separate migration chain — corvid's migrations are only for fresh standalone deployments.