Voodoo

The programmable runtime for adaptive applications and operational systems.

One runtime for Web, APIs, Agents, Workers, Human workflows, Distributed systems, and Physical systems. Built for the future of adaptive applications and operational systems.

Voodoo favors composition over configuration, Python over DSLs, adapters over lock-in, events over tightly coupled systems, and explicit capabilities over unrestricted AI autonomy.

Table of Contents

• Why Voodoo?
• Quick Start
• The AI SaaS App
• What Makes Voodoo Different
• The Computational Model
• Features
• Installation
• Configuration
• Documentation
• Examples
• Project Status & Roadmap
• Contributing
• Security
• License

Why Voodoo?

Modern application development is fragmented. You assemble a frontend framework, a backend framework, a database, a queue, an event bus, an AI SDK, an auth system, a deployment pipeline — and spend more time gluing them together than building your product.

Voodoo asks: what if all of that was one thing?

Voodoo is not a wrapper around other frameworks. It's a unified runtime where UI, API, agents, workers, events, and data are first-class primitives that share a single execution model.

Quick start

pip install voodoo-framework
voodoo create my_app
cd my_app
voodoo dev

Open http://localhost:8000 — that's it. No npm, no bundler, no config files.

voodoo create scaffolds a full local runtime app with durable tasks, scheduler, events, and agent runtime — all on zero infrastructure. The generated app includes a crash/restart demo proving durability.

Want a minimal scaffold? Use voodoo new instead for a bare-bones app with just UI routing.

Want AI features? Install with pip install "voodoo-framework[ai]" to add OpenAI, Anthropic, Gemini, and Ollama SDKs.

The AI SaaS app

Here's a complete example exercising the full chain — UI → agent → tool → MCP → mesh → worker → database:

from voodoo import (
    App,
    page,
    state,
    event,
    Agent,
    tool,
    Container,
    Heading,
    Text,
    Button,
    Card,
    Div,
    Table,
)

app = App()

# --- Data model ---
from voodoo import Model


class Lead(Model):
    name: str
    email: str
    status: str = "new"


# --- Tool (one definition, four consumers) ---
@tool
async def create_lead(name: str, email: str) -> str:
    """Create a new lead in the database."""
    lead = await Lead.create(name=name, email=email)
    return f"Created lead #{lead.id}: {name}"


# --- Agent with tool calling ---
agent = Agent(
    model="openai:gpt-4o",
    tools=["create_lead"],
    system_prompt="You are a sales assistant. Use tools to create leads.",
)

# --- Realtime mesh event ---
from voodoo.mesh import mesh


@mesh.on("lead.created")
async def notify_slack(payload):
    # Triggered when a lead is created
    print(f"New lead notification: {payload}")


# --- Reactive UI ---
leads = state([])


@page("/")
def dashboard():
    return Container(
        Heading("AI SaaS Dashboard", level=1),
        Card(
            Text("Ask the AI to create leads"),
            Button("Create Lead", onclick="vd.event('create_lead', 'btn')"),
        ),
        Div(
            Table(*leads.get()),
            id="leads-table",
        ),
    )


@event
async def create_lead(element_id, value):
    run = await agent.run("Create a lead for Ada Lovelace, ada@x.io")
    # Agent calls create_lead tool → DB insert → mesh event fires
    all_leads = await Lead.all()
    leads.set(all_leads)


if __name__ == "__main__":
    app.run()

What makes Voodoo different

The Computational Model

The runtime is built on a small set of explicit concepts — not a pile of features:

Entity → State → Intent → Capability → Execution → Effect → State

Intent       — the desired outcome to achieve
Capability   — ability + authorization to produce an effect
Execution    — the central runtime mechanism (every operation is one)
Effect       — the change produced by an execution
State        — the operational truth of an entity or system

Compute, Time, Resource, and Constraint govern how an Execution happens — and AI is one form of Compute, never a fundamental primitive.

from voodoo.primitives import State, Capability, Intent, Effect

