📖 The Story

We built ZeptoClaw — an AI agent library in Rust with tool use, multi-provider support, and session management. A single ZeptoClaw agent can spawn sub-agents, delegate tasks, even run agents in parallel. It works great — but everything runs in one process. One agent leaks memory, the whole thing goes down. One agent panics, every agent dies with it.

Then OpenAI launched Symphony — built on Elixir and the BEAM VM. Their insight: turn work into isolated, autonomous runs where agents operate independently. The BEAM has been doing this for decades in telecom — thousands of isolated processes, each with its own memory, supervised by a parent that restarts them on failure.

That was the spark. We applied the same model to AI agents:

🔸 Each ZeptoClaw agent runs as a separate OS process — isolated memory, isolated state, independent crash domains.

🔸 A daemon supervisor watches them all. If one crashes, only that agent restarts. Others keep running.

🔸 Message passing between agents goes through the daemon over JSON lines — never shared memory — just like the BEAM's actor model.

Symphony manages work at a high level. ZeptoPM manages the agents doing the work — process lifecycle, communication, and coordination. Same philosophy, different layer.

✨ Features

📋 Requirements

• Rust 1.85+ (rustup update stable) — uses edition 2024
• macOS or Linux (Windows: untested)
• An API key for at least one supported LLM provider

📦 Install

ZeptoPM is not yet on crates.io. Build from source:

# Clone the repo and sibling dependencies
git clone https://github.com/qhkm/zeptopm.git
git clone https://github.com/qhkm/zeptoclaw.git
git clone https://github.com/qhkm/zeptocapsule.git

# Build (without capsule isolation — works on any OS)
cd zeptopm
cargo build --release --no-default-features

# Or with capsule isolation (macOS/Linux)
cargo build --release

# Install
cp target/release/zeptopm /usr/local/bin/

🚀 Quick Start

1. Create a config file:

# zeptopm.toml
[providers.openai]
api_key = "$OPENAI_API_KEY"

[[agents]]
name = "researcher"
provider = "openai"
model = "gpt-4o-mini"
system_prompt = "You are a research assistant."
auto_start = true

2. Set your API key and start the daemon:

export OPENAI_API_KEY="sk-..."
zeptopm daemon

3. In another terminal — talk to your agent:

zeptopm status                                        # check agent status
zeptopm chat researcher "What is quantum computing?"  # chat with agent
zeptopm logs researcher                               # view logs
zeptopm restart researcher                            # restart agent

🔗 Pipeline

Chain agents sequentially — the output of each agent becomes the input to the next.

# researcher finds info → writer turns it into a blog post
zeptopm pipeline "researcher,writer" "Find key facts about WebAssembly and write a blog post"

Agents must be defined in your config. Output: final agent's response to stdout. Use --json for machine-readable output.

🤖 Orchestrate

A manager agent coordinates other agents using @agent mentions in its responses.

# manager delegates research and writing to other agents
zeptopm orchestrate manager "Research Rust async patterns, then write a summary"

The manager sees all running agents as tools. Its system prompt should mention it can delegate with @researcher, @writer, etc. ZeptoPM intercepts these mentions and routes messages to the target agents.

💬 Agent Channels

Channels enable real-time communication between running agents. The orchestrator routes messages — agents themselves are unaware of channels and just see regular chat messages.

Channel Modes

Peer Failure Policies

Example: Writer + Reviewer with Live Feedback

Two agents collaborate through a TurnBased channel — the writer drafts, the reviewer gives feedback, the writer revises, and the reviewer approves.

📄 Full working config: channels-example.toml

export OPENAI_API_KEY="sk-..."

# Start the daemon
zeptopm daemon --config channels-example.toml --no-sandbox

# Submit a task (in another terminal)
curl -X POST http://127.0.0.1:9876/runs \
  -H "Content-Type: application/json" \
  -d '{"task": "write and review a short blog post about Rust async patterns"}'

# Check progress
curl http://127.0.0.1:9876/runs/<run_id>

# Get the result (includes full channel conversation history)
curl http://127.0.0.1:9876/runs/<run_id>/result

1. Planner creates execution plan:
   - writer job (no dependencies)
   - reviewer job (no dependencies)
   - TurnBased channel "draft-review" connecting both, max 2 rounds

2. Both agents start in parallel. Channel activates when both are Running.

3. Channel conversation:
   Round 0: writer  → writes initial blog post
            reviewer → gives feedback (add examples, define terms)
   Round 1: writer  → revises incorporating all feedback
            reviewer → approves the revision

