Worker container for the personal accounting agent. See the architecture spec: docs/superpowers/specs/2026-08-23-accounting-agent-architecture-design.md.

What it does (Phase 1)

On startup: creates agentdb in the stack's Postgres if missing, applies SQL migrations from src/agent/migrations/, runs one heartbeat, then schedules the heartbeat every HEARTBEAT_INTERVAL_MINUTES. The heartbeat calls Firefly's /api/v1/about and records the outcome in sync_runs.

Development

python3 -m venv .venv && source .venv/bin/activate
pip install -e './agent[dev]'
cd agent && pytest          # needs Docker running (testcontainers)

Configuration

All via environment variables (see .env.example, "Accounting Agent" section): FIREFLY_API_URL, AGENT_FIREFLY_TOKEN (required), AGENT_DB_NAME, HEARTBEAT_INTERVAL_MINUTES, plus the existing DB_HOST/DB_PORT/ POSTGRES_USER/POSTGRES_PASSWORD.

Deploy & verify

# on the host, in the repo directory
git pull
docker compose build agent
docker compose up -d agent
docker compose exec agent python -m agent.verify

Expected verify output: agentdb OK with migrations applied, recent heartbeat runs, Firefly version, and your asset accounts listed.

Inspect heartbeats directly:

docker compose exec db psql -U firefly -d agentdb \
  -c "SELECT connector, status, finished_at FROM sync_runs ORDER BY id DESC LIMIT 5;"