Vapora/provisioning/README.md

VAPORA Provisioning Configuration

Complete configuration system for deploying VAPORA using typedialog (interactive forms) and nickel (configuration generation).

Quick Start

Generate Configuration via Interactive Form

# Start interactive setup wizard
typedialog \
  --form .typedialog/vapora/forms/vapora-main-form.toml \
  --output config/runtime/vapora.custom.toml

This generates a customized TOML configuration based on your answers.

Use Predefined Deployment Profiles

# Copy example for your deployment mode
cp config/examples/vapora.solo.example.toml config/runtime/vapora.toml

# Or use Nickel to generate
nickel export config/examples/vapora.solo.example.ncl > config/runtime/vapora.json

Directory Structure

provisioning/
├── config/
│   ├── examples/              # Reference configurations for all modes
│   │   ├── vapora.solo.example.toml
│   │   ├── vapora.solo.example.ncl
│   │   ├── vapora.multiuser.example.toml
│   │   ├── vapora.multiuser.example.ncl
│   │   ├── vapora.enterprise.example.toml
│   │   └── vapora.enterprise.example.ncl
│   └── runtime/               # Active configuration (generate or copy here)
│       └── .gitkeep
│
├── schemas/
│   ├── vapora/                # VAPORA service schemas
│   │   ├── main.ncl           # Main unified configuration
│   │   ├── backend.ncl        # Backend (Axum REST API)
│   │   ├── agents.ncl         # Agents with learning profiles
│   │   └── llm-router.ncl     # LLM Router with cost tracking
│   │
│   └── platform/
│       ├── common/
│       │   └── helpers.ncl    # Configuration composition utilities
│       └── defaults/
│           └── deployment/
│               ├── solo.ncl           # Solo mode (dev)
│               ├── multiuser.ncl      # Multiuser (team)
│               └── enterprise.ncl     # Enterprise (production)
│
└── .typedialog/
    └── vapora/
        └── forms/
            ├── vapora-main-form.toml           # Main form with all settings
            └── fragments/                      # Modular form fragments
                ├── backend/
                │   └── auth.toml               # Auth config fragment
                ├── agents/
                │   └── learning-profiles.toml  # Learning & KG config
                ├── llm-router/
                │   └── budget-enforcement.toml # Budget config
                └── frontend/

Deployment Modes

1. Solo (Development)

Local development with minimal resources:

• CPU: 2 cores
• Memory: 2GB
• Storage: /tmp/vapora (ephemeral)
• Database: Local file-based SurrealDB
• Coordination: No NATS (single process)
• Cost tracking: Disabled
• Security: JWT only, no TLS

Use for:

• Local development
• Testing features
• PoC deployments
• Single-user testing

Generate:

cp config/examples/vapora.solo.example.toml config/runtime/vapora.toml
typedialog --form .typedialog/vapora/forms/vapora-main-form.toml --output config/runtime/vapora.toml

2. Multiuser (Team)

Team collaboration with shared infrastructure:

• CPU: 4-8 cores
• Memory: 8-16GB
• Storage: /var/lib/vapora (persistent)
• Database: Remote SurrealDB (WS protocol)
• Coordination: NATS JetStream cluster
• Cost tracking: Enabled (per-role budgets)
• Security: TLS, MFA, audit logging

Features:

• Multi-tenant support with workspaces
• Learning profiles for agent improvement
• Cost optimization with budget enforcement
• Swarm coordination for balanced task distribution
• Knowledge graph retention: 30 days

Use for:

• Team development environments
• Staging deployments
• Department-scale rollouts
• Cost-controlled production (small teams)

Generate:

cp config/examples/vapora.multiuser.example.toml config/runtime/vapora.toml
# Edit as needed for your infrastructure

3. Enterprise (Production)

Large-scale production with HA and observability:

• CPU: 16+ cores (distributed)
• Memory: 32GB+ (distributed)
• Storage: High-availability persistent storage
• Database: SurrealDB cluster with replication
• Coordination: NATS JetStream cluster
• Cost tracking: Aggressive (detailed per-token)
• Security: Full TLS, MFA, audit logging, RBAC
• Observability: Prometheus metrics, OpenTelemetry tracing