4. Channel closes at max_rounds. Both agents complete.
   Artifacts contain the full channel conversation history.

🔒 Process Isolation

Each agent runs as a separate OS process. One agent crashing or leaking memory cannot affect another.

🛡️ Capsule Sandbox (optional)

With --sandbox or isolation = "capsule" in config, orchestrated jobs run inside ZeptoCapsule capsules with enforced memory limits, process count limits, filesystem isolation, and network restrictions.

📊 Resource Usage

Measured on macOS (Apple Silicon), release build:

🖥️ CLI Reference

⚙️ Config Reference

Basic

[daemon]
log_level = "info"                  # trace | debug | info | warn | error
log_format = "pretty"               # pretty | compact | json
bind = "127.0.0.1:9876"            # HTTP API bind address
poll_interval_ms = 5000            # Config change polling interval
sessions_dir = "~/.zeptopm/sessions"
max_revisions = 3                   # Max revision rounds per job
run_ttl_days = 7                    # Auto-delete old runs (0 = disabled)

[[agents]]
name = "researcher"                 # Unique agent name
provider = "openai"                 # Must match [providers.*]
model = "gpt-4o-mini"
system_prompt = "You are a research assistant."
auto_start = true                   # Start with daemon
max_restarts = 5                    # Max auto-restarts
restart_backoff_ms = 1000           # Initial backoff (doubles each restart)
max_iterations = 10                 # Max tool-calling iterations
session_persist = true              # Save history across restarts
max_history = 200                   # Keep last N messages

[agents.budget]
token_limit = 100000
cost_limit_usd = 5.00

[agents.gateway]
enabled = true                      # Protect HTTP endpoint
api_key = "$ZEPTOPM_GATEWAY_KEY"
rate_limit = 100                    # Requests per minute

[providers.openai]
api_key = "$OPENAI_API_KEY"         # Supports $ENV_VAR expansion

[providers.anthropic]
api_key = "$ANTHROPIC_API_KEY"

[providers.openrouter]
api_key = "$OPENROUTER_API_KEY"
base_url = "https://openrouter.ai/api/v1"

[daemon]
isolation = "none"                  # none | process | namespace | capsule
worker_binary = "/usr/bin/zk-init"  # Init binary for namespace capsules
security = "standard"               # dev | standard | hardened

[[agents]]
memory_mib = 512                    # Memory limit per capsule job (MiB)
max_pids = 64                       # Max process count inside capsule
timeout_sec = 300                   # Wall clock timeout

🌐 Supported Providers

🔌 HTTP API

The daemon exposes a REST API (default 127.0.0.1:9876):

🏗️ Architecture

zeptopm.toml → Config Parser → Daemon (supervisor)
                                    ↑
                              Config Watcher (hot reload)
                              HTTP API (port 9876)
                                    ↓
                    ┌───────────────┼───────────────┐
                    ↓               ↓               ↓
              Worker Process   Worker Process   Worker Process
              (agent "foo")    (agent "bar")    (agent "baz")
                    ↓               ↓               ↓
              JSON lines       JSON lines       JSON lines
              over stdio       over stdio       over stdio
                    ↓               ↓               ↓
              ZeptoAgent       ZeptoAgent       ZeptoAgent
                    ↓               ↓               ↓
              LLM Provider     LLM Provider     LLM Provider
                    ↓               ↓               ↓
              ~/.zeptopm/sessions/{agent}.json (persistent history)

          Channel Router (orchestrator-routed):
              agent "bar" ←──TurnBased──→ agent "baz"
                    ↑                          ↑
                    └──── daemon routes ────────┘

🗺️ Roadmap

🧩 Zepto Stack

ZeptoPM is part of the Zepto stack — a modular system for running AI agents in production.

ZeptoPM        — orchestration, supervision, retries, job lifecycle
    │
    │  create(spec) + spawn(worker, args, env)
    ▼
ZeptoCapsule   — capsule creation, process isolation, resource enforcement
    │
    │  fork/namespace/microVM + stdio transport
    ▼
ZeptoClaw      — LLM calls, tool use, artifact production
    │
    └── JSON-line IPC over stdin/stdout back to ZeptoPM

🤝 Contributing

# Run tests
cargo test --no-default-features        # without capsule (works everywhere)
cargo test --features capsule            # with capsule (macOS/Linux)

# Check formatting and lints
cargo fmt -- --check
cargo clippy

For commercial licensing, enterprise support, or managed hosting inquiries: qaiyyum@aisar.ai