Installing the `cell` executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install cell-cli

It will make the cell command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall cell-cli uninstalls.

Back to the crate overview.

Readme

Cell – Biological Distributed Super-computing Substrate

Run millions of zero-copy messages per second between sandboxed micro-services that behave like living cells.

30-second Demo

t1:

git clone https://github.com/Leif-Rydenfalk/cell
cd cell/examples/cell-market-bench/cells/exchange
cargo run --release

t2:

cd cell/examples/cell-market-bench/cells/trader
cargo run --release -- 1 ping

On a 2013 Intel i5 you should see ~681 ns and ~1,407,409 QPS processed.

What is Cell?

Cell is a biologically-inspired runtime for building secure, high-throughput, distributed applications in Rust.

Cell – a sandboxed process (Linux namespace / bwrap / Podman)
Membrane – the Unix-domain socket it listens on
Vesicle – a zero-copy message (rkyv-serialised, mem-mapped)
Synapse – a typed client that grows automatically
DNA – the source code that is compiled on first use (cached in ~/.cell/cache)
Mycelium Root – the host daemon that spawns cells on demand

Performance (single core, Intel i5-4300U @ 2.6 GHz, Linux 6.2)

Metric	cell-market-bench demo
messages per second	1.48 M
median RTT (ping)	677 ns
batch 100 messages	1 disk sync
memory copy count	0 (rkyv archived)

Project Layout

cell/
├── cell-sdk/          # Runtime SDK (Membrane, Synapse, Vesicle, …)
├── cell-consensus/    # Embeddable Raft + batched WAL
├── cell-macros/       # `#[protein]` and `signal_receptor!` for codegen
└── examples/          # Living demos
    └── cell-market-bench/   # 9 M TPS market simulation

Writing a Cell

Define the protocol

use cell_sdk::protein;

#[protein]
pub enum PingMsg {
    Ping(u64),
    Pong(u64),
}

Implement the cell

use cell_sdk::{Membrane, vesicle::Vesicle};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    Membrane::bind("pong", |v: Vesicle| async move {
        let ping = rkyv::from_bytes::<PingMsg>(v.as_slice())?;
        let pong = PingMsg::Pong(ping.0);
        Ok(Vesicle::wrap(rkyv::to_bytes::<_,16>(&pong)?.into_vec()))
    }).await
}

Call it from anywhere

let mut syn = Synapse::grow("pong").await?;
let reply = syn.fire(PingMsg::Ping(42)).await?;

Security Model

No network by default – cells share a Unix socket directory only
Read-only root-fs – code cannot be modified at runtime
User-namespace mapping – files created by the container belong to the host user
Resource limits – CPU / memory cgroup quotas (Podman path)
Automatic sandbox escape prevention – bwrap --unshare-all --die-with-parent

How it Works

Mycelium Root listens on ~/.cell/run/mitosis.sock
Synapse::grow("name") asks Root to spawn the binary if the socket is absent
Root compiles the DNA (incremental, cached) and launches the cell inside Capsid (bwrap)
Cell binds its Membrane socket (/tmp/cell/name.sock inside the container, ~/.cell/run/name.sock on host)
Messages are rkyv-serialised, sent over the Unix socket, and zero-copy deserialised on the receiver side
Optional: embed cell-consensus for disk-backed Raft consensus with batch-append WAL (single fsync per batch)

Requirements

Linux 5.10+ (for memfd, user-ns, cgroup v2)
Rust 1.75+
bubblewrap (bwrap) installed (or Podman for rootless containers)

Environment Variables

Variable	Purpose
`CELL_SOCKET_DIR`	Override socket directory (default `~/.cell/run`)
`CELL_UMBILICAL`	Override Mycelium Root socket
`CELL_GOLGI_SOCK`	Used by QUIC transport (future)

Road-map / Ideas

QUIC-based inter-host pheromone routing
GPU vesicles (CUDA memory-mapped buffers)
eBPF packet filtering inside Membrane
Hot swap DNA without dropping connections
Web-assembly ribosome (compile once, run anywhere)

License

MIT + Attribution

Copyright (c) 2025 Leif Rydenfalk
Attribution requirement: The above copyright notice shall be reproduced in
any binary, source or derivative distribution (including compiled artifacts,
container images, SaaS, or embedded firmware) in one of these forms:

A file named ATTRIBUTION in the root/top-level directory, or
A visible "About"/"Credits" page/UI element, or
A command-line flag --about that prints the notice.

Start the mesh

$ cell up

Check status

$ cell status

Live dashboard

$ cell top

Hot-swap a cell

$ cell swap ledger

Stop everything

$ cell down

Installing the cell executable

Installing the `cell` executable