See docs/primitives.md for the computational model, docs/execution-model.md for runtime semantics, and ARCHITECTURE.md for the implementation model.

Features

UI & Frontend

• Reactive UI — Component system in pure Python with WebSocket-driven DOM patches
• Design System — Built-in theme engine with Tailwind adapter support, a token-first palette, and a page-level chrome tier (navbar, hero, code block, stats, CTA)
• Themes as modules — Shareable JSON-only theme presets (.voodoo/theme/theme.json + custom.css) with a voodoo theme CLI; install themes from PyPI (voodoo-theme-<name>)
• SEO & GEO — Server-side rendering, sitemaps, OpenGraph, and Generative Engine Optimization

AI & Agents

• Agents — Provider-driven execution loop with tool calling (OpenAI, Anthropic, Gemini, Ollama)
• Tools — @tool decorator with auto-generated JSON schemas from type hints
• MCP — Built-in Model Context Protocol server; every tool is automatically exposed
• Human-in-the-Loop — ask_human(), approve()/deny(), Task(human=True) — humans as compute participants

Backend & Data

• Data — Async SQLite ORM with RLS policies and lifecycle hooks
• Auth — JWT tokens, API keys, session cookies, RBAC route guards
• Workers — @task decorator with retries, timeout, and telemetry spans
• Voodoo Mesh — Realtime event bus with local + remote boundaries
• Edge Devices — Device Gateway (voodoo-edge/v1 over HTTP & MQTT): devices emit events, trigger Executions, receive Effects — see docs/edge/overview.md

Runtime & Infrastructure

• Runtime Engine — Unified ExecutionEngine producing Execution records for every operation
• Durable Execution — SQLite-backed execution store with checkpointing and voodoo recover CLI
• Planner — Deterministic capability → compute participant resolution with fallbacks
• Adaptive Runtime — Supervisor loop with retry, fallback, delegation, budget steering
• Telemetry — Correlation IDs, request tracking, agent token/cost accounting
• Security — CORS, CSRF, rate limiting, security headers — all on by default

Adapters (optional extras)

• PostgreSQL — Database, queue, and event store ([postgres])
• Redis — Queue and cache ([redis])
• S3/R2 — Object store with presigned URLs and multipart uploads ([s3])

Installation

Homebrew (macOS/Linux)

brew tap helderperez-dev/voodoo
brew install voodoo

uv

uv tool install voodoo-framework

Magic install script

curl -fsSL https://raw.githubusercontent.com/helderperez-dev/voodoo/main/install.sh | bash

pip / pipx

# Core (lean — no AI SDKs)
pip install voodoo-framework

# With AI providers
pip install "voodoo-framework[ai]"

# With all optional extras
pip install "voodoo-framework[ai,postgres,redis,s3]"

# With dev tools
pip install "voodoo-framework[dev]"

# Isolated environment
pipx install voodoo-framework

Verify

voodoo version

Uninstall

# Homebrew
brew uninstall voodoo && brew untap helderperez-dev/voodoo

# uv
uv tool uninstall voodoo-framework

# pip / pipx
pip uninstall voodoo-framework   # or: pipx uninstall voodoo-framework

# Magic install script
rm -rf ~/.voodoo/venv && rm -f ~/.local/bin/voodoo

Configuration

Voodoo runs zero-config out of the box. When you need to customize, create a voodoo.yaml file:

database:
  provider: sqlite          # sqlite (default) | postgres
queue:
  provider: sqlite          # sqlite (default) | postgres | redis
events:
  provider: sqlite          # sqlite (default) | postgres | memory
objects:
  provider: local           # local (default) | s3
cache:
  provider: memory          # memory (default) | redis
models:
  default: openai:gpt-4o
ai:                          # zero-code provider setup (any OpenAI-compatible endpoint)
  provider: openai
  model: deepseek-v4-flash
  base_url: "${DEEPSEEK_BASE_URL:-https://api.deepseek.com/v1}"
  api_key: "${DEEPSEEK_API_KEY}"
runtime:
  run_api_through_runtime: true  # set false to bypass execution records for API handlers

