AI Decision System
Replayable, offline-verifiable records for AI-assisted go/no-go decisions: experiment promotions, typed model answers and human-approved actions.
The AI troubleshooting copilot that works a problem like a seasoned engineer — goal-driven, methodical, evidence-based, and self-learning. Self-host via Docker or scale with FaultMaven Cloud.
Developer toolsPython · ShellGitHub @FaultMavenOnlineOwner unconfirmed
Have you tried it? One tap is enough. No sign-in needed.
No updates detected yet. GitHub releases will appear here.
Owners of public repositories under a personal GitHub account can sign in to verify ownership and manage the introduction themselves. No administrator approval is needed.
Sign in, generate a verification file, and commit it to this repository’s default branch within 30 minutes. Files on other branches or forks do not count. Then check the file below to manage the project without administrator approval. Keep the file to retain your access.
If needed, you will go to sign-in. After signing in, return here and press your chosen verification button again.
Run /nomorevibe verify in your project folder to verify ownership and manage the introduction yourself.
Verify in one minuteAsk about other verification options
The core API and orchestration layer for FaultMaven, connecting the browser extension and dashboard to your infrastructure and LLMs.
Taken from the repository README
Loading the full README. The saved excerpt is shown below.
AI Troubleshooting Copilot for Modern Engineering.
Built to solve, not to chat — fair-source, self-hostable, and optimized for cloud scale.
FaultMaven is an AI-powered troubleshooting copilot. It correlates the logs, metrics, and configs you share with runbooks, documentation, and past fixes to deliver contextual AI-driven incident investigation — answers grounded in your actual system, not generic guesses.
FaultMaven works a problem the way a seasoned engineer does — and never forgets what it learns:Read the full README ↗AI Troubleshooting Copilot — run it yourself, or let us run it for you. Same engine either way: fair source (FSL-1.1-ALv2), self-hostable, and on FaultMaven Cloud with nothing to operate.
FaultMaven is an AI-powered troubleshooting copilot. It correlates the logs, metrics, and configs you share with runbooks, documentation, and past fixes to deliver contextual AI-driven incident investigation — answers grounded in your actual system, not generic guesses.
FaultMaven works a problem the way a seasoned engineer does — and never forgets what it learns:
Traditional observability tools tell you what broke. Generic LLMs guess why, but can't see your infrastructure. FaultMaven bridges this gap. Where predictive AIOps platforms act like actuaries — forecasting next quarter's outage probabilities from historical patterns — FaultMaven is the ER surgeon for systems already on the table.
This repository is the engine. There are two ways to run it, and it is the same engine either way — so whichever you choose, you are never locked in.
| Let us run it | app.faultmaven.ai — FaultMaven Cloud: nothing to install or operate, plus team knowledge sharing. In beta: free, with a daily limit on investigation turns |
| Run it yourself | Quick Start — one command, free forever, fair source (FSL-1.1-ALv2). Your cases, evidence and knowledge base stay on your hardware |
| Just look | A complete investigation transcript, unedited — or join the Community Slack and @mention FaultMaven. Neither needs an account |
Self-hosting is subject to none of this except the first point, which is a property of language models rather than of the deployment.
FaultMaven consists of an API and three ways to reach it:
| Component | Repository | Purpose |
|---|---|---|
| FaultMaven API | This repo | Backend server: investigation engine, knowledge base, AI orchestration |
| FaultMaven Dashboard | faultmaven-dashboard | Web UI: knowledge base management, case history, settings |
| FaultMaven Copilot | faultmaven-copilot · Chrome Web Store | Browser extension: in-context troubleshooting overlay |
| FaultMaven Slack Agent | faultmaven-slack-agent · Community Slack | Answers in the incident thread |
Typical usage: the Dashboard is the full product in a browser tab, and works end to end on its own. The Copilot extension puts the same investigation beside whatever page you are reading. The Slack agent answers where the incident is already being discussed. All three talk to the API backend.
One command. Budget 10–20 minutes on a first run — most of it pulling a 2.3 GB image that carries its own embedding model, which is what lets FaultMaven index and retrieve with no network at all. Subsequent starts take seconds.
# Clone the repository
git clone https://github.com/FaultMaven/faultmaven.git
cd faultmaven
# Configure your LLM provider — the ONLY thing you must set
cp .env.example .env
# Edit .env: set ONE provider's API key (e.g. GEMINI_API_KEY / OPENAI_API_KEY /
# ANTHROPIC_API_KEY). Everything else uses documented defaults, and the auth
# secret is auto-generated on first run.
# Start API + Dashboard (pulls pre-built images from GitHub Container Registry)
# This AUTOMATICALLY creates the database and a default admin user.
./faultmaven.sh start
# Or: docker compose up -d
What happens:
./data.admin / [email protected]First run is slower because of the one-time image pull. After that, startup is ~1 minute and needs no internet access for the embedding model or KB. Investigation turns still call the LLM provider you configured.
CHAT_PROVIDER=local with LOCAL_LLM_URL points FaultMaven at a self-hosted
OpenAI-compatible endpoint (vLLM, or Ollama's /v1). The provider is wired in
and its tool-calling check reads the endpoint rather than the model name, but
we have not yet verified a full investigation end to end on an open-weights
model, and local endpoints are best-effort for the structured output the
engine depends on. Until a tested configuration is published here, use a hosted
provider with strict structured output (Gemini, OpenAI, Anthropic) for
CHAT_PROVIDER. If you try a local model, we want to hear how it went.
adminThat's it! You are ready to go.
If you need more accounts, you can create them via CLI:
./faultmaven.sh create-user
http://localhost:8090The store build is the right one for self-hosting — it ships the presets and host permissions for a local or LAN backend. Self-hosting is about where this server runs, not which extension you install. Prefer to build it yourself? See the Copilot repository.
Once logged in, go to LLM Settings in the Dashboard sidebar to verify your provider is connected:
Note: LLM settings configured through the Dashboard are persisted in the database and take precedence over
.envvalues. The.envfile provides the initial configuration on first startup.
Convenient scripts for managing the Docker-based stack:
# Main CLI for Docker-based deployment
./faultmaven.sh start # Start services
./faultmaven.sh start --demo # Start with demo data
./faultmaven.sh health # Check service health
./faultmaven.sh logs # View all logs
./faultmaven.sh logs api # View specific service logs
./faultmaven.sh restart # Restart all services
./faultmaven.sh stop # Stop all services
./faultmaven.sh clean # Remove containers (PROTECTS ./data)
./faultmaven.sh clean --wipe-data # Remove containers AND delete all data
By default the stack runs pre-built images from GHCR (ghcr.io/faultmaven/faultmaven and …/faultmaven-dashboard). Pin versions with FM_IMAGE_TAG / FM_DASHBOARD_IMAGE_TAG in .env, or refresh to the latest published images with ./faultmaven.sh start --pull.
Building from source (contributors):
./faultmaven.sh start --build # Build the API from this repo, then start
./faultmaven.sh start --build-dashboard # Also build the Dashboard from ../faultmaven-dashboard
--build-dashboard needs the Dashboard repo checked out alongside this one (git clone https://github.com/FaultMaven/faultmaven-dashboard.git ../faultmaven-dashboard). For pure backend development without Docker, use ./scripts/faultmaven-dev.sh start.
| Component | URL | Description |
|---|---|---|
| Dashboard | http://localhost:3333 | Web UI for KB management, case history, LLM settings |
| API | http://localhost:8090 | REST API |
| API Docs | http://localhost:8090/docs | Interactive OpenAPI documentation |
For contributors or debugging, you can run the components as local processes instead of Docker.
1. Start the API Backend:
# Start API as local process
./scripts/faultmaven-dev.sh start
# Verify it's running
./scripts/faultmaven-dev.sh health
The API will be available at http://localhost:8090
2. Start the Dashboard (separate process):
The dashboard is in a separate repository. To run it locally:
# Clone the dashboard repository (if not already cloned)
git clone https://github.com/FaultMaven/faultmaven-dashboard.git
cd faultmaven-dashboard
# Install dependencies
npm install
# Or: pnpm install
# Configure API endpoint (optional - defaults to http://localhost:8090)
cp .env.example .env
# Edit .env if needed: VITE_API_URL=http://localhost:8090
# Start the development server
npm run dev
# Or: pnpm dev
The dashboard will be available at http://localhost:5173 (Vite dev server) and will connect to the API at http://localhost:8090.
Note: Make sure the API backend is running before starting the dashboard. The dashboard requires the API to be available at
http://localhost:8090.
Convenient scripts for managing the local development environment:
# For contributors developing FaultMaven
./scripts/faultmaven-dev.sh start # Start API as local process
./scripts/faultmaven-dev.sh stop # Stop the API
./scripts/faultmaven-dev.sh restart # Restart the API
./scripts/faultmaven-dev.sh health # Run comprehensive health checks
./scripts/faultmaven-dev.sh logs # Stream application logs
./scripts/faultmaven-dev.sh test # Run tests (delegates to scripts/tests.py)
For more detailed setup instructions, see Development Setup.
FaultMaven is not a chatbot wrapper; it is a context-aware investigation engine, built to solve, not to chat — and designed to get smarter with every incident. It is a copilot, not an autopilot: every step it suggests is yours to run, review, or reject. You stay in command of the keyboard.
Generic chatbots can't access your logs, configs, or deployments. FaultMaven correlates your full stack context—connecting errors with recent changes, configuration drift, and system state to find root causes faster.
Example: A Kubernetes pod is crashlooping. ChatGPT gives generic advice. FaultMaven analyzes your pod logs alongside deployment YAMLs and recent changes—then identifies that a ConfigMap update 2 hours ago introduced an invalid environment variable.
Stop copying errors between browser tabs. The FaultMaven Copilot browser extension overlays AI troubleshooting directly onto your existing tools—AWS Console, Datadog, Grafana, or localhost. No backend agents, webhooks, or complex integrations required. Because the Copilot lives in your browser, it never asks for production API keys, root credentials, or read/write access to your live systems — you supply the context it sees, nothing more.
How it works: FaultMaven lives in your browser, not your cluster. As you view logs in CloudWatch, traces in Datadog, or pods in the Kubernetes dashboard, the Copilot extension captures the relevant context and correlates it with your Knowledge Base in real-time.
Most troubleshooting knowledge is lost once the incident is closed. FaultMaven turns that lost data into a growing asset through a "Seed & Grow" lifecycle:
FaultMaven investigates methodically — verify the symptom, form hypotheses, test them against evidence, then fix — and never jumps to conclusions. But methodical doesn't mean rigid: it uses an opportunistic investigation approach where the agent completes tasks based on data availability rather than following rigid sequential phases.
Core Principles:
Case Lifecycle: INQUIRY → INVESTIGATING → RESOLVED / CLOSED
Key Components:
FaultMaven is architected to be model-agnostic, giving you the freedom to choose the best intelligence for your specific needs and budget.
It supports a wide variety of backends, including:
FaultMaven runs on a single, deployment-agnostic Core. The same engine powers two deployment architectures — what differs is the infrastructure footprint and who operates it, not the investigation engine itself. The Core is source-available (FSL-1.1-ALv2) in every mode.
Best for: Engineers who want FaultMaven on their own hardware, contributors, and anyone who wants to audit exactly what runs.
Standalone is a monolithic, single-instance deployment you run on your own hardware — directly as a server process or inside a Docker container. It ships with fixed, simple defaults (SQLite, in-process FakeRedis, embedded ChromaDB) so getting started is "pick an LLM provider, paste a key, go."
.env file.Follow the Quick Start guide above to get up and running.
Best for: Individuals and teams who would rather use FaultMaven than operate it.
Cloud is FaultMaven run for you: the same engine as Standalone, with nothing to install or operate, plus team knowledge sharing. In beta it is free, with a daily limit on investigation turns; pricing will be announced before general availability. Because the engine is fair source, you are never locked in — you can run the same engine yourself at any time.
"Cloud" describes the architecture, not the location. The same cloud-native deployment can run in public cloud (AWS/GCP/Azure) or on-prem as a private cloud.
| Feature | Standalone (Self-Hosted) | Cloud (FaultMaven-Hosted) |
|---|---|---|
| Configuration | Single-User / Docker | Multi-User / Managed K8s |
| Knowledge Base Start State | Ships with the global runbook pack | Ships with the global runbook pack |
| Knowledge Scopes | Global + Personal | Global + Team + Personal (team sharing) |
| LLM Configuration | Dashboard-managed (single provider, BYOK) | Dashboard-managed (multi-provider fallback chain, hot-reload) |
| Case Management | Full (with archive) | Full (with archive + org-wide view) |
| User Management | Not applicable (single user) | Full CRUD, invite, roles |
| Infrastructure | Fixed defaults (SQLite, FakeRedis, embedded ChromaDB) | Fully Managed (Postgres, Redis, S3) |
| Security | Local Auth | SSO (SAML/OIDC), enterprise isolation (RLS), teams |
| Session Persistence | Ephemeral (FakeRedis, resets on restart) | Persistent (Redis, saved across sessions) |
| Access | http://localhost:3333 (localhost only) | https://app.faultmaven.ai |
Cloud beta is open — sign up at app.faultmaven.ai with your email. Free while it is in beta, with a daily limit on investigation turns; pricing will be announced before general availability.
FaultMaven is a monolithic application with clean Vertical Slice Architecture. Instead of separating by technical layers (Controller, Service, Dao), we organize by Feature Modules.
Browser Extension / Dashboard
|
HTTPS
v
+------------------------------------------------------------------+
| FaultMaven API (8090) |
| |
| +------------------------------------------------------------+ |
| | API Layer | |
| | /api/v1/agent /api/v1/cases /api/v1/knowledge ... | |
| +------------------------------------------------------------+ |
| | Service Layer | |
| | AgentService CaseService KnowledgeService AuthService | |
| +------------------------------------------------------------+ |
| | Infrastructure Layer | |
| | LLM Router Persistence Security Observability | |
| +------------------------------------------------------------+ |
+------------------------------------------------------------------+
| | |
v v v
+--------+ +---------+ +----------+
| Redis | |ChromaDB | | SQLite/ |
| (opt) | |(Vectors)| | Postgres |
+--------+ +---------+ +----------+
| Module | Description |
|---|---|
agent | Investigation orchestration, AI tools |
auth | Users, sessions, organizations, teams, RBAC |
case | Investigation cases and lifecycle management |
evidence | Evidence storage, linking, and retrieval; file storage adapters (raw uploads land in uploaded_files via case turns) |
knowledge | Embeddings, vector search, RAG, knowledge items |
report | Report generation and recommendations |
faultmaven/
├── faultmaven/ # Main application
│ ├── main.py # FastAPI entry point
│ ├── api/ # Shared API middleware, dependencies
│ ├── modules/ # Vertical slice feature modules
│ │ ├── agent/ # Investigation + AI tools
│ │ ├── auth/ # Authentication + authorization
│ │ ├── case/ # Case management
│ │ ├── evidence/ # Evidence/file handling
│ │ ├── knowledge/ # Knowledge base + RAG
│ │ └── report/ # Reporting
│ ├── config/ # Settings (single env-read point)
│ ├── container/ # Dependency injection
│ ├── infrastructure/ # Shared adapters (LLM, DB, storage)
│ ├── core/ # Core domain logic
│ └── services/ # Service layer
├── tests/ # Test suite
│ ├── unit/
│ ├── integration/
│ ├── health/
│ └── performance/
├── docs/ # Documentation
├── alembic/ # Database migrations
├── faultmaven.sh # Docker CLI wrapper (start/stop/health/logs)
├── docker-compose.yml # Local services
├── Dockerfile # Container image
├── pyproject.toml # Dependencies and tools
└── .env.example # Configuration template
Create a .env file from the template:
cp .env.example .env
FaultMaven has two configuration layers:
| Layer | What it configures | How to change |
|---|---|---|
Environment (.env) | Infrastructure: database, auth mode, Redis, CORS, ports | Edit .env file, restart the server |
| Dashboard (DB-backed) | LLM settings: provider, API keys, fallback chain | Change via Dashboard UI, takes effect immediately |
On first startup, LLM settings are loaded from .env. Once you modify them through the Dashboard, the database becomes the source of truth for LLM configuration. Infrastructure settings always come from .env.
.env)| Category | Variables | Description |
|---|---|---|
| Database | DATABASE_URL | SQLite (default) or PostgreSQL |
| Sessions | REDIS_HOST, REDIS_URL | FakeRedis (default) or real Redis |
| Vectors | VECTOR_STORAGE_TYPE, CHROMADB_URL | chromadb (default, local PersistentClient); set CHROMADB_URL for an external server |
| Security | JWT_SECRET_KEY, CORS_ALLOW_ORIGINS | Auth and CORS settings |
See .env.example for all options with detailed comments.
Set your initial LLM provider in .env:
# Select primary provider
CHAT_PROVIDER=openai # openai, anthropic, fireworks, gemini, groq, cohere, huggingface, openrouter, local
# Add API key for your provider
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
FIREWORKS_API_KEY=fw-...
GROQ_API_KEY=gsk-...
COHERE_API_KEY=xxx
HUGGINGFACE_API_KEY=hf_...
OPENROUTER_API_KEY=sk-or-...
# Optional: Separate providers for specific tasks
MULTIMODAL_PROVIDER=gemini # Visual evidence processing
SYNTHESIS_PROVIDER=openai # RAG document queries
After the first startup, you can manage all LLM settings (provider, API keys, fallback chain) through the Dashboard > LLM Settings page. Changes are hot-reloaded — no server restart required.
Fallback Chain: Primary provider -> Fireworks -> OpenAI -> Local
# Run all tests (local dev runner)
./scripts/faultmaven-dev.sh test
# Run a subset
./scripts/faultmaven-dev.sh test --unit
# Or use pytest directly
pytest tests/unit/
pytest --cov=faultmaven
# Linting — the same line CI runs. Do not add `--select`: it REPLACES
# [tool.ruff.lint].select in pyproject.toml rather than narrowing it.
ruff check faultmaven/ tests/
# Formatting — CI runs `black --check faultmaven/ tests/`. Import sorting is
# ruff's `I` rules (ruff replaced isort in #179); do not run `isort`.
black faultmaven/ tests/
# Type checking (not a CI gate; `ignore_errors = true` in pyproject.toml)
mypy faultmaven/
# Create migration
alembic revision --autogenerate -m "description"
# Apply migrations
alembic upgrade head
| Layer | Technologies |
|---|---|
| Framework | Python 3.11.5+, FastAPI, Uvicorn, AsyncIO |
| LLM/AI | OpenAI, Anthropic, Fireworks, Gemini, Groq, Cohere, HuggingFace, OpenRouter |
| Database | SQLAlchemy 2.0, SQLite (standalone), PostgreSQL (cloud), Alembic |
| Vector DB | ChromaDB, sentence-transformers |
| Cache | Redis (cloud), FakeRedis (standalone — full API parity) |
| Auth | JWT (PyJWT), bcrypt, RBAC |
| Observability | Opik tracing, Prometheus metrics, structlog |
| Testing | pytest, pytest-asyncio, pytest-cov |
FaultMaven provides two frontend interfaces. For setup instructions, see Quick Start or Local Development Setup.
FaultMaven Dashboard - Web application for proactive knowledge management:
FaultMaven Copilot — browser extension for reactive troubleshooting, available on the Chrome Web Store:
For development or customization, see the respective repositories:
| Document | Description |
|---|---|
| docs/README.md | Documentation index |
| docs/architecture/ | System design and ADRs |
| docs/guides/ | How-to guides |
| docs/development/ | Development standards |
| docs/operations/ | Runbooks and monitoring |
See docs/CONTRIBUTING.md for:
FSL-1.1-ALv2 (Functional Source License) — source-available, converting to Apache-2.0 two years after each release. See LICENSE for details.