Theater: Run agents on your computer safely

9 hours ago 1

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 [email protected]

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

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

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)?; }

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

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: