vaultagent-stack

Developer workspace for the VaultStack Open Source Ecosystem. Docker Compose, shared tooling, contribution guidelines, and a one-command setup to clone and bootstrap all sibling repositories.

---

The Ecosystem

Repository	Role	Key Technology
vaultagent-core	Governed AI engine — LangGraph agents, PII redaction, pgvector memory, HITL	Django 5 + Ninja API
vaultagent-desktop	Mac/Windows desktop app — menu bar, drop-to-index, HITL review UI	Tauri 2 + React
django-agent-governance	Reusable governance library — @redact_pii, @audit_llm_call, LLMProxy	Pure Django package
vaultagent-stack	Workspace orchestration — Docker Compose, Makefile, scripts	You are here

---

Local Directory Layout

All repos are siblings in the same parent directory:

~/your-workspace/
├── vaultagent-stack/ ← you are here
│ ├── docker-compose.yml ← Postgres + Redis + Core + Celery
│ ├── docker-compose.prod.yml ← Production overrides
│ ├── Makefile ← 30+ cross-repo shortcuts
│ ├── .env.example ← Template for all secrets
│ └── scripts/
│ ├── setup.sh ← Clone all repos
│ ├── full-dev.sh ← One-command bootstrap
│ ├── migrate.sh ← Run Django migrations
│ ├── seed.sh ← Seed fixtures + admin user
│ ├── healthcheck.sh ← Verify all services
│ └── init-db.sql ← Postgres extensions (pgvector etc.)
│
├── django-agent-governance/
├── vaultagent-core/ ← Dockerfile included
└── vaultagent-desktop/

---

Quick Start

Prerequisites

• Docker Desktop for Mac/Windows
• Ollama for local LLM (no API key needed)
• Python 3.11+
• Node.js 20+ (for the desktop UI)

1. Bootstrap Everything (New Developer)

# Clone this repo
git clone https://github.com/vaultagent/vaultagent-stack.git
cd vaultagent-stack
# Clone all sibling repos + start infra + migrate + seed
make full-dev

That's it. make full-dev will:

• Create your .env from .env.example with a generated secret key
• Start PostgreSQL (pgvector) and Redis via Docker
• Run all Django migrations
• Seed the default Agent and admin superuser

2. Pull a Local AI Model

ollama pull llama3.2:1b # Fast 1B model for testing
ollama pull nomic-embed-text # Required for RAG memory search

3. Start the Servers

# Terminal 1 — Core API (http://localhost:8001)
make core-dev
# Terminal 2 — Desktop UI
make desktop

---

Services

Service	URL	Notes
Core API	http://localhost:8001/api/v1/docs	Django Ninja auto-docs
Django Admin	http://localhost:8001/admin/	admin / admin (dev only)
pgAdmin	http://localhost:5050	make dev-tools to start
Flower (Celery)	http://localhost:5555	make dev-tools to start
Postgres	localhost:5432	vaultagent / vaultagent_dev_password
Redis	localhost:6379

---

Shared Commands

# Infrastructure
make dev-up # Start Postgres + Redis only
make dev-down # Stop all containers
make dev-tools # Add pgAdmin + Flower
make dev-reset # ⚠️ Destroy all containers AND volumes# Database
make migrate # Run Django migrations
make seed # Seed default agent + admin user
make health # Check health of all services# Dev Servers
make core-dev # vaultagent-core API (port 8001)
make desktop # Tauri desktop (dev mode)# Logs & Shells
make logs # Follow all logs
make logs-core # vaultagent-core logs only
make shell-db # psql shell in Postgres container
make shell-redis # redis-cli in Redis container
make shell-core # Django shell in vaultagent-core# Testing
make test-all # All repos
make test-core # vaultagent-core only (uses SQLite, no Docker needed)
make test-governance # django-agent-governance only# Code Quality
make lint-all # ruff + mypy + ESLint
make format-all # ruff format + prettier
make install-all # pip + npm install across all repos
make clean # Remove __pycache__, .pytest_cache, etc.# Docker
make build-core # Build vaultagent-core Docker image

---

Architecture

┌─────────────────────────────────────────────────────────┐
│ vaultagent-desktop │
│ (Tauri 2 + React — Menu Bar App) │
│ ChatWindow · HITLPanel · DropZone · PrivacyToggle │
└──────────────────────────┬──────────────────────────────┘
│ Tauri IPC → Rust → HTTP
│ localhost:8001
┌──────────────────────────▼──────────────────────────────┐
│ vaultagent-core │
│ (Django 5 + Django Ninja + LangGraph) │
│ /api/v1/chat/ /api/v1/hitl/ /api/v1/memory/ │
│ LangGraph: Memory→Redact→LLM→Risk→Audit→HITL │
└──────────────────────────┬──────────────────────────────┘
│ pip dependency (editable)
┌──────────────────────────▼──────────────────────────────┐
│ django-agent-governance │
│ @redact_pii · @audit_llm_call · LLMProxy │
│ PII Sovereign Vault · TokenBudget · LLMCallLog │
└──────────────────────────┬──────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────┐
│ vaultagent-stack (this repo) │
│ PostgreSQL + pgvector ← long-term memory │
│ Redis ← Celery broker + cache │
└─────────────────────────────────────────────────────────┘

---

Philosophy: Local-First, Cloud-Optional

VaultAgent defaults to zero cloud dependency:

# Default — works with Ollama, no wallet required
VAULTAGENT_LLM_BACKEND=ollama
# Enterprise — flip a single config flag
VAULTAGENT_LLM_BACKEND=openai # + OPENAI_API_KEY
VAULTAGENT_LLM_BACKEND=anthropic # + ANTHROPIC_API_KEY
VAULTAGENT_LLM_BACKEND=gemini # + GEMINI_API_KEY

---

Production Deployment

# Use the production compose override
cp .env.example .env
# Fill in real secrets in .env
docker compose \
-f docker-compose.yml \
-f docker-compose.prod.yml \
up -d

The production override adds:

• Gunicorn (4 workers) instead of Django's development server
• Resource limits on all containers
• Redis password enforcement
• HSTS and full security headers via Django production settings
• WhiteNoise for static file serving

---

Contributing

See CONTRIBUTING.md. All contributions welcome — whether it's a regex PII pattern, a new LLM backend, or a Tauri UI improvement.

---

Licenses

Repo	License
vaultagent-core	Apache 2.0
vaultagent-desktop	MIT
django-agent-governance	MIT
vaultagent-stack (this repo)	MIT