Stack & deployment
Technology stack
Backend: Scala 2.13, Apache Pekko (actors and crash resilience), PostgreSQL, Redis (optional). LLM layer: multi-provider proxy (OpenAI, Anthropic, local models, custom base URLs). Frontend: React 18, TypeScript, Vite, MUI (Material UI), TanStack Query, React Router. Auth: Keycloak (JWT / OIDC) for the console and Admin API. Encryption: AES-256-GCM envelope encryption (typical SaaS: Tink + AWS KMS KEK; legacy direct KMS and self-hosted operator KEK also supported). Containerisation: Docker; frontend builds with Vite.
Configuration Reference
PlanVault is configured at two levels. Organisation settings define shared resources (providers, org tool catalog, OpenAPI Auto-Healer, MCP, knowledge providers, inbound webhooks, org-wide scenarios, secrets, models, spend and budgets subject to role, users, audit). Project settings control per-project models, LLM, retrieval, knowledge, tool integrations, **project** scenarios, secrets, Runtime keys, lifecycle webhooks, operations, and budget.
Organisation settings
Organisation settings sidebar (console order): General · Data export · Providers · LLM · Models (shown for roles with Developer access or higher) · Tools (org catalog) · OpenAPI Auto-Healer · MCP · Knowledge providers · Webhooks · Scenarios · Secrets · Users · Audit · Audit webhooks (**Owner/Admin only**) · Spend · Budget limit (Developer+). Some entries are hidden for lower roles.
Warning: budget limits
Project settings
Project settings sidebar (console order): General · Data export · Models · LLM · Tool retrieval · Knowledge · Debug: tools and plan (**Owner/Admin only**) · Tool integrations · Project scenarios · Secrets · Keys · Session lifecycle webhooks · Audit (**Owner/Admin**) · Operations (**Owner/Admin**) · Budget limit.
Note on planner modes
Deployment
PlanVault ships as containerised services (API, Keycloak, LLM proxy, PostgreSQL, optional Redis) for self-hosted operation; a managed SaaS deployment may also be available — architecture and security goals stay the same. Operators choose session-store modes and KMS wiring per environment.
Prerequisites: • Container runtime (Docker, Kubernetes, or equivalent) • JVM 21 for the published API image (Dockerfile.api uses Eclipse Temurin 21); local builds may use another compatible LTS JDK per your toolchain • Node.js 20+ (frontend build, or use the pre-built Docker image) • A Keycloak realm configured for PlanVault (realm name, client IDs) • LLM provider credentials (OpenAI, Anthropic, or a custom base URL for local models) • Key encryption key wiring for organisation DEKs depends on deployment mode (typical SaaS: **Tink** + AWS KMS KEK; legacy: direct KMS wrap; self-hosted: operator-managed KEK; local development may use a compatible KMS-like endpoint) plus a dedicated HMAC signing key
PlanVault can run in a private VPC with air-gapped LLM backends (e.g. Ollama via custom api_base in the LLM proxy layer). Enterprise deployments may include billing via AWS Marketplace for existing procurement budgets — confirm availability with your vendor or account team. For production hardening, see the production checklist and configuration reference in the repository documentation.
Troubleshooting
Execution and events
If execution looks stuck: check the SSE connection chip, enable debug mode with the event graph, or refresh and inspect the latest session events.
LLM, models, and tools
If the LLM rejected or oversimplified a plan: review the project system prompt, allowed models and quotas; reduce scenario complexity or tool count. If the wrong tools are shortlisted, check Tool retrieval (mode, thresholds), scenarios, and test-selection / Debug.