Kameo

Kameo implements the actor model for Rust’s async ecosystem: each actor runs in its own Tokio task with an isolated mailbox, communicates via strongly-typed messages and replies, and can be organized into supervision trees so that a panicking actor doesn’t take down the rest of the system. It supports both bounded and unbounded mailboxes with backpressure, and — via its remote feature built on libp2p — lets actors send messages across process/node boundaries using the same API as local messaging.

The project is a Cargo workspace containing the core kameo crate plus companion crates: kameo_actors (prebuilt actor patterns), kameo_macros (the #[derive(Actor)] and message-handling macros), and a console crate that ships a terminal UI for live-inspecting a running actor system’s supervision tree, mailbox backpressure, throughput, and restarts. Development is active, with frequent releases and a growing set of distributed-systems features layered onto the local actor core.

What You Get

• #[derive(Actor)] and Message/Context traits for defining actors and their typed message handlers
• Supervision trees with restart/backoff strategies so a panicking actor doesn’t crash the whole system
• Bounded and unbounded mailboxes with backpressure for controlling message load per actor
• Distributed actor messaging across process/node boundaries via the remote feature (built on libp2p)
• A live terminal-UI console (kameo_console) showing the supervision tree, mailbox depth, throughput, restarts, and deadlocks in real time

Common Use Cases

• Building concurrent Rust services (web servers, data pipelines, simulation engines) with isolated, fault-tolerant units of state
• Implementing distributed microservices or message brokers where actors on different nodes need to communicate transparently
• Real-time, low-latency systems like game servers or chat backends that benefit from actor-per-connection isolation
• Embedded/IoT applications running lightweight actors on resource-constrained devices

Under The Hood

Architecture - The core crate (src/, ~20k lines across actor.rs, mailbox.rs, message.rs, supervision.rs, registry.rs, remote.rs, request/) implements the actor runtime: actor.rs defines spawning and lifecycle, mailbox.rs implements bounded/unbounded channels with backpressure, supervision.rs implements restart strategies, and remote.rs layers libp2p-based transport on top of the same message-passing API used locally. The repo is a Cargo workspace with actors (reusable actor patterns), console (a ratatui-based TUI), and macros (proc-macro derive support) as separate member crates.

Tech Stack - Rust (edition 2024, rust-version 1.88+), built on Tokio for async execution; optional features pull in libp2p (distributed transport), rmp-serde (console wire format), and const-fnv1a-hash/const-str/either for the remote/console feature sets. Uses release-plz for automated release/versioning.

Code Quality - tests/ contains integration tests targeting specific behaviors (actor_ref_counts.rs, stop_gracefully_closes_mailbox.rs, supervision_mailbox.rs, tracing_spans.rs, on_undelivered.rs), plus a benches/ directory for performance benchmarking; the project also ships a docs/ mdBook and a hosted book (docs.page), indicating above-average documentation investment for a systems-level Rust crate.

API Design - The #[derive(Actor)] + Message/Context pattern keeps actor definitions close to plain Rust structs and impls, and local vs. distributed messaging share the same call shape, so moving an actor from local to remote deployment doesn’t require rewriting call sites — a deliberate ergonomic choice highlighted in the README’s feature list.