Operations
Codifix is local-first, but it still has operational concerns: service health, database availability, backups, logs, privacy, and upgrade safety. Use this page as a runbook, not a second copy of the troubleshooting guide.
Baseline
codifix health # backend service
codifix doctor # config and dependencies
codifix status --project <project-slug> # combined service, watcher, MCP, doctorRun these once at the start of an incident or change. After that, move to the relevant section below instead of repeating them.
Service
The service runs as a systemd unit on Linux or a launchd agent on macOS. Use standard OS tools to start, stop, and inspect it. See Service setup for initial configuration.
| Task | Command |
|---|---|
| Run in foreground for debugging | codifix service run |
| Enable packaged background service | codifix service enable |
| Inspect configured service | codifix service status |
| Restart known service components | codifix service restart-all |
| Regenerate or confirm API token | codifix service ensure-api-token |
The foreground run command is intentionally blocking. If it exits, the service is not running from that terminal.
Database
Codifix stores everything in PostgreSQL with pgvector. See PostgreSQL and pgvector for setup.
Backups and restore
What to back up
- PostgreSQL database.
- Global configuration.
- Repo-local
.codifix/project config. .agents/integration files if they are part of the project workflow.
Basic database backup
pg_dump "$DATABASE_URL" > codifix-backup.sql
psql "$DATABASE_URL" < codifix-backup.sqlFor production-grade backups, prefer custom-format dumps, checksums, restore tests, and a retention policy. Verify a restore by running codifix doctor against a disposable database.
Do not commit secrets, API keys, local database URLs, or runtime state.
Upgrades
Codifix v2.0.0 is a breaking upgrade from v1. Follow the v2 Update guide for removed config keys, renamed commands, API changes, package-specific install steps, migrations, and rollback. The sequence below is the shorter runbook for routine updates within a compatible release line.
Before upgrading, take a baseline and back up the database:
pg_dump "$DATABASE_URL" > codifix-before-upgrade.sqlAfter upgrading:
codifix service restart-all
codifix doctor
codifix health
codifix status --project <project-slug>
codifix upgrade --dry-runRun codifix upgrade inside repositories only after reviewing the dry run, because it can refresh .agents/ and other repo-local integration files.
Logs and diagnostics
| Surface | Use it for |
|---|---|
codifix doctor | Configuration, database, provider, and environment checks. |
codifix status --project <slug> | Combined project, service, watcher, MCP, and health view. |
codifix loops runs --project <slug> | Automation run ledger and recent loop outcomes. |
| TUI Errors tab | Persisted diagnostics with fix hints and raw errors. |
| Web UI Errors tab | Same diagnostic model in a browser surface. |
| OS service logs | Startup failures, migrations, port conflicts, crashes. |
Redact provider tokens, database URLs, prompts, and local file paths before sharing logs publicly.
Security and privacy
Codifix can be local-first, but external embedding or LLM providers may receive text depending on your configuration.
Check before enabling integrations
- Which database stores project memory?
- Which LLM provider is configured?
- Which embedding provider is active?
- Is MCP HTTP local and token-protected?
- What does the watcher capture?
- Are logs redacted before sharing?
Do not expose the service or MCP HTTP route directly to the public internet. For remote multi-user access, enable Authentik mode, terminate HTTPS at a trusted reverse proxy, keep service-token clients scoped, and add network controls. HTTP MCP remains cookie-blind and needs its own service token.
Multi-project use
One backend serves multiple projects. Each project has its own slug, config, watchers, and scoped queries. Use codifix status --project <slug> to inspect each one independently.
Web UI
The Web UI is served by the same local service. Use it when you need a wider inspection surface for memories, query evidence, activities, review proposals, errors, embeddings, and resume briefings.
Keep the service bound to local interfaces unless you have explicitly configured Authentication and access, HTTPS, trusted proxy behavior, and network controls.
Automations
The Automations control plane is service-owned. Treat it like an operational surface: inspect settings before enabling loops, prefer dry-runs when exploring outputs, and review approval requests before accepting memory or repository changes.
Next
Read Automations, Reference, Troubleshooting, or MCP.