Case Study
A self-hosted REST API workspace for Claude AI agents — persistent memory, git-backed vaults, real-time response loops, and HMAC-signed webhooks.
Python API serving a React SPA, backed by PostgreSQL and Redis, all containerized in Docker Compose.
FastAPI with async SQLAlchemy 2.0 and asyncpg for non-blocking database access. Pydantic v2 for request/response validation. Alembic for migrations. GitPython for vault file operations with real git commits.
React 18 SPA built with Vite 6 and Tailwind CSS 4. TypeScript throughout. Dashboard with real-time agent event feed, resource stats, document editor, memory browser, and webhook management.
Multi-stage Dockerfile builds the React SPA then layers it into the Python image. PostgreSQL 16 for data, Redis 7 for caching and rate limiting, bare git repos for file vault storage. Automated backups.
A single Docker Compose stack running on a Proxmox LXC container, with a watcher service on a separate host that bridges the dashboard to Claude CLI.
Send a message from the dashboard and get a Claude response posted back to the feed in under 10 seconds — no browser extension, no API wrapper.
event_type: "user_message" and metadata.source: "dashboard"
claude -p --resume with the message as input. Runs on the same host as the Claude Code installation
event_type: "assistant_message"
Eight modules behind a consistent REST envelope. Every response wraps data in { success, data } with paginated list endpoints.
Git-backed file storage. Create repos, read/write/delete files (each producing a real git commit), browse directory trees, and query commit history. Branches supported.
Versioned document store with full-text search, template support, and tagging. Every edit creates a version snapshot for history and rollback.
Namespaced key-value store with optional TTL. Supports bulk operations, namespace export, direct key lookup, and search. Designed for agent context persistence across sessions.
Manage agent sessions with status tracking. Post events to agent feeds (messages, tool calls, system events) and query by time range or event type. Supports reordering.
Organize work into projects with task lists. Status tracking, priority ordering, and task assignment. Each project scopes agents and documents.
Subscribe to events with glob pattern matching. HMAC-SHA256 signed payloads, automatic retries with exponential backoff, delivery history, and auto-disable after 50 consecutive failures.
Production-grade event delivery with signed payloads, retry logic, and self-healing subscriptions.
Every payload is signed with HMAC-SHA256 using a per-subscription secret. Consumers verify via the X-ClaudeVault-Signature header. Secrets are generated at creation time and can be rotated.
Failed deliveries retry up to 3 times with exponential backoff. Retries are queued in Redis and processed by a background loop. After 50 consecutive failures, the subscription auto-disables to prevent noise.
| Event Pattern | Fires On |
|---|---|
| agent.* | Agent created, updated, or deleted |
| agent_event.created | New event posted to any agent feed |
| vault.* | File written or deleted in any repo |
| doc.* / memory.* | Document or memory entry mutations |
| project.* / task.* | Project or task lifecycle events |
| * | Wildcard — matches everything |
JWT with RSA-256, scoped API keys, role-based permissions, audit logging, and rate limiting.
Access tokens signed with RSA private key (30-min expiry). Refresh tokens last 7 days. Keys generated via OpenSSL and stored on a Docker volume.
Prefixed with cv_prod_ or cv_dev_. Support rotation without downtime. Scoped to the creating user's permissions. Used by the watcher and MCP server.
Three roles: admin (full access + user management), agent (read/write, no admin), viewer (read-only). Permissions checked on every request.
Every mutation is logged with user ID, action, resource, and metadata. Admin-queryable via GET /auth/audit with filters for user and action type.
Redis-backed sliding window: 60 requests/minute per user with a burst allowance of 10. Configurable via environment variables. Returns 429 with retry-after header.
A built-in Model Context Protocol server lets Claude Code interact with ClaudeVault directly — read/write memory, manage docs, browse vault files, and track projects without leaving the terminal.
The MCP server wraps the REST API using FastMCP. It authenticates with an API key and exposes tools for memory CRUD, document search, vault file operations, and project/task management. Add it to .mcp.json and Claude has full workspace access.
Every git push to the config repo triggers a post-receive hook that upserts all .md files as ClaudeVault documents tagged memory-file. An n8n workflow then fetches them all, sends to Claude Haiku for audit, and posts findings to Discord.