Environment variables follow the VOODOO_* convention and override defaults. See .env.example for the complete reference.

Key variables:

Generate a secure secret key:

voodoo auth secret-key

Documentation

Getting Started

• Installation
• Hello World
• Architecture
• Computational Model

Building Apps

• Components
• Routing
• Reactive State
• Events
• Data & Models
• Design System

AI & Agents

• Agents
• Tools
• MCP
• Human-in-the-Loop

Realtime & Workers

• Mesh
• Workers

Edge Devices

• Edge Overview
• Edge Protocol v1
• HTTP Transport
• MQTT Transport
• Device Security
• Reliability

Runtime & Operations

• Runtime Engine
• Planner & Adaptive Runtime
• Telemetry
• Auth
• Deployment

Engineering

• Contributing Guide
• Security Policy
• Code of Conduct
• Changelog
• Master Roadmap
• Sprint Plan
• Architecture Reference

AI Development Workflow

• AI Agent Instructions
• Copilot Instructions
• Instruction Files — Domain-specific guidance for AI agents
• Skills — Structured workflows for common tasks
• Prompts — Structured prompts for audits, planning, and reviews

Examples

Project Status & Roadmap

Voodoo is in active development (v2.0.0, Beta). The core runtime, UI system, AI agents, MCP, durable execution, adaptive runtime, model-provider protocol, layered memory, and durable agent registry are production-ready. PostgreSQL, S3/R2, and Redis adapters are shipped behind optional extras; durable human-in-the-loop is the current focus.

timeline
    title Voodoo Roadmap
    section Shipped (v1.0–v1.15.1)
        Core Runtime & UI : Routing : Components : Reactive state
        AI & Agents : Providers : Tools : MCP : Human-in-the-Loop
        Unified Runtime : ExecutionEngine : Planner : Adaptive supervisor
        Durable Local Runtime : SQLite queue : Executions : Scheduler : Objects : Events
        Production Providers : PostgreSQL : S3/R2 : Redis
    section Shipped (v1.16–v2.0)
        ModelProvider protocol : Model descriptors : Routing aliases
        Memory capability : Layered memory : SQLite + FTS5
        Durable Agents : Agent registry : v2.0
    section In Progress (v2.1)
        Durable HITL : Resumable approvals
    section Planned (v2.2+)
        Capability Security & Secrets : v2.2
        Observability & Protocol : v2.3–v2.4
        Local Runtime DX : v2.5
| AI runtime — model-provider protocol, memory, durable agent registry | v1.16–v2.0 | ✅ Shipped |
| Durable human-in-the-loop — resumable approvals | v2.1 | 🚧 In Progress |
| Capability security & secrets | v2.2 | 📋 Planned |
| Protocol stability & DX — observability, schemas, local runtime | v2.3–v2.5 | 📋 Planned |

See the [master roadmap](ROADMAP.md) and [sprint plan](SPRINT_PLAN.md) for details.

## Contributing

Contributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) before opening a pull request.

> **AI coding agents:** Read [`AGENTS.md`](AGENTS.md) and [`.github/copilot-instructions.md`](.github/copilot-instructions.md) before making any changes. These define the architectural invariants, code style, testing standards, and sprint protocol that must be followed.

Quick start for contributors:

```bash
git clone https://github.com/helderperez-dev/voodoo.git
cd voodoo
just install          # set up dev environment
just format && just lint && just test

• Bug reports → Open an issue
• Feature requests → Open an issue
• Discussions → GitHub Discussions
• Security reports → See Security Policy (do NOT open public issues)

By participating, you agree to abide by the Code of Conduct.

Security

Voodoo includes security features on by default: CORS, CSRF protection, rate limiting, and security headers. For production deployments, review the hardening checklist in SECURITY.md.

To report a vulnerability, email contact@helderperez.com — do not open a public issue. See the full Security Policy for response timelines.

Testing

pytest

License

MIT — Copyright (c) 2026 Helder Perez and the Voodoo contributors.