{ "markdown": "# Foxhound\n\n**Scale targets** — 1B spans/day per customer · ingest p99 < 500 ms · trace query p95 < 2 s · dashboard query p95 < 300 ms.\n**Architecture tour** — [10-minute walk from SDK to dashboard](./docs/tour/README.md).\n**Scale readiness** — [live gap matrix](./docs/reference/scale-readiness.md) · [RFC index](./docs/rfcs/README.md).\n\nSource-available, self-hostable observability for AI agent fleets. Multi-tenant. OTel-compatible. Evaluators, Run Diff, Session Replay, cost budgets, SLA monitoring, behavior regression, CI quality gate.\n\n---\n\n
\n\n

\n \"FOXHOUND\n

\n\n### Compliance-grade observability for AI agent fleets.\n\nTrace every decision. Evaluate every response. Budget every dollar.\n\n

\n \"CI\"\n \"All\n \"npm\n \"npm\n \"PyPI\"\n

\n\n

\n Docs ·\n Live Sandbox ·\n Quickstart ·\n Tooling ·\n Self-Hosting ·\n Development\n

\n\n
\n\n---\n\n> **Licensing notice**\n> This repository is publicly visible for reference and evaluation only.\n> No permission is granted to use, copy, modify, distribute, sublicense, or sell this software without prior written permission from Caleb Love.\n> Licensing inquiries: hello@caleb-love.com\n>\n> See [LICENSE](./LICENSE) for full terms.\n\n## What is Foxhound?\n\nFoxhound is a source-available observability platform purpose-built for AI agent systems. Generic APM and logging tools do not model agent behavior well: tool calls, LLM invocations, branching workflows, replay, evaluation, and regression detection all get flattened into the wrong abstractions.\n\nFoxhound gives you the missing layer:\n\n- **trace every agent run** as a structured span tree\n- **compare executions** to see exactly where behavior diverged\n- **evaluate responses** with datasets, experiments, and LLM-as-judge workflows\n- **enforce budgets and SLAs** before costs and latency drift silently\n- **audit and isolate tenant data** for security-sensitive deployments\n\n**Not a generic logging product. AI agent observability.**\n\n## Sandbox\n\nThe sandbox is a self-contained demo workspace that tells a realistic seven-day story: a returns resolution agent regresses after a prompt rollout, gets detected through traces and regressions, is investigated via run diff and session replay, and recovers through a dataset-backed experiment.\n\nRun locally with no external dependencies:\n\n```bash\npnpm install\npnpm dev:web:demo\n# Open http://localhost:3001/sandbox\n```\n\nWhat you will see:\n\n- **Fleet Overview**: platform posture, operator focus items, and trend charts (Recharts)\n- **Traces**: 568 seeded traces with tree-structured span timelines, cost badges on LLM calls, and parent/child indentation\n- **Run Diff**: side-by-side comparison showing exactly where two agent runs diverged\n- **Session Replay**: step-through playback with play/pause, speed control, seek bar, and live state diff\n- **Regressions**: behavior drift detection by agent version with linked investigation paths\n- **Experiments**: dataset-backed evaluation with promotion-ready candidates\n- **Budgets and SLAs**: per-agent cost budgets and latency/reliability targets\n- **Prompts**: versioned prompt registry with label-based promotion and diff view\n- **Notifications**: alert routing to Slack, webhook, GitHub, Linear, PagerDuty\n- **Settings**: theme switcher, SDK ingestion simulator, CI quality gate demo\n- **Guided tour**: first-visit walkthrough with keyboard navigation (auto-shows once, re-trigger from the Tour button)\n- **Command palette**: `Cmd+K` for quick navigation across all surfaces\n- **Mobile responsive**: hamburger menu with slide-over drawer on small screens\n\n## Core capabilities\n\n| Area | What you get |\n| ---------------------- | ----------------------------------------------------------------------------------------- |\n| **Tracing** | Structured traces and spans for every run · trace explorer · metadata and event capture |\n| **Replay & Diff** | Session replay · run diff · trace timeline inspection |\n| **Evaluation** | LLM-as-judge evaluators · dataset curation from production traces · experiment comparison |\n| **Agent intelligence** | Cost budgets · SLA monitoring · regression detection by agent version |\n| **Prompt management** | Prompt templates · label-based promotion such as `staging` → `production` |\n| **Operations** | API keys · notifications · audit logging · multi-tenant isolation |\n| **Developer tooling** | TypeScript SDK · Python SDK · CLI · MCP server · GitHub quality gate |\n\n## Quickstart\n\n### 1. Clone and install\n\n```bash\ngit clone https://github.com/caleb-love/foxhound.git\ncd foxhound\npnpm install\n```\n\n### 2. Start local infrastructure\n\n```bash\ndocker compose -f docker-compose.dev.yml up -d\ncp apps/api/.env.example apps/api/.env\npnpm --filter @foxhound/db db:migrate\n```\n\n### 3. Run the app\n\n```bash\npnpm dev # API\npnpm dev:web # dashboard in another terminal\n```\n\nDefault local endpoints:\n\n- API: `http://localhost:3000`\n- Web: `http://localhost:3001`\n\n### 4. Send your first trace\n\n#### Python\n\n```bash\npip install foxhound-ai\n```\n\n```python\nfrom foxhound import FoxhoundClient\n\nfox = FoxhoundClient(\n api_key=\"fh-...\",\n endpoint=\"http://localhost:3000\",\n)\n\nasync with fox.trace(agent_id=\"support-agent\") as tracer:\n span = tracer.start_span(name=\"tool:search\", kind=\"tool_call\")\n span.set_attribute(\"query\", \"refund policy\")\n span.end()\n```\n\n#### TypeScript\n\n```bash\nnpm install @foxhound-ai/sdk\n```\n\n```ts\nimport { FoxhoundClient } from \"@foxhound-ai/sdk\";\n\nconst fox = new FoxhoundClient({\n apiKey: process.env.FOXHOUND_API_KEY!,\n endpoint: \"http://localhost:3000\",\n});\n\nconst trace = fox.trace({ agentId: \"support-agent\" });\nconst span = trace.startSpan({ name: \"tool:search\", kind: \"tool_call\" });\nspan.setAttribute(\"query\", \"refund policy\");\nspan.end();\nawait trace.flush();\n```\n\n## Tooling\n\n| Artifact | Install | Purpose |\n| ------------------ | ---------------------------------------- | -------------------------------------------------------------- |\n| **Python SDK** | `pip install foxhound-ai` | Instrument Python agent systems |\n| **TypeScript SDK** | `npm install @foxhound-ai/sdk` | Instrument Node.js / TypeScript runtimes |\n| **CLI** | `npm install -g @foxhound-ai/cli` | Inspect traces and operate Foxhound from the terminal |\n| **MCP Server** | `npm install -g @foxhound-ai/mcp-server` | Query Foxhound from Claude Code, Cursor, and other MCP clients |\n| **GitHub Action** | `caleb-love/foxhound-quality-gate` | Block PRs that fail eval or quality thresholds |\n\n## Architecture\n\n```text\nSDKs / OTLP -> API (Fastify) -> PostgreSQL\n |\n -> Worker (BullMQ) -> Redis\n -> Web dashboard (Next.js)\n```\n\nCurrent monorepo layout:\n\n```text\napps/api/ Fastify REST API\napps/web/ Next.js dashboard\napps/worker/ BullMQ workers\npackages/sdk/ TypeScript SDK\npackages/sdk-py/ Python SDK\npackages/cli/ CLI\npackages/mcp-server/ MCP server\npackages/api-client/ Typed API client\npackages/db/ Drizzle schema + queries\npackages/types/ Shared types\npackages/billing/ Billing + entitlements\npackages/notifications/ Notification delivery\n```\n\n## Self-hosting\n\nFoxhound is designed to run on your own infrastructure.\n\nMinimum stack:\n\n- PostgreSQL 16+\n- Redis\n- Node.js 20+\n- pnpm 9+\n\nPrimary local/dev commands:\n\n```bash\npnpm build\npnpm test\npnpm lint\npnpm typecheck\n```\n\nFor API configuration, see:\n\n- `apps/api/.env.example`\n\n## Security\n\nFoxhound is built for security-sensitive, multi-tenant environments.\n\nCurrent repo expectations include:\n\n- API keys hashed at rest\n- tenant-scoped data access via `org_id`\n- JWT auth for user-facing operations\n- audit logging for sensitive actions\n- rate limiting and security headers on the API/web surfaces\n\nIf you discover a vulnerability, use GitHub security advisories or follow `SECURITY.md` if present.\n\n## Development\n\n```bash\npnpm install\npnpm build\npnpm test\npnpm lint\npnpm typecheck\npnpm format\n```\n\nUseful dev commands:\n\n```bash\npnpm dev # API only\npnpm dev:web # web only\npnpm dev:all # API + web\npnpm --filter web verify # canonical web verification lane\n```\n\nFor the web preview surface, `/sandbox` is canonical and `/demo` is compatibility-only. See `apps/web/README.md` and `docs/reference/sandbox-compatibility-retirement-checklist.md`.\n\n## Contributing\n\nContributions are welcome.\n\n- open issues for bugs and feature requests\n- keep multi-tenant safety and security review standards high\n- prefer small, verifiable changes over broad speculative refactors\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) for contribution conventions.\n\n## License\n\nAll rights reserved. This repository is public for reference and evaluation only.\nNo permission is granted to use, copy, modify, distribute, sublicense, or sell this software without prior written permission.\nSee [LICENSE](LICENSE) and contact hello@caleb-love.com for licensing inquiries.\n", "bytes": 10556, "sha": "ddb23ce7f904a05fe6bbbd27554e0b27cf75240fa60e4a1a5df17b32fc0a26c4", "repo_slug": "caleb-love/foxhound", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_caleb_love_foxhound_37f6a584/readme" }