Vapora/provisioning/config/examples/README.md

VAPORA Configuration Examples

Reference configurations for all deployment modes.

Files Overview

TOML Format (Direct Usage)

Copy and customize for your environment:

• vapora.solo.example.toml - Development mode (local, single-user)
• vapora.multiuser.example.toml - Team mode (shared infrastructure, cost-tracking)
• vapora.enterprise.example.toml - Production mode (HA, multi-provider, enterprise features)

How to use:

cp vapora.solo.example.toml ../runtime/vapora.toml
# Edit ../runtime/vapora.toml as needed

Nickel Format (Generated Configs)

Use Nickel for composable, mergeable configurations:

• vapora.solo.example.ncl - Solo mode with composition
• vapora.multiuser.example.ncl - Multiuser mode with customization examples
• vapora.enterprise.example.ncl - Enterprise mode with tuning options

How to use:

# Export to JSON
nickel export vapora.solo.example.ncl > ../runtime/vapora.json

# Or convert to TOML (via jq + toml converters)
nickel export vapora.multiuser.example.ncl | jq . > ../runtime/vapora.json

Quick Selection Guide

I'm developing locally

→ Use vapora.solo.example.toml

• All services on localhost
• File-based database
• No authentication complexity
• Perfect for testing

We're a small team

→ Use vapora.multiuser.example.toml

• Shared backend infrastructure
• Cost tracking per developer role
• MFA and audit logging
• Team collaboration ready

We need production deployment

→ Use vapora.enterprise.example.toml

• High availability setup
• All LLM providers enabled
• Aggressive cost optimization
• Enterprise security features

Common Customizations

Change Backend Port

TOML:

[backend]
port = 9001

Nickel:

{
  backend.port = 9001,
}

Enable Ollama for Local LLMs

TOML:

[providers]
ollama_enabled = true
ollama_url = "http://localhost:11434"

Nickel:

{
  providers.ollama_enabled = true,
}

Adjust Agent Learning Window

TOML:

[agents.learning]
recency_window_days = 14
recency_multiplier = 3.5

Nickel:

{
  agents.learning = {
    recency_window_days = 14,
    recency_multiplier = 3.5,
  },
}

Set Role-Based Budgets

TOML:

[llm_router.budget_enforcement.role_limits]
architect_cents = 750000    # $7500/month
developer_cents = 500000    # $5000/month

Nickel:

{
  llm_router.budget_enforcement.role_limits = {
    architect_cents = 750000,
    developer_cents = 500000,
  },
}

Environment Variables Override

All settings can be overridden via environment variables:

# Backend settings
export VAPORA_BACKEND_PORT=9001
export VAPORA_BACKEND_WORKERS=8

# Database
export SURREAL_URL=ws://surrealdb.example.com:8000

# LLM Providers
export ANTHROPIC_API_KEY=sk-ant-xxx
export OPENAI_API_KEY=sk-xxx
export GOOGLE_API_KEY=xxx
export OLLAMA_URL=http://localhost:11434

Deployment Checklist

Before Using Solo Mode

• Single developer machine
• Local development only
• No sensitive data

Before Using Multiuser Mode

• SurrealDB instance ready
• NATS cluster running
• Network connectivity tested
• TLS certificates available

Before Using Enterprise Mode

• Kubernetes cluster (or equivalent) ready
• SurrealDB cluster configured
• NATS JetStream cluster running
• All TLS certificates prepared
• LLM provider accounts configured
• Backup strategy in place
• Monitoring/observability stack ready

Validation

TOML Files

# Syntax check
toml-cli validate vapora.solo.example.toml

# Or via Rust
cargo build -p vapora-backend --features toml-validate

Nickel Files

# Type check
nickel typecheck vapora.solo.example.ncl

# Export and validate
nickel export vapora.solo.example.ncl | jq .

Performance Notes

• Solo mode: 2-10 concurrent tasks (development)
• Multiuser mode: 50-100 concurrent tasks (team of 10-20)
• Enterprise mode: 500+ concurrent tasks (organization scale)

Adjust max_instances in agents config based on actual needs:

[agents]
max_instances = 50  # For multiuser team
max_instances = 100 # For enterprise

Cost Estimation

Typical Monthly Costs (Multiuser Mode)

With default role budgets:

• Architect tasks: $5000/month
• Developer tasks: $3000/month
• Review tasks: $2000/month
• Testing: $1000/month
• Total budget: $11,000/month

Adjust role_limits in llm_router.budget_enforcement as needed.

Cost Optimization Tips

1. Use Ollama for development (free, local)
2. Set realistic budgets per role
3. Enable cost tracking for visibility
4. Use cheaper providers for testing (set in fallback_chain)
5. Monitor usage via Prometheus metrics

Troubleshooting

"Connection refused" on localhost:8001

• Ensure backend config uses 127.0.0.1 for solo mode
• Check no other process is using port 8001
• Verify [backend] host and port settings

"Database connection timeout"

• For solo: File path must be writable
• For multiuser: Verify SurrealDB is running and accessible
• Check [database] URL and credentials

"Budget exceeded" warnings

• Review role_limits in [llm_router.budget_enforcement]
• Increase budgets for busy months
• Check auto_fallback is enabled

Next Steps

1. Select a mode based on your needs
2. Copy example to ../runtime/
3. Customize for your environment
4. Validate configuration
5. Deploy using docker-compose or Kubernetes

For detailed instructions, see ../README.md.

---

Last Updated: January 12, 2026