Features:

• Multi-region deployment support
• All LLM providers enabled (Claude, OpenAI, Gemini, Ollama)
• Aggressive cost optimization with multi-provider fallback
• 90-day knowledge retention for enterprise learning
• Enterprise-grade backup strategy (6-hour intervals)
• Full distributed tracing and metrics

Use for:

• Production deployments (any scale)
• Multi-region rollouts
• Enterprise customers
• Mission-critical systems

Generate:

cp config/examples/vapora.enterprise.example.toml config/runtime/vapora.toml
# Customize for your infrastructure (TLS certs, domains, etc.)

Configuration Layers

1. Schema Layer (.schemas/)

Defines the structure and types for all configurations:

• Main schema (vapora/main.ncl) - Unified service configuration
• Service schemas - Backend, Agents, LLM Router specifics
• Deployment schemas - Mode-specific defaults (solo, multiuser, enterprise)

Example:

# Backend schema defines structure
{
  host | String | doc "Bind address" | default = "0.0.0.0",
  port | Number | doc "Port" | default = 8001,
  workers | Number | doc "Worker threads" | default = 4,
  # ... more fields
}

2. Form Layer (.typedialog/)

Interactive forms for configuration generation:

• Main form - Complete VAPORA setup wizard
• Fragment forms - Modular forms for specific features (auth, budgets, learning)

Example:

[[elements]]
name = "backend_port"
nickel_path = ["vapora", "backend", "port"]
prompt = "Backend Port"
default = 8001
type = "number"

3. Configuration Layer (config/)

Generated or manually-customized configurations:

• Examples - Reference configs for all modes (TOML + Nickel)
• Runtime - Active configurations (generated from forms or copied from examples)

Key Configuration Concepts

Cost-Aware LLM Routing

Budget enforcement per role with automatic fallback:

[llm_router.budget_enforcement]
enabled = true
window = "monthly"

[llm_router.budget_enforcement.role_limits]
architect_cents = 500000      # $5000/month
developer_cents = 300000      # $3000/month
reviewer_cents = 200000       # $2000/month
testing_cents = 100000        # $1000/month

When budget is exceeded:

1. Alert threshold triggered (80% default)
2. Automatic fallback to cheaper provider
3. Cost report generated
4. Manual intervention available

Learning-Based Agent Selection

Agents improve with execution history:

[agents.learning]
enabled = true
recency_window_days = 7       # Weight recent tasks 3x higher
recency_multiplier = 3.0

[agents.learning.scoring]
load_weight = 0.3             # 30% on agent load
expertise_weight = 0.5        # 50% on expertise profile
confidence_weight = 0.2       # 20% confidence (prevents overfitting)

Knowledge Graph

Temporal execution history with learning curves:

[agents.knowledge_graph]
enabled = true
retention_days = 90           # Keep 90 days of history
causal_reasoning = true       # Understand task relationships
similarity_search = true      # Recommend past solutions

Customization Guide

Modify Backend Settings

Edit schemas/vapora/backend.ncl:

# Change default port
backend = {
  port | Number | default = 9001,
  # ... other fields
}

Or in config/runtime/vapora.toml:

[backend]
port = 9001

Add New Service

1. Create schema: schemas/vapora/newservice.ncl
2. Add to main schema: schemas/vapora/main.ncl
3. Create form: .typedialog/vapora/forms/fragments/newservice/
4. Update examples in config/examples/

Override Mode Defaults

Use Nickel composition in config/runtime/vapora.custom.ncl:

let defaults = import "../../schemas/vapora/main.ncl" in
let mode = import "../../schemas/platform/defaults/deployment/enterprise.ncl" in

let customizations = {
  backend.port = 9001,
  llm_router.budget_enforcement.window = "weekly",
} in

std.record.merge defaults (std.record.merge mode customizations)

Deployment

Via Docker Compose

