Wippy

Wippy is a single-binary application runtime built on the actor model. It runs Lua code in isolated processes with message passing — no shared memory, no locks. Three compute models exist: functions (stateless, request-scoped), processes (long-lived actors with state), and workflows (durable actors backed by Temporal that survive crashes). The system is designed so that agents can generate code, register it, and improve applications without redeployment.

Mental Model Everything in Wippy is a registry entry. Entries have an ID (namespace:name), a kind (which determines behavior), metadata, and data. YAML files are one way to declare entries, but the registry is the runtime source of truth and entries can be created, updated, or deleted while the system is running.

Important Rules

1. Use named logger
2. Use query builder for SQL if possible (https://wippy.ai/llm/path/en/lua/storage/sql)
3. Do not forget docs, to get to know the system better

Entry Kinds

Project Structure

myapp/
├── .wippy.yaml          # Runtime configuration
├── wippy.lock           # Source directories config
├── .wippy/              # Installed modules
└── src/                 # Application source
    ├── _index.yaml      # Entry definitions
    ├── api/
    │   ├── _index.yaml
    │   └── *.lua
    └── workers/
        ├── _index.yaml
        └── *.lua

Error Handling

-- errors global is available without require()

-- Create structured errors (MUST use single-table argument)
local err = errors.new({message = "user not found", kind = errors.NOT_FOUND})
local err = errors.new({message = "invalid input", kind = errors.INVALID})

-- WRONG: two-argument form silently breaks
-- errors.new(errors.INVALID, "message")  -- DO NOT USE

-- Error methods
err:kind()      -- Error category
err:message()   -- Error message
err:retryable() -- Boolean: can retry?
err:details()   -- Additional context table
err:stack()     -- Stack trace

-- Error wrapping
errors.wrap(err, "context message")

-- Error kinds (constants)
-- Typically retryable: TIMEOUT, RATE_LIMITED, UNAVAILABLE
-- Non-retryable: INVALID, NOT_FOUND, PERMISSION_DENIED, INTERNAL, UNKNOWN

Process Model

Processes follow actor-model concurrency without shared state. State machine: Ready -> Running -> Blocked/Idle -> Complete.

-- Spawning processes
local pid, err = process.spawn(id, host, ...)
local pid, err = process.spawn_monitored(id, host, ...)

-- Registry for service discovery
process.registry.register("name")       -- Register current process
process.registry.lookup("name")         -- Find process by name

-- Message passing (fire-and-forget, ordered per sender)
process.send(pid, topic, payload)

-- Receive messages with select
channel.select{
    {case = mailbox:case_receive(), handler = function(msg) ... end},
    {case = timer:case_receive(), handler = function() ... end},
}

Functions Module

Functions are synchronous, stateless entry points.

local funcs = require("funcs")

-- Synchronous call
local result, err = funcs.call("app.api:function_name", arg1, arg2)

-- Asynchronous call
local future = funcs.async("app.process:analyze", data)
local ch = future:response()
local result, ok = ch:receive()

-- With context
local exec = funcs.new()
    :with_context({trace_id = "abc-123"})
    :call("app.api:process", data)

Store Module

Key-value storage with TTL support.

local store = require("store")

local cache = store.get("app:cache")
cache:set("key", value, 3600)  -- TTL in seconds (0 = no expiry)
local val = cache:get("key")
cache:has("key")               -- Check existence
cache:delete("key")
cache:release()                -- Return to pool

Logger Module

local log = logger:named("component")

log:debug("message", {key = value})
log:info("message", {key = value})
log:warn("message", {key = value})
log:error("message", {key = value})

-- Child logger with persistent fields
local child = log:with({request_id = "abc"})

HTTP Handler Pattern

function handler(req, res)
    -- Request methods
    req:method()           -- GET, POST, etc.
    req:path()             -- Request path
    req:param("id")        -- Path parameter {id}
    req:query("page")      -- Query string parameter
    req:header("X-Token")  -- Request header
    req:headers()          -- All headers
    req:body()             -- Request body
    req:cookie("session")  -- Cookie value
    req:remote_addr()      -- Client IP

    -- Response methods
    res:set_status(200)
    res:set_header("Content-Type", "application/json")
    res:set_cookie("session", "value", {http_only = true})
    res:write(json.encode({ok = true}))
    res:redirect("/other", 302)
end

API Endpoints

• Browse structure: https://wippy.ai/llm/toc
• Search: https://wippy.ai/llm/search?q=your+query
• Fetch page: https://wippy.ai/llm/path/en/
• Batch fetch: https://wippy.ai/llm/context?paths=path1,path2
• Get chunk: https://wippy.ai/llm/chunk/
• Related content: https://wippy.ai/llm/related/
• Full docs dump: https://wippy.ai/llms-full.txt

Documentation

Getting Started

• What is Wippy
• Installation
• Project Structure

Guides

• CLI
• Configuration
• Linter
• Language Server
• Dependency Management
• Entry Kinds
• Observability
• Queue Consumers
• Supervision
• Publishing

Core Concepts

• Compute Units
• Registry
• Process Model
• Functions
• Workflows

Lua Runtime

• Overview
• Types
• Entries

Core

• Base
• Errors
• Time
• Channels
• Process
• Functions
• Future
• Stream
• Context
• Events
• Registry
• Contract

Data Formats

• JSON
• YAML
• Base64
• Compress
• Payload
• Excel

HTTP & Web

• HTTP
• HTTP Client
• WebSocket
• HTML

Storage

• SQL
• Store
• Filesystem
• Cloud Storage
• Queue

System

• System
• Environment
• Logger
• I/O
• Metrics
• OS Time
• TTY

Text & Templates

• Text
• Template
• TreeSitter

Security

• Security
• Crypto
• Hash
• UUID

Dynamic

• Eval
• Exec
• Expression

WASM Runtime

• Overview
• Functions
• Host Functions
• Processes

Framework

• Overview
• LLM
• Agents
• Testing
• Dataflow
• Relay
• Views
  • Facade

Temporal

• Overview
• Activities
• Workflows

System Components

• Process Host
• Terminal
• Database
• Store
• Queue
• Filesystem
• Cloud Storage
• Environment
• Template
• Security
• Exec

HTTP

• Server
• Router
• Endpoint
• Middleware
• Static Files
• WebSocket Relay
• Server-Sent Events

Tutorials

• Hello World
• CLI Applications
• Echo Service
• Channels
• Processes
• Supervision
• Task Queue
• Authentication
• Rust WASM
• LLM Agent
• Micro AGI

Internals

• Architecture
• Registry
• Scheduler
• Dispatch
• Events
• Modules
• Kinds

About

• Contributing
• License

LLM

• Platform Brief

CLI Operations Reference

Development

wippy run                    # Start the runtime (HTTP on :8080)
wippy run -c                 # Start with colorful console logging
wippy run -v                 # Start with verbose debug logging

Code Quality

wippy lint                   # Check Lua code for errors
wippy lint --level warning   # Show warnings and errors
wippy lint --level hint      # Show all diagnostics
wippy lint --rules           # Enable style lint rules

Registry Inspection

wippy registry list                        # List all entries
wippy registry list --kind "function.lua"  # List Lua functions
wippy registry list --kind "process.lua"   # List processes
wippy registry show cve.sync:cve_sync            # Show entry details

Dependency Management

wippy init                   # Initialize new lock file
wippy install                # Install dependencies from lock file
wippy update                 # Update dependencies
wippy add <module>           # Add a module dependency