Skip to main content

​
Requirements

Docker with Compose v2, Python 3, and OpenSSL 1.1.1 or newer. The documented setup supports Linux and macOS. Allow time and disk space for the initial application build.
The setup command prompts for owner credentials and prints the initial API key once. Save it securely; subsequent owner setup runs cannot recover that key. Sign in at http://localhost:3000. Create a local API key in Settings → API keys. Keep the key private; SDK ingestion uses http://localhost:8000 and requires authentication. If a default port is occupied, run python3 scripts/init-env.py --origin http://localhost:3001 --api-port 8001 before starting, and use those ports throughout the walkthrough. Setup preserves an existing .env; change its port and origin values directly for an existing installation. The generated .env contains persistent instance and signing secrets, is ignored by Git, and has owner-only permissions. Re-running generation preserves it. PostgreSQL data persists across docker compose down and restart.

​
Pick a first workflow

  • Python: run a synthetic nested execution with a successful tool and a handled failure; inspect and export the result.
  • Claude Code: prepare the collector, install the plugin and capture an actual local session.
The default full-content Claude profile can store prompts, source and tool output. Reduced capture modes remain available. Missing content is reported as partial or unavailable.

​
First-run troubleshooting

Run docker compose ps -a and docker compose logs --tail=100 migrate api web. A migration error prevents startup. Setup refuses an unknown nonempty database rather than rewriting it. Use a fresh volume; the release does not migrate an existing hosted installation. If a port is already occupied, change FACT0_WEB_PORT, FACT0_API_PORT and the matching BETTER_AUTH_URL in .env, recreate the services with docker compose up -d --force-recreate --wait web api, and use the matching host API URL in your SDK/plugin. See operation and restore for backups, password reset, TLS and disk usage.