Theater

A WebAssembly actor system designed for secure, transparent, and reliable AI agent infrastructure.

This project is in early development, breaking changes are expected. Now that the core functionality is in place, I am going to start building actors, if you are interested in being notified of future developments, have an idea of the some agents i should build, or want to help please email me at colinrozzi+theater@gmail.com

The Challenge

AI agents present incredible opportunities for automation and intelligence, but they also introduce significant challenges. As autonomous AI agents become more capable and ubiquitous, we need infrastructure that can:

Contain and secure agents with precise permission boundaries
Trace and verify all agent actions for auditability and debugging
Manage failures gracefully in complex agent systems
Orchestrate cooperation between specialized agents with different capabilities

The Theater Approach

Theater provides infrastructure specifically designed for AI agent systems. It moves trust from the individual agents to the system itself, providing guarantees at the infrastructure level:

WebAssembly Components provide sandboxing and deterministic execution, ensuring agents can only access explicitly granted capabilities
Actor Model with Supervision implements an Erlang-style supervision hierarchy for fault-tolerance and structured agent cooperation
Event Chain captures every agent action in a verifiable record, enabling complete traceability and deterministic replay

Guide - A comprehensive guide to Theater
Reference - Full rustdoc documentation

Quick Start with Theater CLI

Theater includes a powerful CLI tool for managing the entire agent lifecycle:

# Create a new agent project
theater create my-agent

# Build the WebAssembly agent
cd my-agent
theater build

# Start a Theater server in another terminal
theater server

# Start the agent
theater start manifest.toml

# List running agents
theater list

# View agent logs
theater events <agent-id>

# Start agent and subscribe to its events in one command
theater start manifest.toml --id-only | theater subscribe -

See complete CLI documentation →

Agent System Architecture

Theater enables sophisticated agent architectures through its actor model:

Agent Hierarchy: Structure agents in parent-child relationships where parent agents can spawn, monitor, and control child agents
Specialized Agents: Create purpose-built agents with specific capabilities and knowledge domains
Secure Communication: Enable agent-to-agent communication through explicit message passing
Capability Controls: Grant agents precisely the capabilities they need through configurable handlers

Agent Supervision

Theater's supervision system enables robust agent management:

# Parent agent manifest
name = "supervisor-agent"
component_path = "supervisor.wasm"

[[handlers]]
type = "supervisor"
config = {}

Supervisor agents can:

Spawn new specialized agents
Monitor agent status and performance
Restart failed agents automatically
Access agent state and event history

Example usage in a supervisor agent:

use theater::supervisor::*;

// Spawn a specialized agent
let agent_id = supervisor::spawn_child("researcher_agent.toml")?;

// Get agent status
let status = supervisor::get_child_status(&agent_id)?;

// Restart agent if needed
if status != ActorStatus::Running {
    supervisor::restart_child(&agent_id)?;
}

Complete Traceability

Theater captures every action agents take in a verifiable event chain:

All messages between agents are recorded
Every external API call is logged with inputs and outputs
State changes are tracked with causal relationships
The entire system can be deterministically replayed for debugging

Development Setup

Using Nix (Recommended)

Theater uses Nix with flakes for reproducible development environments. Here's how to get started:

First, install Nix: https://nixos.org/download/

Enable flakes by either:

Adding to your /etc/nix/nix.conf:

experimental-features = nix-command flakes

Or using the environment variable for each command:

export NIX_CONFIG="experimental-features = nix-command flakes"

Clone the repository:

git clone https://github.com/colinrozzi/theater.git
cd theater

Enter the development environment:
```
nix develop
```

Manual Setup

If you prefer not to use Nix, you'll need:

Rust 1.81.0 or newer
LLVM and Clang for building wasmtime
CMake
OpenSSL and pkg-config

Then:

Clone the repository:

git clone https://github.com/colinrozzi/theater.git
cd theater

Build the project:

cargo build

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Run the tests (cargo test)
Run the linter (cargo clippy)
Format your code (cargo fmt)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Status

This project is in active development. Most features are focused on providing infrastructure for AI agent systems with security, traceability, and reliability as primary goals. If you are interested in the project or have questions, please reach out to me at theater.ntwk@gmail.com.

theater 0.2.0