Use generated config with docker-compose:

# Generate config
cp config/examples/vapora.multiuser.example.toml config/runtime/vapora.toml

# Start services (requires docker-compose.yml that reads this config)
docker compose up -d

Via Kubernetes

Convert Nickel to Kubernetes manifests:

# Export config as JSON
nickel export config/runtime/vapora.multiuser.ncl > config/runtime/vapora.json

# Use ConfigMap in K8s
kubectl create configmap vapora-config --from-file=vapora.json

Via Provisioning Script

Use Nushell scripts to apply configuration:

# Read config and validate
nu scripts/deploy-vapora.nu \
  --config config/runtime/vapora.toml \
  --mode multiuser

Validation

Validate Nickel Configuration

# Type check
nickel typecheck config/runtime/vapora.custom.ncl

# Export to JSON
nickel export config/runtime/vapora.custom.ncl > vapora.json

# Validate JSON structure
jq . vapora.json

Validate TOML Configuration

# Use toml-cli or similar
toml-cli validate config/runtime/vapora.toml

# Or via Rust
cargo build -p vapora-backend --features config-validation

Test Configuration

# Dry-run backend with config
cd ../../crates/vapora-backend
cargo run --features dry-run -- --config ../../provisioning/config/runtime/vapora.toml

Environment Variables

Override configuration values with environment variables:

# Backend
export VAPORA_BACKEND_PORT=9001
export VAPORA_BACKEND_WORKERS=8

# Database
export SURREAL_URL=ws://surrealdb:8000
export SURREAL_USER=root
export SURREAL_PASS=secret

# Agents
export VAPORA_AGENTS_MAX_INSTANCES=20

# LLM Router
export VAPORA_ROUTER_BUDGET_ENABLED=true

# Providers
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

Security Considerations

Solo Mode

• ⚠️ No TLS (HTTP only)
• ⚠️ No MFA
• ⚠️ Local storage (not backed up)
• Use only for local development

Multiuser Mode

• ✅ TLS enabled
• ✅ MFA available
• ✅ Audit logging
• ✅ JWT tokens with 1-hour TTL
• Suitable for internal teams

Enterprise Mode

• ✅ Enforced TLS
• ✅ MFA required
• ✅ Full audit logging
• ✅ JWT + refresh tokens
• ✅ RBAC-ready (integrates with Cedar)
• ✅ Encrypted secrets in transit
• Production-ready

Troubleshooting

Configuration Not Applied

1. Check file is in config/runtime/
2. Verify TOML syntax: toml-cli validate vapora.toml
3. Check environment variables aren't overriding
4. Restart services after config changes

Port Already in Use

Edit configuration:

[backend]
port = 9001  # Change from 8001

Database Connection Timeout

Check URL and connectivity:

# Test SurrealDB
curl -i http://localhost:8000/health

# Update config
[database]
url = "ws://surrealdb.example.com:8000"

Cost Tracking Not Working

Ensure provider credentials are set:

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

Advanced Topics

Custom Scoring Formula

Modify learning profile weights in agents schema:

[agents.learning.scoring]
load_weight = 0.2      # Reduce load importance
expertise_weight = 0.6 # Increase expertise importance
confidence_weight = 0.2

Multi-Region Deployment

Create regional config:

let defaults = import "../../schemas/vapora/main.ncl" in
let enterprise = import "../../schemas/platform/defaults/deployment/enterprise.ncl" in

{
  ..enterprise,
  frontend.api_url = "https://us-west.vapora.production",
  database.url = "ws://surrealdb-us-west.internal:8000",
}

Budget Alerts and Actions

Define custom budget thresholds in llm_router:

[llm_router.budget_enforcement]
near_threshold_percent = 70  # Alert at 70%
auto_fallback = true         # Auto-fallback to cheaper

References

• VAPORA Architecture
• Nickel Language
• typedialog Documentation
• SurrealDB Configuration
• NATS JetStream

---

Generated: January 12, 2026 VAPORA Version: 1.2.0 Last Updated: January 12, 2026