Introduction

nexo-rs is a Rust framework for building multi-agent LLM systems that live on real messaging channels — WhatsApp, Telegram, email — instead of a chat webapp. Event-driven (NATS, or a built-in local broker — zero external infra), per-agent tool sandboxes, drop-in configuration for private vs. public agents.

Coming from OpenClaw? That's the closest reference point — TypeScript, Node, single-process. nexo-rs keeps the "agents on real channels" idea and trades JS familiarity for: a single static binary, a fault-tolerant broker layer (NATS or a local stdio bridge — no NATS server required), per-agent capability sandboxes, durable workflows, secrets audit, plugin SDKs in 4 languages, and Termux-first portability. See vs OpenClaw for the full side-by-side.

One process, many agents, many channels. Kate handles your personal Telegram; Ana works the WhatsApp sales line; a cron-style poller sweeps Gmail for leads — all sharing one broker, one tool registry, and one memory layer.

Boots with zero config. nexo runs against documented defaults when no config dir exists — 0 agents, local broker, admin RPCs + health endpoint live. Add a persona, a YAML, or nexo init's 19 commented sample files when you're ready. Switch broker mode at runtime with nexo set-broker {local,nats}.

Single binary, ~90 MB. No Node, no npm, no Docker required. The release tarball you download is ~15 MB (xz-compressed); the .deb is ~18 MB, the .rpm ~25 MB. Runs on a fresh VPS, on Termux without root, or as a systemd unit. Pre-built binaries ship for Linux (x86_64 / aarch64, static musl), macOS (Intel / Apple Silicon), and Windows; .deb / .rpm / Termux .deb too.

flowchart LR
    WA[WhatsApp] --> NATS[(NATS broker)]
    TG[Telegram] --> NATS
    MAIL[Email / Gmail poller] --> NATS
    BROWSER[Browser CDP] --> NATS
    NATS --> ANA[Agent: Ana]
    NATS --> KATE[Agent: Kate]
    NATS --> OPS[Agent: ops-bot]
    ANA --> TOOLS[Tools & extensions]
    KATE --> TOOLS
    OPS --> TOOLS
    TOOLS --> MEM[(Memory: SQLite + sqlite-vec)]
    TOOLS --> LLM{{LLM providers}}

Why it exists

Most "agent frameworks" assume one LLM talking to one user through one UI. Real deployments are not shaped that way:

• Several agents with different personas, models, and skills
• Multiple channels (WA + Telegram + mail) feeding the same agents
• Business logic that is not LLM-driven (scheduled tasks, regex email triage, lead notifications) running next to the LLM loop
• Private prompts and pricing tables alongside an open-source core

nexo-rs is opinionated toward that shape.

What's in the box

Who it is for

• Developers who want to run real agents — not a ChatGPT demo with retrieval.
• Multi-tenant single-install — several agents, several channels, isolated by config.
• Fault-tolerance-first teams — disk queue, DLQ, circuit breakers, single-instance lock, no message drop on reconnect.
• Anyone extending with their own stack — stdio extensions in any language, MCP, drop-in private agents.

What it is not

• Not a chatbot, not a webapp. It has no UI of its own.
• Not a replacement for LangChain/LlamaIndex as a "primitives library". It is an operational runtime.
• Not a channel-abstraction layer. WhatsApp behaves like WhatsApp, Telegram like Telegram. The runtime surfaces channels, not uniforms them.

Three minutes to a running agent

# 1. Install nexo-rs — pre-built binary, no Rust toolchain needed:
curl -fsSL https://lordmacu.github.io/nexo-rs/install.sh | bash
#    (or `cargo install nexo-rs` from crates.io, or download the
#     .deb / .rpm / Termux .deb from GitHub Releases.)

# 2. Add a channel plugin (GitHub Releases tarball OR crates.io):
nexo plugin install lordmacu/nexo-plugin-whatsapp
#    Built-ins: nexo-plugin-{whatsapp,telegram,email,browser,google,web-search}.
#    crates.io path: `cargo install nexo-plugin-web-search` (etc.).

# 3. Install the Cody programmer-pair persona (or any other v2 pack):
nexo persona install lordmacu/nexo-persona-cody

# 4. Boot. The daemon picks up the persona + plugins automatically.
nexo

nexo (no subcommand) runs the daemon against documented defaults for every YAML when no config dir exists; nexo plugin install drops a channel plugin under <state_dir>/plugins/; nexo persona install lays down a ready-to-run agent + plugin bindings under <state_dir>/personas/. To tune from a documented baseline instead of the bare defaults, run nexo init first to scaffold 19 commented sample YAMLs. Other install channels (Docker, Nix, native packages, Termux): see the installation guide.

Build your own persona pack? See Installing personas for the v2 manifest shape + GitHub Releases wire convention.

Next

• Zero-config quickstart (30s)
• Installation
• Quick start (10min walkthrough)
• Installing personas
• Architecture overview
• API reference (rustdoc) — every public type in the workspace

Why nexo-rs

If you've tried to build a real agent system, you know the gap.

Most "agent frameworks" assume one LLM talking to one user through one UI. Real deployments are not shaped that way.

You have several agents with different personas, models, and skills. Multiple channels (WhatsApp + Telegram + mail) feed the same agents. Business logic that is not LLM-driven (scheduled tasks, regex email triage, lead notifications) runs next to the LLM loop. Private prompts and pricing tables live alongside an open-source core. Customer support agents need a different tool sandbox than your billing bot.

nexo-rs is opinionated toward that shape.

What you get

• One process, many agents, many channels. Kate handles your personal Telegram. Ana works the WhatsApp sales line. A cron-style poller sweeps Gmail for leads — all sharing one broker, one tool registry, and one memory layer.
• Single binary, ~90 MB. No Node, no npm, no Docker required. The release tarball you actually download is ~15 MB (xz-compressed); the .deb is ~18 MB, the .rpm ~25 MB. Runs on a fresh VPS, on Termux without root, or as a systemd unit.
• Production-grade by default. Event bus with disk fallback — NATS for multi-host, or a built-in local broker (stdio-bridge for subprocess plugins, no external server) for single-host; nexo set-broker flips between them. Per-agent capability sandboxes. Cosign-verified plugin marketplace. Multi-tenant SaaS-ready.
• Zero-config boot. nexo runs against documented defaults with no config dir — admin RPCs + health live, 0 agents. Add a persona, a YAML, or nexo init's 19 commented samples when you're ready.

Three layers of extensibility

When you're ready to add functionality, pick the right layer:

What it's not

• Not a chat webapp. There's no built-in UI; you bring your own channels (and your own UI for microapps).
• Not a single-tenant prototype. Multi-tenant SaaS is a first-class shape, not an afterthought.
• Not a research toy. Every release is signed; the install pipeline has cosign verification + sha256 checks; the broker has disk fallback; the test surface covers all four SDK languages.

How it compares

The closest reference point is OpenClaw (TypeScript, Node). If that's where you're coming from, here's the trade: you give up JS familiarity, you get —

• A single static Rust binary (vs Node + node_modules); pre-built for Linux / macOS / Windows + .deb / .rpm / Termux
• A fault-tolerant broker layer — NATS for multi-host or a local stdio bridge with no external server (vs in-memory only)
• Zero-config boot + nexo init documented YAML scaffolds
• Per-agent capability sandboxes
• Durable workflows (TaskFlow) + secrets audit
• Termux / mobile-first portability
• Plugin SDKs in 4 languages — Rust, Python, TypeScript, PHP (vs TS only)

See vs OpenClaw for the full side-by-side.

Where to next

• New here? → Quickstart — install
  • first agent in 5 minutes.
• Want to write a plugin? → Plugin contract.
• Building a SaaS? → Microapps · getting started.
• Curious about internals? → Browse the Advanced section in the sidebar — architecture deep-dives, ADRs, design notes.

What you can build

A non-exhaustive gallery of products people are shipping (or could ship by next week) on top of nexo-rs. Each card links to the recipe / template that gets you 80 % of the way.

If you're scanning to decide whether nexo-rs fits your use case, read this page top-to-bottom. If something matches your shape, follow the link.

Channel agents

Installing a channel plugin — each card below needs one. They ship as GitHub Releases tarballs; install with nexo plugin install <owner>/<repo>:

nexo plugin install lordmacu/nexo-plugin-whatsapp
nexo plugin install lordmacu/nexo-plugin-telegram
nexo plugin install lordmacu/nexo-plugin-email
nexo plugin install lordmacu/nexo-plugin-browser
nexo plugin install lordmacu/nexo-plugin-google      # Gmail/Calendar/Drive/Sheets
nexo plugin install lordmacu/nexo-plugin-web-search  # Brave/Tavily/DuckDuckGo/Perplexity
nexo plugin list

All six also ship to crates.io: cargo install nexo-plugin-web-search (etc.) drops the binary in $HOME/.cargo/bin/ and the daemon's discovery walker picks it up automatically.

(Or build from source: cargo install --git https://github.com/lordmacu/nexo-plugin-whatsapp.) Then reference the channel in your agent YAML, as shown below.

WhatsApp sales agent — qualify leads + book demos

⏱ Build time · 1 afternoon · ⚙️ Layer · agent + WhatsApp plugin

Ana takes inbound WhatsApp messages, qualifies the prospect with a tool that calls your CRM, and books a calendar slot. Persona prompt

• 2 tools (crm_lookup, calendar_book) + a YAML — that's it.

# config/agents.d/ana-sales.yaml
agents:
  - id: ana-sales
    persona_path: ./personas/ana-sales.md
    llm: minimax-m2.5
    channels:
      - whatsapp:sales-line
    tools: [crm_lookup, calendar_book, send_quote]
    memory: { long_term: true, vector: true }

→ WhatsApp sales agent recipe → WhatsApp plugin docs

Email triage agent — auto-reply + escalate

⏱ Build time · 1 day · ⚙️ Layer · agent + email plugin + skill bundle

Sweeps Gmail every 5 minutes, classifies inbound messages (invoice / support / spam / sales), auto-replies to the easy buckets, escalates the rest to a human via Telegram with a 1-paragraph summary.

agents:
  - id: triage-bot
    persona_path: ./personas/triage.md
    channels: [email:inbox, telegram:ops-team]
    skills: [classify-email, draft-reply, escalate-to-human]

→ Email plugin docs → Skill catalog

Google Workspace agent — Gmail + Calendar + Drive

⏱ Build time · 1 afternoon · ⚙️ Layer · agent + Google plugin

OAuth-authenticated agent that can search Gmail, schedule calendar events, and pull docs from Drive — all through the generic google_call tool that wraps any *.googleapis.com endpoint. Token state lives in the agent's workspace; access tokens auto-refresh.

cargo install nexo-plugin-google
nexo                                        # daemon discovers + spawns
nexo-plugin-google --oauth-once <agent_id> \
    --client-id-file ./secrets/google_client_id.txt \
    --client-secret-file ./secrets/google_client_secret.txt \
    --token-file ./data/workspace/<agent_id>/google_tokens.json \
    --scopes gmail.readonly,calendar,drive.readonly \
    --workspace-dir ./data/workspace/<agent_id>

agents:
  - id: gws
    persona_path: ./personas/gws.md
    google_auth:
      client_id_file:     ./secrets/google_client_id.txt
      client_secret_file: ./secrets/google_client_secret.txt
      scopes: [gmail.readonly, calendar, drive.readonly]
    tools: [google_auth_status, google_call]

→ Google plugin docs → Source · github.com/lordmacu/nexo-rs-plugin-google

Customer support copilot — Telegram bot with KB + handoff

⏱ Build time · 2-3 days · ⚙️ Layer · agent + Telegram + vector memory + MCP

Telegram bot answers from your knowledge base (sqlite-vec). When the LLM's confidence drops, it hands off to a human and posts the transcript to your support channel.

agents:
  - id: support-copilot
    persona_path: ./personas/support.md
    channels: [telegram:support-bot]
    memory:
      vector: true
      vector_collections: [kb-faqs, kb-troubleshooting]
    tools: [escalate_to_human, search_kb]

→ Telegram plugin → Vector search

Multi-agent systems

Multi-agent CRM — intake, qualifier, closer

⏱ Build time · 3-5 days · ⚙️ Layer · 3 agents + agent-to-agent delegation

Three coordinated agents over NATS:

• Intake picks up inbound on every channel, normalizes, hands off
• Qualifier scores the lead (BANT or your framework), tags
• Closer (only on hot leads) drafts proposal + books call

Communicate via agent.route.<target_id> topics with a correlation_id to match responses.

flowchart LR
    WA[WhatsApp] --> INTAKE[Intake]
    EMAIL[Email] --> INTAKE
    INTAKE -->|hot lead| QUAL[Qualifier]
    QUAL -->|score >= 70| CLOSER[Closer]
    CLOSER --> CALENDAR[Calendar tool]
    QUAL -->|score < 70| NURTURE[(Drip campaign queue)]

→ Agent-to-agent delegation → Multi-agent coordination

Internal ops bot — Slack via MCP + AWS tools + cron

⏱ Build time · 1-2 days · ⚙️ Layer · agent + MCP + cron skills

A bot in your team's Slack (via MCP server) that answers "what's broken in prod", schedules nightly DB snapshots, and posts the daily cost report at 9 AM.

agents:
  - id: ops-bot
    persona_path: ./personas/ops.md
    channels: [mcp:slack-team]
    tools: [aws_logs, aws_cost, db_snapshot]
    cron:
      - "0 9 * * *"  # daily cost report
      - "0 2 * * *"  # nightly DB snapshot

→ MCP channels → Cron schedule tools

SaaS products

WhatsApp meta-creator SaaS — clients build their own agents

⏱ Build time · 4-8 weeks · ⚙️ Layer · microapp + multi-tenant + WhatsApp Web UI

A SaaS where end-users sign up and build their own WhatsApp agent through a WhatsApp-Web-style React UI. Each client gets isolated state, their own agents, their own knowledge base. The framework runs out of view; the microapp owns the UX.

#![allow(unused)]
fn main() {
// Provision a tenant from the microapp backend
admin.create_tenant(TenantSpec {
    id: "client-acme".into(),
    plan: "pro".into(),
    quotas: Quotas { agents: 10, llm_tokens_month: 5_000_000 },
}).await?;
}

→ Microapps · getting started → agent-creator reference → Multi-tenant SaaS

Vertical SaaS — sales / support / marketing extension pack

⏱ Build time · 2-3 weeks · ⚙️ Layer · extension + multi-tenant

Bundle your domain expertise as an extension: 5 tools + 3 advisors

• 8 skills + an MCP server adapter. Operators run nexo ext install ./your-pack and your vertical lights up across all their tenants.

→ Extension manifest → Extension templates

Personas — pre-built agent packs

Persona packs bundle a ready-to-run agent (system prompt + plugin bindings + workspace seed + secrets templates) you install with one command. Distinct from plugins (plugins register CODE; personas register CONFIG). Authored against the v2 manifest schema, published as GitHub Releases, installed via nexo persona install.

# Browse + install:
nexo persona install lordmacu/nexo-persona-cody
nexo persona list

Available today:

More on the way — see the Cody README for the v2 manifest shape if you want to publish your own. Inner- loop dev with nexo persona run /path/to/local/pack boots the daemon against an unpackaged dir.

→ Installing personas (full guide)

Specialized agents

Browser scraping agent — URL → structured data

⏱ Build time · 1-2 days · ⚙️ Layer · agent + browser plugin

Receives URLs (via webhook / Telegram / API), uses the browser plugin (Chrome DevTools Protocol) to render JS-heavy pages, extracts structured data, publishes results back to a topic. Useful for price monitoring, competitive intel, lead enrichment.

agents:
  - id: scraper
    persona_path: ./personas/scraper.md
    channels: [webhook:scrape-requests]
    tools: [browser_navigate, browser_screenshot, browser_extract_text]

→ Browser plugin

Lead notification poller — RSS / API → Telegram alert

⏱ Build time · half a day · ⚙️ Layer · poller + Telegram

A cron-style poller hits an external RSS feed / API every N minutes, dedupes against state, and pings your sales team in Telegram when something matches. Pure config — no LLM call needed on the hot path.

# config/pollers.yaml
pollers:
  - id: linkedin-jobs
    cron: "*/15 * * * *"
    url: "https://linkedin.example/.../feed.atom"
    filter:
      keyword: ["VP Sales", "Head of Growth"]
    publish: plugin.inbound.telegram.sales-alerts

→ Build a poller module → Pollers config

MCP server from Claude Desktop — expose your tools to Claude

⏱ Build time · 1 hour · ⚙️ Layer · agent as MCP server

Run nexo-rs as an MCP server. Claude Desktop (or any MCP client) sees every tool / agent / skill you've configured as if they were native. Build internal Claude integrations without writing TS.

→ MCP server from Claude Desktop → Agent as MCP server

Where to next

• Pick the closest match → follow its link → adapt to your data.
• Read the Quickstart first if you don't already have a binary running.
• Browse the Recipes section in the sidebar for end-to-end deploy walkthroughs.
• If you're building a SaaS, jump straight to Microapps · getting started.

Install nexo-rs (LLM-friendly guide)

Share this URL with any AI assistant to teach it how to install nexo-rs end-to-end on Linux or Termux: https://lordmacu.github.io/nexo-rs/install-for-ai.html

The page is intentionally linear: copy-paste each block in order. No menus to navigate, no marketing, every command is deterministic.

What you are installing

• nexo-rs — a Rust multi-agent framework. Single agent binary
  • a cloudflared tunnel for the web admin UI.
• Source: https://github.com/lordmacu/nexo-rs
• Docs (full): https://lordmacu.github.io/nexo-rs/
• License: dual MIT / Apache-2.0

Pick your platform

• Linux (Debian / Ubuntu / Arch / Fedora) → §A
• Termux (Android, no root) → §B

Skip the section that doesn't apply.

§A — Linux install

A.1. System packages

Debian / Ubuntu:

sudo apt update
sudo apt install -y build-essential pkg-config libsqlite3-dev git curl

Arch:

sudo pacman -Syu --needed base-devel pkgconf sqlite git curl

Fedora:

sudo dnf install -y @development-tools pkgconf-pkg-config sqlite-devel git curl

A.2. Rust toolchain

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
rustup component add rustfmt clippy

A.3. Clone + build

git clone https://github.com/lordmacu/nexo-rs
cd nexo-rs
cargo build --release --bin agent

The compiled binary is at ./target/release/agent. Copy it into PATH (optional):

sudo install -m 0755 target/release/agent /usr/local/bin/agent

A.4. First-run wizard

agent setup

Follow the interactive prompts. Defaults are sane. The wizard writes config/agents.d/<your-agent>.yaml, IDENTITY.md, SOUL.md, and any channel YAMLs you opt into.

A.5. Run

agent

Or, for the web admin (loopback HTTP + Cloudflare tunnel):

agent admin

The admin command prints a one-time URL + password to stdout. Open the URL, log in, and configure from the browser.

A.6. (Optional) systemd service

sudo useradd -r -s /bin/false -d /srv/nexo-rs nexo
sudo mkdir -p /srv/nexo-rs
sudo cp -r config target/release/agent /srv/nexo-rs/
sudo chown -R nexo:nexo /srv/nexo-rs

sudo tee /etc/systemd/system/nexo-rs.service > /dev/null <<'EOF'
[Unit]
Description=nexo-rs agent
After=network.target

[Service]
Type=simple
User=nexo
WorkingDirectory=/srv/nexo-rs
ExecStart=/srv/nexo-rs/agent --config /srv/nexo-rs/config
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now nexo-rs

Logs: journalctl -u nexo-rs -f.

A.7. (Optional) NATS broker

A single-process install does not need NATS — the runtime falls back to in-process channels. Add NATS only when scaling beyond one host:

curl -L -o /tmp/nats.tar.gz \
  https://github.com/nats-io/nats-server/releases/download/v2.10.20/nats-server-v2.10.20-linux-amd64.tar.gz
tar -xzf /tmp/nats.tar.gz -C /tmp
sudo mv /tmp/nats-server-*/nats-server /usr/local/bin/
sudo systemctl enable --now nats-server  # if you have a unit file

Then in config/broker.yaml set kind: nats and url: nats://127.0.0.1:4222.

§B — Termux install (Android, no root)

B.1. Termux from F-Droid

Install Termux from https://f-droid.org/en/packages/com.termux/. Do not install from the Google Play Store — that build is outdated.

Open Termux. Then:

pkg update
pkg upgrade -y

B.2. Build dependencies

pkg install -y rust git curl sqlite openssl clang pkg-config

Optional extras (only the ones you'll use):

# media transcoding + OCR + youtube downloads
pkg install -y ffmpeg tesseract yt-dlp
# tmux for long-running tunnels and ssh
pkg install -y tmux openssh
# headless Chromium for the browser plugin
pkg install -y tur-repo
pkg install -y chromium
# Termux:API for sensors / SMS / clipboard
pkg install -y termux-api
# (also install the Termux:API companion app from F-Droid)

B.3. Clone + build

cd ~
git clone https://github.com/lordmacu/nexo-rs
cd nexo-rs
cargo build --release --bin agent

B.4. First-run wizard

./target/release/agent setup

B.5. Run

./target/release/agent

Or with the admin UI (the cloudflared tunnel works on Termux):

./target/release/agent admin

B.6. Keep running with the screen off

Termux apps get killed on doze unless you disable battery optimizations and acquire a wake lock:

1. Disable optimizations: Android Settings → Apps → Termux → Battery → Unrestricted.

2. Wake lock: in Termux, type:

   termux-wake-lock
   

3. (Optional) auto-restart on boot: install Termux:Boot from F-Droid, then create ~/.termux/boot/00-nexo-rs:

   mkdir -p ~/.termux/boot
   cat > ~/.termux/boot/00-nexo-rs <<'EOF'
   #!/data/data/com.termux/files/usr/bin/sh
   termux-wake-lock
   cd ~/nexo-rs
   ./target/release/agent --config ./config >> ~/nexo-rs/agent.log 2>&1
   EOF
   chmod +x ~/.termux/boot/00-nexo-rs
   

B.7. Termux-specific tip — Chromium flags

The browser plugin (plugins: [browser]) needs the right Chromium launch flags on Termux. The defaults already cover Android; nothing extra to set. Just make sure chromium is on PATH (it is, after pkg install chromium).

Config layout (both platforms)

After agent setup runs, the project tree looks like:

nexo-rs/
├── config/
│   ├── agents.yaml          # opt-in dev defaults
│   ├── agents.d/            # your agents land here
│   │   └── <slug>.yaml
│   ├── broker.yaml          # NATS or local
│   ├── llm.yaml             # provider keys + model
│   └── plugins/             # one YAML per channel plugin
├── secrets/                 # mode 0600 token files (gitignored)
├── data/                    # SQLite databases (memory, taskflow, transcripts)
├── target/release/agent     # the built binary
└── agent.log                # if you redirected stdout

Edit YAML by hand or use the web admin (agent admin).

Troubleshooting

• cargo build fails with linker errors on Linux — install build-essential and pkg-config (§A.1).
• cargo build hits out of memory on Termux — close other apps, or build with one job: cargo build --release -j 1.
• agent exits immediately with failed to load config — run agent setup first; the wizard creates the missing files.
• WhatsApp QR pairing fails on Termux — make sure the device is on the same network as your phone, then open the QR pairing URL the daemon prints.
• Admin tunnel URL doesn't respond — Cloudflare's quick tunnel occasionally rotates; restart agent admin and copy the new URL.

Useful commands after install

agent --help                                  # all subcommands
agent doctor capabilities --json              # which env toggles are armed
agent setup doctor                            # audit configured secrets
agent ext doctor --json                       # extension health
agent flow list                               # taskflow admin
agent dlq list                                # dead-letter queue

Full reference: https://lordmacu.github.io/nexo-rs/cli/reference.html

When asking an AI for help

Paste this URL into your prompt:

Install nexo-rs from https://lordmacu.github.io/nexo-rs/install-for-ai.html
on this machine. The OS is <Linux distro / Termux>. Stop after each
section to confirm output looks right.

The page above is the canonical, copy-paste-friendly install path. The full mdBook (https://lordmacu.github.io/nexo-rs/) covers the same ground in more depth — link there once the agent is up.

Installation

Pick the channel that matches your environment. Every channel produces the same nexo binary; the differences are in how it gets onto your machine and which dependencies come bundled.

Channel matrix

Quickest path — pre-built binary

Linux / macOS (also Windows from Git Bash):

curl -fsSL https://lordmacu.github.io/nexo-rs/install.sh | bash

Windows (PowerShell):

irm https://lordmacu.github.io/nexo-rs/install.ps1 | iex

Detects your OS + arch (Linux x86_64 / aarch64 static-musl, macOS Intel / Apple Silicon, Windows x86_64-MSVC), downloads the matching release artifact from GitHub Releases, verifies its sha256, drops nexo (nexo.exe on Windows) onto your PATH, then installs the bundled channel plugins + a persona. Falls back to cargo install nexo-rs → cargo install --git if there's no pre-built binary for your platform. Every release artifact is cosign-signed.

Then:

nexo                 # boots the daemon — zero config required

Windows users: download the .zip from Releases, or run the installer under WSL (it then sees Linux).

From crates.io

If you already have a Rust toolchain:

cargo install nexo-rs

Builds + installs the nexo binary into $CARGO_HOME/bin. The whole nexo-* workspace ships to crates.io, so this resolves cleanly without a git checkout.

From source

For contributors and operators who want to track main directly:

git clone https://github.com/lordmacu/nexo-rs
cd nexo-rs
cargo build --release --bin nexo
./target/release/nexo --help

The workspace compiles ~45 crates and produces the nexo binary plus two example smoke-test bins (integration-browser-check, llm_smoke). Toolchain is pinned to Rust 1.80 (MSRV) via rust-toolchain.toml — no manual channel selection needed. For faster iterative builds use cargo build --profile release-fast (same opt-level, no LTO, ~50 % quicker).

Prerequisites

• Rust 1.80+ (rustup recommended)
• NATS is optional — the daemon defaults to broker.type: local (an in-process stdio bridge, no external server). Run a NATS server only for multi-host clusters:

  docker run -p 4222:4222 nats:2.10-alpine
  nexo set-broker nats --url nats://localhost:4222
  

  See broker shapes / broker.yaml.
• Git (the memory subsystem uses per-agent workspace-git)
• Chrome / Chromium (only if you plan to use the browser plugin)

Verification

./target/release/nexo --version
cargo test --workspace --lib

nexo --version prints the build provenance line (commit + build timestamp) so a bug report carries enough context to reproduce.

Bootstrap script

For native or Termux installs, ./scripts/bootstrap.sh automates the whole process — installs the system deps, downloads NATS if not present, scaffolds config/, and runs the setup wizard.

./scripts/bootstrap.sh           # interactive
./scripts/bootstrap.sh --yes     # accept all defaults

The script auto-detects Termux ($PREFIX set) and switches to pkg install + broker.type: local so you don't need root or NATS on a phone.

Next steps

• Quick start — first agent running in five minutes
• Setup wizard — pair channels and wire secrets
• Docker — compose stack, secrets, GHCR pulls
• Nix flake — nix run, dev shell
• Native install — detailed no-Docker setup
• Termux install — phone-hosted personal agent

Zero-config quickstart

The fastest path from an installed nexo binary to a running daemon — no YAML editing required, no NATS server, no API key needed to boot. (Install: curl … install.sh | bash, cargo install nexo-rs, or a .deb/.rpm — see Installation.) Once running, configure incrementally via nexo init (scaffold sample YAMLs), nexo set-broker (switch broker mode), or the operator UI (admin RPCs).

Total wall-clock time: 30 seconds from installed binary to live daemon serving health + admin RPCs.

This page reflects the post-Phase-92/93/94/95 ergonomics. For the classical full-control walkthrough (manually edit each YAML, pair channels, talk to a Telegram bot end-to-end), see Quickstart.

1. Run the daemon

nexo

That's it. The daemon discovers its config dir per Phase 92.9 precedence, falls back to baked-in defaults for any YAML that's missing (Phase 93), and starts serving on the default health + admin endpoints.

Expected log:

WARN  nexo_config: config dir not found — booting with
                   Default::default() for every YAML
                   (0 agents, BrokerKind::Local, 0 llm
                    providers, sqlite memory at default path)
INFO  nexo: broker ready kind=Local url=
INFO  nexo: long-term memory ready path=./data/memory.db
INFO  plugins.discovery: plugin registry wire complete loaded=0
INFO  nexo: pairing initialised
INFO  nexo: agent ready — waiting for shutdown signal

What's happening:

• 0 agents — daemon waits for nexo/admin/agents/upsert via the operator UI.
• BrokerKind::Local — in-process tokio::mpsc. No NATS server needed. Subprocess plugins bridge through stdio (Phase 92).
• 0 LLM providers — any tool call to an LLM fails loud with provider_not_found; the daemon stays up.
• SQLite memory at ./data/memory.db — auto-created.

The daemon is now ready to accept admin RPCs to populate state. The next sections walk through adding config either via the operator UI (recommended) or by hand-editing YAMLs.

2. Operator UI (recommended)

If you have the agent-creator-microapp extension installed, it exposes a web UI for managing agents, LLM providers, channels, and credentials. Every UI action is an admin RPC behind the scenes:

Each RPC writes to the corresponding YAML on disk and notifies the running daemon via config_watch, so changes take effect without restart for hot-reloadable subsystems.

If you don't yet have a microapp installed, see agent-creator-microapp or skip ahead to YAML scaffolding.

3. Scaffold sample YAMLs

When you want to configure something specific and don't want to read the source for field shapes, ask the daemon to write heavily-commented templates:

nexo init                        # writes 19 sample YAMLs to ~/.config/nexo/
nexo init --yaml broker          # only broker.yaml
nexo init --yaml broker,llm      # comma-separated names
nexo init --yaml plugins         # all plugins/*.yaml templates
nexo init --output /etc/nexo     # custom target dir
nexo init --force                # overwrite existing files
nexo init --yaml llm --stdout    # emit to stdout (for piping)

Templates cover the four required configs (agents, broker, llm, memory) plus every optional subsystem (extensions, mcp, runtime, pollers, taskflow, transcripts, pairing, webhook_receiver) and the plugin

• persona dirs.

Edit any of them, then restart the daemon (or let config_watch pick up the change). Empty fields stay at their defaults — you only fill in what you actually want.

Example: adding a MiniMax LLM provider after nexo init:

nexo init --yaml llm --output ~/.config/nexo
# Edit ~/.config/nexo/llm.yaml — uncomment the minimax block
# Set MINIMAX_API_KEY in your env (the YAML uses ${MINIMAX_API_KEY})
export MINIMAX_API_KEY=your-key
nexo

4. Switch the broker at runtime

broker.yaml type: is the single most operator-tweaked field. Skip the YAML edit and use the dedicated subcommand:

nexo set-broker local                            # stdio bridge (default)
nexo set-broker nats --url nats://localhost:4222 # multi-host cluster
nexo set-broker local --no-signal                # edit YAML only, no respawn

The subcommand edits broker.yaml in your resolved config dir (auto-creating the file with defaults if missing) and sends SIGTERM to the running daemon by default. The supervisor loop (dev-daemon.sh, systemd, etc.) respawns and picks up the new config — ~3 second blackout.

--no-signal skips the kill; you control the restart timing yourself.

When to pick which broker shape: broker shapes architecture.

5. Override config via env vars (12-factor)

For Docker / Kubernetes / CI deployments where YAMLs live in secret mounts at non-canonical paths:

NEXO_BROKER_YAML=/run/secrets/broker.yaml \
NEXO_LLM_YAML=/run/secrets/llm.yaml \
NEXO_AGENTS_YAML=/etc/cfg/agents.yaml \
  nexo

Each NEXO_<NAME>_YAML env points at an absolute path. If set, that file wholesale replaces the YAML the daemon would otherwise load from the config dir.

Currently supported (Phase 94): NEXO_AGENTS_YAML, NEXO_BROKER_YAML, NEXO_LLM_YAML, NEXO_MEMORY_YAML.

6. Layered overrides (Kustomize-style)

For ConfigMap base + Secret overlay deployments where you want to override specific fields (not whole files):

nexo --config /etc/nexo --override-from /run/secrets

The daemon loads each YAML from /etc/nexo/<name>.yaml, then deep-merges the same-named file from /run/secrets/<name>.yaml on top (per-field for mappings; wholesale replace for sequences and scalars).

Example:

# /etc/nexo/broker.yaml  (committed to git, in ConfigMap)
broker:
  type: nats
  url: nats://placeholder
  persistence:
    enabled: true

# /run/secrets/broker.yaml  (mounted from Kubernetes Secret)
broker:
  url: nats://prod-cluster.example.com:4222

Effective config the daemon sees:

broker:
  type: nats                                    # from base
  url: nats://prod-cluster.example.com:4222     # from overlay
  persistence:
    enabled: true                               # from base (overlay didn't touch)

The same chain applies to all four required YAMLs. Both env vars and --override-from compose with Phase 93 defaults: when neither layer has a value, the daemon's Default::default() takes over.

Config dir discovery

When --config <dir> is not passed explicitly, the daemon resolves the config dir in this order:

1. NEXO_CONFIG_DIR env var
2. ./config relative to cwd (legacy, only when present)
3. $XDG_CONFIG_HOME/nexo or $HOME/.config/nexo
4. ./config as a last-resort error path

Subcommands that read or write config (nexo init, nexo set-broker) auto-create the directory and any missing files when they need to — operators don't run mkdir first.

Composition summary

The four ergonomic phases stack like this:

┌────────────────────────────────────────────────────────────┐
│  Phase 95: nexo init                                       │
│    Scaffolds sample YAMLs with field-level docs.           │
│                          ↓                                 │
│  Operator edits YAML  OR  uses admin RPC  OR  set-broker   │
│                          ↓                                 │
│  Phase 94: env / override-from                             │
│    NEXO_<NAME>_YAML overrides; --override-from deep-merges.│
│                          ↓                                 │
│  Phase 92.9: --config / NEXO_CONFIG_DIR / XDG default      │
│    Base config dir resolution.                             │
│                          ↓                                 │
│  Phase 93: zero-config defaults                            │
│    Any YAML still missing → Default::default().            │
│                          ↓                                 │
│  Phase 92: subprocess broker bridge                        │
│    `broker.yaml type: local` works even with extracted     │
│    subprocess plugins. No NATS server required.            │
└────────────────────────────────────────────────────────────┘

Each layer is optional; pick the ones your deployment needs.

Where to next

• Want the classical walkthrough? → Quickstart shows manual YAML editing + Telegram bot end-to-end.
• Deploy targets in detail → .deb, .rpm, Termux, Nix, native.
• Add an agent at runtime → agents.yaml or the operator UI's /agents/new page.
• Broker shapes → broker-shapes.md covers when to pick NATS vs local vs embedded.
• Microapp framework → Microapps · getting started for building operator-facing UIs on top of the daemon.

Quickstart

Goal: by the end of this page you have a running nexo-rs daemon with one agent that replies on Telegram (or WhatsApp) when you send it a message.

Total wall-clock time on a fresh laptop: ~10 minutes. The first cargo build is the slow step — pre-built binaries skip it entirely.

In a hurry? Phase 92-95 added a much shorter path: nexo alone now boots a working daemon with zero YAMLs + zero external broker. See zero-config quickstart for the 30-second version. This page covers the classical full-control walkthrough.

What you'll have at the end

You (in Telegram)        →  "what's the weather in Bogotá?"
Your agent (Ana)         →  "Looking it up..."  (via tool)
Your agent (Ana)         →  "Currently 18 °C, light rain."

Plus everything wired together — the broker (local stdio bridge by default, or NATS), an LLM provider, a channel plugin, the agent runtime, memory. From here you can swap personas, add tools, pair more channels, or move to a multi-tenant deployment.

1. Install the binary

Pick one — the one-liner is the fastest, no Rust toolchain needed:

# Pre-built binary (Linux x86_64/aarch64, macOS Intel/Apple Silicon).
# Detects your platform, verifies sha256, drops `nexo` on PATH.
curl -fsSL https://lordmacu.github.io/nexo-rs/install.sh | bash
nexo --version

Other paths:

# From crates.io (needs a Rust toolchain)
cargo install nexo-rs

# Debian/Ubuntu (.deb), Fedora/RHEL (.rpm), Termux (aarch64 .deb) —
# grab the file for your arch from the latest release, e.g.:
#   https://github.com/lordmacu/nexo-rs/releases/latest
sudo apt install ./nexo-rs_0.1.6_amd64.deb        # Debian/Ubuntu
sudo dnf install ./nexo-rs-0.1.6-1.x86_64.rpm     # Fedora/RHEL
pkg install ./nexo-rs_0.1.6_aarch64.deb           # Termux

# Docker
docker pull ghcr.io/lordmacu/nexo-rs:latest

# From source (track main)
git clone https://github.com/lordmacu/nexo-rs.git
cd nexo-rs && cargo build --release && ./target/release/nexo --version

→ More installers: Installation, .deb, .rpm, Termux, Nix.

2. Start NATS (optional)

Phase 92 onwards, NATS is optional. Subprocess plugins bridge through the daemon's stdio JSON-RPC channel when broker.yaml type: local, so single-host dev deployments don't need an external broker server at all. Skip this step unless you're building a multi-host cluster.

For multi-host / prod-like setups, start NATS:

docker run -d --name nexo-nats -p 4222:4222 nats:2.10-alpine
# OR native install — see broker-shapes architecture doc

Then later, after the daemon is running:

nexo set-broker nats --url nats://localhost:4222

→ Broker shapes explains when to pick which.

3. Provide an LLM key

Pick one provider. MiniMax M2.5 is the primary; Anthropic and OpenAI-compatible APIs are first-class alternatives.

# Option A — MiniMax (default in shipped config)
export MINIMAX_API_KEY=your-key
export MINIMAX_GROUP_ID=your-group-id

# Option B — Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# Option C — any OpenAI-compatible endpoint
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://api.openai.com/v1

The shipped config/llm.yaml reads each via ${ENV_VAR} — no hardcoded keys.

4. Install the channel plugin + pair it

Channels are subprocess plugins (Phase 81.18 onward). Easiest is Telegram — no QR code, no Signal protocol, just a bot token from BotFather:

# Cargo install drops the binary in ~/.cargo/bin/ — the daemon's
# discovery walker scans that directory on boot, no YAML edit
# required (Phase 81.33 Stage 8 auto-detection).
cargo install nexo-plugin-telegram
nexo plugin list

# Tell BotFather to /newbot, save the token:
export TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

For WhatsApp: cargo install nexo-plugin-whatsapp, then the setup wizard walks you through QR pairing.

For Google (Gmail / Calendar / Drive): cargo install nexo-plugin-google, then run nexo-plugin-google --oauth-once <agent_id> --device (or omit --device to use the loopback browser flow). See the Google plugin docs for the full CLI flag list.

For Web Search (Brave / Tavily / DuckDuckGo / Perplexity): cargo install nexo-plugin-web-search, then populate <config_dir>/plugins/web-search.yaml::instances[].providers with API key file refs. See the Web Search plugin docs. DuckDuckGo works with no API key as the fallback provider.

Six canonical plugins live on crates.io: whatsapp/telegram/email/browser/google/web-search.

How the daemon finds your plugin

The discovery walker (Phase 81.33 Stage 8) probes every search path on boot. Defaults out of the box:

In each path the walker looks for two shapes:

1. A directory containing a nexo-plugin.toml manifest + bin/<plugin-id> entrypoint (classic layout — used when you want to ship multiple files together).
2. A bare executable named nexo-plugin-<id>. The walker invokes the binary with --print-manifest (2s timeout), parses stdout as TOML, and registers the plugin if validation passes. This is the layout cargo install produces.

Operators can append paths via config/plugins/discovery.yaml:

discovery:
  search_paths:
    - /opt/nexo-plugins        # site-specific install root
  # Default paths above are STILL scanned — supply
  # `search_paths: []` to opt out entirely.
  auto_detect_binaries: true   # opt out by setting to false
  disabled: []                 # plugin ids to skip
  allowlist: []                # whitelist when non-empty

→ Authoring your own plugin: Plugin SDKs → Rust SDK documents the print_manifest_if_requested(MANIFEST) call that makes binaries discoverable.

5. Drop a minimal agents.yaml

Scaffold every YAML the daemon knows (heavily commented, sane defaults filled in):

nexo init --output ./config
# Writes 19 sample YAMLs you can edit in place.
# Or just the ones you need: nexo init --yaml broker,llm,agents

Then add an agent to config/agents.yaml (or drop it in config/agents.d/ana.yaml — the runtime merges that directory in, alphabetical, and hot-reloads it):

agents:
  - id: ana
    model:
      provider: minimax          # minimax | anthropic | openai | gemini | deepseek
      model: MiniMax-M2.5
    plugins: [telegram]          # the plugin you installed in step 4
    inbound_bindings:
      - plugin: telegram         # which channel may trigger this agent
    system_prompt: |
      You are Ana, a helpful assistant. You answer concisely. You
      speak Spanish if the user does, English otherwise. When you
      don't know something, say so — don't make it up.

(YAML config uses #[serde(deny_unknown_fields)] — a typo'd key fails fast at boot rather than being silently ignored. Full field list: agents.yaml reference.)

6. Run the daemon

nexo --config ./config

First boot prints a startup summary. With the defaults from nexo init (broker type: local), look for something like:

✓ broker ready — kind=Local (stdio bridge, no NATS server)
✓ plugin telegram — registered remote tools (registered_count=6)
✓ Telegram bot @YourBotName online
✓ Loaded 1 agent(s): ana
✓ LLM provider: minimax-m2.5 ready
✓ Memory: SQLite at ./data/memory.db
nexo-rs v0.1.6 ready

(If you'd run nexo set-broker nats … in step 2, the first line reads broker ready — kind=Nats url=nats://… instead.) If anything is missing, the log line tells you exactly what to fix — missing env var, wrong YAML key, channel pair failure.

7. Talk to it

Open Telegram, search for your bot's name, send hola. Within seconds you'll see Ana's reply — the LLM round-trip plus any tools the agent decided to call.

You: hola
Ana: ¡Hola! ¿En qué te puedo ayudar?
You: ¿qué clima hace en Bogotá?
Ana: Déjame revisarlo...
Ana: En Bogotá ahora hay 18 °C con lluvia ligera.

(Weather requires a web_fetch or weather tool — see agents.yaml to wire one up.)

What you just ran

sequenceDiagram
    participant U as You
    participant CH as Telegram plugin (subprocess)
    participant B as Broker (local stdio bridge, or NATS)
    participant A as Ana (agent runtime)
    participant L as MiniMax M2.5

    U->>CH: "hola"
    CH->>B: publish plugin.inbound.telegram
    B->>A: deliver to ana
    A->>L: chat.completion(messages, tools)
    L-->>A: assistant turn
    A->>B: publish plugin.outbound.telegram
    B->>CH: deliver
    CH-->>U: "¡Hola! ¿En qué te puedo ayudar?"

Every arrow is observable: nexo doctor plugins, the daemon log (plugin.inbound.* / plugin.outbound.* lines), and — in NATS mode — topic subscribers.

Where to next

You picked the simplest possible path. Common next moves:

• See real product shapes → What you can build — gallery of 10 deployable use cases.
• Multiple agents on multiple channels → drop more YAML files in config/agents.d/. Hot-reload picks them up without a restart. → Drop-in agents
• Add tools your agent can call → wire a built-in tool, write a custom one, or install an extension pack. → agents.yaml reference
• Build a plugin in your language → Plugin contract (Rust, Python, TypeScript, PHP).
• Build a SaaS on top → Microapps · getting started.
• Production deploy → Hetzner, Fly.io, AWS EC2.

Platform support

Honest matrix of what runs on what, plus the prerequisites each operating system needs for the optional voice / browser / WhatsApp features.

Daemon binary (nexo)

The core daemon — the agent loop, NATS bus, plugin supervisor, admin API, MCP client/server, memory layer, taskflow runtime — ships as a single static binary. It compiles against pure-Rust TLS (rustls) and a bundled SQLite C source, so no system OpenSSL or libsqlite is required at runtime.

Installer. The install.sh one-liner detects your OS + arch and downloads the matching pre-built tarball from the latest GitHub release (Linux x86_64 / aarch64 static-musl, macOS Intel / Apple Silicon), verifies its sha256, and drops nexo on your PATH — no Rust toolchain needed. It falls back to cargo install nexo-rs → cargo install --git for platforms with no pre-built binary. Every release artifact (tarball, .deb, .rpm) carries a .sha256 sidecar and a cosign signature.

Native Windows (cmd.exe / PowerShell, no WSL): grab the release .zip or cargo install nexo-rs. The shell installer is bash-only by design — use it under WSL if you prefer the one-liner.

Optional features — what compiles per OS

The daemon's default feature set works on every platform above. A microapp built on top of nexo-microapp-sdk can opt into extra features that pull additional system dependencies; this is what changes per OS.

STT backend choice (stt-candle vs stt)

Phase 91 introduced the pure-Rust Candle backend (stt-candle) as the default track. The legacy whisper-rs path (stt) is retained for one stability window — Phase 91.12 drops it once telemetry confirms the migration.

Pick the right one:

• stt-candle (recommended for every target) — HuggingFace Candle ML framework, no C++ build chain. Works out of the box on Linux, macOS, Windows, Termux / Android NDK. Model format is HuggingFace SafeTensors (openai/whisper-tiny and friends); the SDK auto-fetches the weights + tokenizer + config from HF Hub on first call when TranscribeConfig::model_id is set, or loads from a local directory pinned via TranscribeConfig::model_path (air-gapped deployments).
• stt (legacy) — whisper-rs binding to whisper.cpp. Slightly faster on CPU, but the C++ build chain requires a per-target toolchain and breaks Android NDK / WASM cross-compile entirely. Keep it only if you've already shipped GGML .bin models you can't easily migrate yet.

Both backends share the audio-decode pipeline (ogg-opus → s16 PCM → f32) and the public TranscribeConfig / transcribe_file signature, so swapping is a Cargo feature change with no code edits at consumer sites.

GPU acceleration (opt-in, stt-candle-* sub-features)

The default stt-candle build is CPU-only pure-Rust so it cross-compiles to every target the workspace ships. Hardware acceleration is opt-in per build target:

Mix at most one per build. The audio decode + tokenizer pipeline stays identical — only the Tensor backend swaps.

Migration from a stt (whisper-rs) deployment

If you already ship a GGML .bin file and want to switch to stt-candle:

# 1. Download the equivalent SafeTensors model from HF Hub.
huggingface-cli download openai/whisper-tiny \
  --local-dir ./data/whisper-tiny

# 2. Point your microapp config at the new directory.
#    Either:
#      TranscribeConfig.model_path = "./data/whisper-tiny"
#    or, to auto-fetch on first call (HF Hub cache):
#      TranscribeConfig.model_id   = Some("openai/whisper-tiny")

# 3. Flip the Cargo feature.
#    Before: nexo-microapp-sdk = { features = ["stt"] }
#    After:  nexo-microapp-sdk = { features = ["stt-candle"] }

The whisper-rs path keeps working unchanged during the transition. Do not enable both features at once in a production build — stt-candle wins the public re-export when both are on, so the legacy path becomes effectively unreachable through the default API.

stt (legacy) — when you still need the C++ toolchain

If you stay on the stt feature, the original platform caveats still apply:

• Linux: apt install clang cmake (or your distro's equivalent). Most dev machines already have it.
• macOS: Xcode Command Line Tools — xcode-select --install. Provides clang + cmake.
• Windows: Visual Studio Build Tools 2022 (the "Desktop development with C++" workload, or just MSVC + CMake from the individual components page) — no full Visual Studio IDE required. Plus cmake from https://cmake.org/download/. After install, open a "Developer Command Prompt for VS 2022" the first time so cl.exe is on PATH.
• Termux: pkg install cmake clang from inside the Termux shell. Note that whisper.cpp performance on Android / Termux is noticeably lower than desktop CPUs; for production STT in Termux, consider stt-candle (which compiles trivially in Termux) or routing transcription to an upstream daemon.

Once the C++ build succeeds the first time, subsequent rebuilds are cached — operators usually pay this cost once during initial setup and never again.

Cloud STT (stt-cloud*) — REST + WebSocket backends

For deployments where on-device inference isn't a good fit (SaaS hot path, WASM browser microapps, metered cellular devices) the SDK ships a cloud STT path. Three providers, one fallback chain primitive, three one-line convenience constructors:

Cloud-first with local fallback — one line

When stt-cloud-local-candle is on, compose any cloud primary with a local Candle backup in one call:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use nexo_microapp_sdk::stt::{TranscribeConfig, cloud};

let candle_cfg = Arc::new(TranscribeConfig {
    model_id: Some("openai/whisper-tiny".into()),
    lang_hint: Some("es".into()),
    ..Default::default()
});

// Anthropic voice_stream → Candle fallback:
let chain = cloud::anthropic_then_candle(oauth_token, candle_cfg.clone());

// Or OpenAI / Groq REST → Candle fallback:
// let chain = cloud::openai_then_candle(api_key, candle_cfg.clone());
// let chain = cloud::groq_then_candle(api_key, candle_cfg);

let transcript = cloud::transcribe_file_with_chain(
    std::path::Path::new("/tmp/voice-note.ogg"),
    &chain,
    Some("es"),
).await?;
}

The fallback fires on transport errors (HTTP 5xx, network unreachable, WebSocket disconnect). Hard audio errors (EmptyAudio, UnsupportedFormat, Decode) short-circuit — the next leg would hit the same problem on the same bytes.

Anthropic voice_stream — Claude.ai OAuth required

AnthropicVoiceStream connects to the same endpoint Claude Code uses internally: wss://api.anthropic.com/api/ws/speech_to_text/voice_stream. Requires a Claude.ai subscriber OAuth token (not a regular Anthropic API key — different auth surface).

Wire format (linear16 PCM @ 16 kHz mono, JSON control frames, binary audio frames). The SDK collapses the streaming endpoint to a one-shot call: open WS, send buffer, send {"type":"CloseStream"}, drain until the 4-trigger finalize state machine resolves (PostCloseStreamEndpoint @ ~300 ms / NoDataTimeout @ 1.5 s / SafetyTimeout @ 5 s / WsClose). Live push-to-talk streaming is a deferred follow-up — see FOLLOWUPS.md 91.x.wasm.phase-4b.streaming.

WASM (wasm32-unknown-unknown) — REST cloud works, voice_stream deferred

The pure-Rust local backends (stt-candle Candle + stt whisper-rs) don't compile for wasm32-unknown-unknown today — the inference stack depends on crates that need kernel networking (mio) or aren't WASM-clean (opus-wave, tokenizers with onig, Candle's GEMM kernels).

REST cloud STT works on wasm32. Enable stt-cloud-wasm (the wasm-clean sibling of stt-cloud — reqwest pulled without rustls-tls, browser fetch API handles TLS). OpenAI Whisper-1 + Groq Whisper-large-v3 + the CompositeProvider fallback chain are fully supported in browser microapps. SttProvider trait drops Send + Sync bounds + uses async_trait(?Send) on wasm32 because the wasm-bindgen fetch backend returns futures holding js-sys types that aren't Send (single-threaded execution model — the bounds were a native-only thing anyway).

Cross-target microapps select the right feature per-target in their own Cargo.toml:

[target.'cfg(target_arch = "wasm32")'.dependencies]
nexo-microapp-sdk = { workspace = true, features = ["stt-cloud-wasm"] }

[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
nexo-microapp-sdk = { workspace = true, features = ["stt-cloud", "stt-cloud-anthropic", "stt-cloud-local-candle"] }

stt-cloud-anthropic (voice_stream WebSocket) is still native-only — tokio-tungstenite drags TCP types absent on wasm32. Browser microapps wanting voice_stream would need a web-sys::WebSocket-based swap-in (filed as 91.x.wasm.phase-4c).

Voice (TTS) is portable everywhere

The voice feature uses pure-Rust crates (opus-wave, symphonia, ogg) plus a websocket call to Microsoft Edge's TTS endpoint. No C/C++ build, no system audio framework — works the same on Linux, macOS, Windows, and Termux.

Channels — what Rust + the host OS support

Channels (WhatsApp / Telegram / browser / email) ship as standalone subprocess plugins. Each plugin is its own Rust binary and inherits the same OS support matrix as the daemon:

Browser channel caveat — Chromium availability

The browser plugin spawns a Chromium instance via Chrome DevTools Protocol. The plugin doesn't bundle Chromium; it shells out to whatever Chrome / Chromium / Edge is in PATH:

• macOS: brew install --cask google-chrome or use an existing Chrome install (/Applications/Google Chrome.app/... path is auto-detected).
• Windows: install Chrome from https://www.google.com/chrome/ and let the plugin auto-detect at default install path.
• Linux servers (headless): install via your distro (apt install chromium) — the plugin runs Chromium headless by default.
• Termux: pkg install chromium — note that Termux's chromium package is significantly older than upstream and some CDP features may misbehave.

What's intentionally NOT in scope today

Reporting platform-specific issues

If nexo --version runs but a particular feature breaks on your OS, file an issue with the version line + the relevant build channel (printed by nexo version in verbose mode):

nexo version | head -5
# nexo 0.1.6
# git_sha:  …
# channel:  tarball-x86_64-apple-darwin
# target:   x86_64-apple-darwin

Tag the issue with os:macos, os:windows, os:termux, etc., so we can track per-platform regressions across releases.

Setup wizard

The setup wizard is the recommended way to configure nexo-rs on a fresh install. It pairs channels, writes secrets, and patches the YAML config files so the runtime boots with everything it needs.

./target/release/agent setup

Run it from the repo root (or wherever your config/ directory lives).

What the wizard does

flowchart TD
    START([agent setup]) --> MENU{Menu}
    MENU --> LLM[LLM provider]
    MENU --> WA[WhatsApp pairing]
    MENU --> TG[Telegram bot]
    MENU --> GOOG[Google OAuth]
    MENU --> MEM[Memory DB location]
    MENU --> INFRA[NATS + runtime]
    MENU --> SKILLS[Enable / disable skills]

    LLM --> WRITE1[Write secrets/<br/>patch llm.yaml]
    WA --> QR[Scan QR<br/>write session dir]
    TG --> TOKEN[Ask bot token<br/>write secret]
    GOOG --> OAUTH[Open browser<br/>PKCE flow]
    MEM --> WRITE2[Patch memory.yaml]
    INFRA --> WRITE3[Patch broker.yaml]
    SKILLS --> WRITE4[Patch extensions.yaml]

    WRITE1 --> DONE([Done])
    QR --> DONE
    TOKEN --> DONE
    OAUTH --> DONE
    WRITE2 --> DONE
    WRITE3 --> DONE
    WRITE4 --> DONE

Every step is optional. You can run setup repeatedly — each section is idempotent.

Steps in detail

LLM provider

Prompts for the default provider (MiniMax, Anthropic, OpenAI-compat, Gemini). Writes the API key to ./secrets/<provider>_api_key.txt and ensures config/llm.yaml references it via ${file:...} or the corresponding env var.

WhatsApp pairing (multi-instance)

Per-agent. Asks which agent you are pairing and which instance label to use (personal, work, …). Each instance gets its own session dir under ./data/workspace/<agent>/whatsapp/<instance> and an allow_agents list (defense-in-depth ACL). The wizard:

1. Normalises config/plugins/whatsapp.yaml to sequence form (legacy single-mapping entries are auto-converted on first edit).
2. Upserts the entry by instance label.
3. Writes credentials.whatsapp: <instance> on the chosen agent's YAML — agents.yaml if the agent lives there, otherwise the matching agents.d/*.yaml.
4. Launches the pairing loop and renders the QR as Unicode blocks. Scan with WhatsApp → Settings → Linked Devices.
5. Runs the credential gauntlet so any drift surfaces immediately.

Re-run the wizard once per number you want to pair; instance labels are append-friendly.

Telegram bot (multi-instance)

Same shape as WhatsApp. Asks for instance label (default <agent>_bot) and bot token from @BotFather. Token lands at ./secrets/<instance>_telegram_token.txt with mode 0o600; the YAML references it via ${file:...} so secrets never live in telegram.yaml directly. Adds credentials.telegram: <instance> on the agent.

Google OAuth

The wizard writes one entry per agent in config/plugins/google-auth.yaml:

google_auth:
  accounts:
    - id: ana@google
      agent_id: ana
      client_id_path:     ./secrets/ana_google_client_id.txt
      client_secret_path: ./secrets/ana_google_client_secret.txt
      token_path:         ./secrets/ana_google_token.json
      scopes: [https://www.googleapis.com/auth/gmail.modify]

Two consent flows are offered after the YAML is written:

• Device-code (default — works headless / over SSH): the wizard prints verification_url + a 6-character user_code. Open the URL on any device, type the code, approve. The wizard polls oauth2.googleapis.com/token until approval and persists the refresh_token at token_path (mode 0o600).
• Skip and consent later via the google_auth_start LLM tool — uses the loopback PKCE flow, requires a local browser.

Scopes are comma-separated at the prompt; defaults to gmail.modify. Re-running with a different id adds a second account; re-running with the same id overwrites in place.

Memory DB location

Lets you pick where the SQLite long-term memory file lives. Default is ./data/memory.db. Per-agent isolation is on by default — each agent gets its own DB file under its workspace.

Infrastructure (NATS + runtime)

Asks for the NATS URL, optional user/password, and timeouts. Patches config/broker.yaml.

Skills on/off

Lets you selectively disable shipped extensions you don't plan to use (reduces tool surface exposed to the LLM).

Files the wizard touches

Every YAML patch preserves existing keys and comments via the yaml_patch module — your hand edits survive.

Re-running

Re-run agent setup as many times as you want. Paired channels are detected and skipped unless you explicitly ask to re-pair. To wipe a paired session:

./target/release/agent setup wipe whatsapp --agent ana

Troubleshooting

• WhatsApp QR expires too fast → the QR refreshes every ~20s; the wizard re-renders. Scan from the phone with a stable network.
• Google OAuth fails with redirect_uri_mismatch → the wizard binds to 127.0.0.1:<port>; make sure your OAuth client allows http://127.0.0.1 as a redirect URI.
• NATS unreachable → the wizard will warn but still write config. The runtime's disk queue will drain once NATS comes back.

Verifying releases

Every Nexo release artifact is signed with Sigstore Cosign using keyless OIDC — no long-lived private key, no PGP key management, no out-of-band trust establishment. The signature is tied to the GitHub Actions workflow run that produced the artifact, and a public record lives in the Rekor transparency log.

Why keyless

Traditional signing requires a long-lived signing key. If it leaks, every past release becomes suspect. Keyless signing instead anchors each signature to:

1. The GitHub Actions OIDC identity of the workflow run (https://token.actions.githubusercontent.com)
2. The specific repo + workflow file that ran (https://github.com/lordmacu/nexo-rs/.github/workflows/...)
3. The commit + ref the workflow built from

A short-lived certificate (10 min validity) is issued by Sigstore's fulcio CA, the artifact is signed with it, and the whole bundle is recorded in rekor (immutable). To forge a signature, an attacker would need to compromise GitHub's OIDC infra and the exact workflow path — and even then the forgery shows up in the public log.

Install Cosign

# macOS:
brew install cosign

# Linux (Debian/Ubuntu):
curl -L "https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64" \
  -o /usr/local/bin/cosign
chmod +x /usr/local/bin/cosign

# Linux (Fedora/RHEL):
sudo dnf install cosign

# Verify the install:
cosign version

Verify a Docker image

Every image at ghcr.io/lordmacu/nexo-rs is cosign-signed by the docker.yml workflow. Verify any tag with:

cosign verify ghcr.io/lordmacu/nexo-rs:latest \
  --certificate-identity-regexp 'https://github.com/lordmacu/nexo-rs/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

A successful verification prints the full certificate + the Rekor entry URL. Anything else (signature missing, identity mismatch, broken cert chain) means don't trust this image — check the release notes, file an issue.

Verify a downloaded binary / .deb / .rpm / .tar.gz

The sign-artifacts.yml workflow attaches three files next to every release asset:

• <asset>.sig — the raw signature
• <asset>.pem — the leaf certificate
• <asset>.bundle — combined Sigstore bundle (preferred; carries the inclusion proof)

Verify with the bundle (recommended, single command):

cosign verify-blob \
  --bundle nexo-rs_0.1.1_amd64.deb.bundle \
  --certificate-identity-regexp 'https://github.com/lordmacu/nexo-rs/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  nexo-rs_0.1.1_amd64.deb

Or with the standalone .sig + .pem if you prefer:

cosign verify-blob \
  --signature nexo-rs_0.1.1_amd64.deb.sig \
  --certificate nexo-rs_0.1.1_amd64.deb.pem \
  --certificate-identity-regexp 'https://github.com/lordmacu/nexo-rs/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  nexo-rs_0.1.1_amd64.deb

Verify in CI / scripted contexts

Drop this in a deploy pipeline:

#!/usr/bin/env bash
set -euo pipefail

ASSET="${1:?usage: $0 <asset-path>}"
BUNDLE="${ASSET}.bundle"

if [ ! -f "$BUNDLE" ]; then
    echo "ERROR: $BUNDLE missing — refusing to deploy unsigned artifact" >&2
    exit 1
fi

cosign verify-blob \
  --bundle "$BUNDLE" \
  --certificate-identity-regexp 'https://github.com/lordmacu/nexo-rs/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  "$ASSET" \
  || { echo "ERROR: signature verification failed for $ASSET" >&2; exit 2; }

Inspecting the transparency log

Every signature is searchable on Rekor:

# Search by artifact sha256:
cosign tree ghcr.io/lordmacu/nexo-rs:latest

The output shows every cosign-related artifact attached to the image (signatures, attestations, SBOMs) plus the Rekor log index where each was recorded.

What if verification fails

1. Identity regex doesn't match — the asset may have been built from a fork / unofficial workflow. Re-download from the GitHub release page directly.
2. bundle file missing — older releases (pre-Phase 27.3) don't have signatures. Tag v0.1.1 is the first signed release.
3. Cert chain expired / revoked — Sigstore's fulcio root CA has a long lifespan, but the leaf cert is short-lived. cosign automatically fetches the right TUF root; if you see chain errors run cosign initialize to refresh local trust roots.
4. Network errors talking to Rekor / Fulcio — both have CDN in front. Retry, or use --insecure-ignore-tlog for local verification (drops the transparency log check — only safe in air-gapped trust contexts).

Out of scope (for now)

• Long-lived PGP keys for the apt / yum repos — needs Phase 27.4 signed-repo work to consume them on the user side. Until that ships, .deb / .rpm signatures live in the Cosign world only.
• A Homebrew bottle-signing path that lets brew validate without the OIDC chain — Phase 27.6 follow-up.

Configuration layout

nexo-rs loads configuration from a single directory (passed via --config <path>, default ./config). The runtime reads a small set of required YAML files and a handful of optional ones.

Source: crates/config/src/lib.rs::AppConfig::load.

Directory tree

config/
├── agents.yaml              # required — base agent catalog
├── agents.d/                # optional — drop-in agents, merged in alpha order
│   ├── ana.example.yaml     # template (committed)
│   └── *.yaml               # real definitions (gitignored)
├── broker.yaml              # required — NATS / local broker + disk queue
├── llm.yaml                 # required — LLM providers
├── memory.yaml              # required — short-term + long-term + vector
├── extensions.yaml          # optional — extension search paths, toggles
├── mcp.yaml                 # optional — MCP servers the agent consumes
├── mcp_server.yaml          # optional — expose this agent as an MCP server
├── tool_policy.yaml         # optional — per-tool / per-agent policy
├── runtime.yaml             # optional — hot-reload watcher settings
├── plugins/
│   ├── whatsapp.yaml
│   ├── telegram.yaml
│   ├── email.yaml
│   ├── browser.yaml
│   ├── google.yaml
│   └── gmail-poller.yaml
└── docker/                  # optional — overrides for containerized runs
    ├── agents.yaml
    ├── llm.yaml
    └── …

Required vs optional

The loader fails startup if any required file is missing or malformed. Optional files return None when absent and unlock related features only if present.

Drop-in agents

Files under config/agents.d/*.yaml are merged into the base agents.yaml in lexicographic filename order. Each file has the same top-level shape (agents: [...]); entries append to the base list.

Common patterns:

• 00-dev.yaml / 10-prod.yaml — control override order by numeric prefix
• Keep agents.yaml public-safe and drop sensitive business content (sales prompts, pricing, phone numbers) into gitignored config/agents.d/ana.yaml
• Ship config/agents.d/<name>.example.yaml as a template so the shape stays discoverable

Details in Drop-in agents.

Docker layout

config/docker/ mirrors the main layout and is consumed when the compose file mounts it at /app/config/docker:

# docker-compose.yml
command: ["agent", "--config", "/app/config/docker"]

Secrets inside Docker containers live at /run/secrets/<name> — the compose definitions use ${file:/run/secrets/...} references. See LLM config — auth for the full secret resolution rules.

Env vars and secrets in YAML

YAML values can reference env vars and files:

Path-traversal rules for ${file:...}:

• Relative paths are rooted at the current working directory
• .. segments are rejected outright
• Absolute paths must sit under one of these whitelisted roots:
  • /run/secrets/ (Docker secrets)
  • /var/run/secrets/ (Kubernetes projected volumes)
  • ./secrets/ (project-local)
  • the directory pointed at by $CONFIG_SECRETS_DIR (operator-defined)

Everything else is refused at parse time with an explicit error naming the invalid path and the allowed roots.

Validation

All config structs deserialize with #[serde(deny_unknown_fields)], so typos fail fast:

unknown field `modl`, expected `model`
at line 4, column 5 in config/agents.yaml

Missing required fields produce the same kind of message:

missing field `model`
at line 5, column 3 in config/agents.yaml

Env / file resolution errors identify the placeholder and the file:

env var MINIMAX_API_KEY not set (referenced in llm.yaml)

${file:../etc/passwd}: `..` not allowed in file reference (in broker.yaml)

Boot sequence

flowchart TD
    START([agent --config path]) --> LOAD[AppConfig::load]
    LOAD --> REQ{required files<br/>present & parseable?}
    REQ -->|no| FAIL([fail fast, exit 1])
    REQ -->|yes| OPT[read optional files]
    OPT --> DROP[merge config/agents.d/]
    DROP --> RESOLVE[resolve env / file placeholders]
    RESOLVE --> VAL[struct-level validation<br/>deny_unknown_fields]
    VAL --> SEM[semantic validation<br/>validate_agents, MCP headers]
    SEM --> READY([AppConfig ready])

Next

• agents.yaml — full agent schema
• llm.yaml — LLM provider schema + auth modes
• broker.yaml — NATS + disk queue
• memory.yaml — short/long/vector
• Drop-in agents — merge order and patterns

agents.yaml

The agent catalog. One entry per agent; each entry declares the model, channels, tools, sandboxing, and behavioral knobs for that agent.

Source: crates/config/src/types/agents.rs.

Top-level shape

agents:
  - id: ana
    model:
      provider: minimax
      model: MiniMax-M2.5
    plugins: [whatsapp]
    inbound_bindings:
      - plugin: whatsapp
    allowed_tools:
      - whatsapp_send_message
    outbound_allowlist:
      whatsapp:
        - "573000000000"
    system_prompt: |
      You are Ana, …

Full field reference

All fields use #[serde(deny_unknown_fields)] — typos fail fast.

Identity & model

Channels

Each inbound_bindings[] entry can override the agent-level defaults for that channel: allowed_tools, outbound_allowlist, skills, model, system_prompt_extra, sender_rate_limit, allowed_delegates. Useful for running the same agent on two channels with different rules. See Per-binding capability override below for the full override surface and merge rules.

Binding match rules are strict on (plugin, instance):

• instance omitted/null only matches plugin.inbound.<plugin>
• instance: foo only matches plugin.inbound.<plugin>.foo

Tool sandboxing

allowed_tools semantics:

• For legacy agents (no inbound_bindings) the allowlist is applied at registry-build time — tools not matching the patterns are removed from the registry before the LLM sees them.
• For agents with inbound_bindings the base registry keeps every tool and enforcement happens per-binding at turn time (see Per-binding capability override) so a binding's override can both narrow AND expand within the registry. Defense-in-depth: the LLM only receives tools allowed by the matched binding, and the tool-call execution path rejects any hallucinated name outside the same allowlist.

In both modes the LLM never receives disallowed tool definitions; the difference is where the filter is applied.

System prompt & workspace

Heartbeat

heartbeat:
  enabled: true
  interval: 30s

See Agent runtime — Heartbeat.

Runtime knobs

config:
  debounce_ms: 2000
  queue_cap: 32

Agent-to-agent delegation

Routing uses agent.route.<target_id> over NATS with a correlation_id. See Event bus — Agent-to-agent routing.

Dreaming (memory consolidation)

dreaming:
  enabled: false
  interval_secs: 86400
  min_score: 0.35
  min_recall_count: 3
  min_unique_queries: 2
  max_promotions_per_sweep: 20
  weights:
    frequency: 0.24
    relevance: 0.30
    recency: 0.15
    diversity: 0.15
    consolidation: 0.10

Defaults shown. See Soul — Dreaming.

Workspace-git

workspace_git:
  enabled: false
  author_name: "agent"
  author_email: "agent@localhost"

When enabled, the agent's workspace directory is a git repo that the runtime commits to after dream sweeps, forge_memory_checkpoint, and session close. Good for forensic replay.

Google auth (per-agent OAuth)

google_auth:
  client_id: ${GOOGLE_CLIENT_ID}
  client_secret: ${file:./secrets/google_secret.txt}
  scopes:
    - https://www.googleapis.com/auth/gmail.readonly
  token_file: ./data/workspace/ana/google_token.json
  redirect_port: 17653

Used by crates/plugins/google to run OAuth PKCE per agent.

Deprecated in Phase 17 — prefer declaring Google accounts in a dedicated config/plugins/google-auth.yaml and binding them from credentials.google (see next section). Inline google_auth still boots with a warn so existing deployments keep working; it is auto-migrated into the credential store at startup.

Credentials (per-agent WhatsApp / Telegram / Google)

Pins each agent to the plugin instance / Google account it may use for outbound traffic. The runtime resolves the target at publish time from the agent id — the LLM cannot pick the instance via tool args, closing the prompt-injection vector.

credentials:
  whatsapp: personal          # must match whatsapp.yaml instance label
  telegram: ana_bot           # must match telegram.yaml instance label
  google:   ana@gmail.com     # must match google-auth.yaml accounts[].id
  # Silence the "inbound ≠ outbound" warning when intentional:
  # telegram_asymmetric: true

Validated at boot by the gauntlet (agent --check-config runs the same checks without starting the daemon). Omitting credentials: keeps the legacy single-account behavior for back-compat.

Full schema + migration guide: config/credentials.md.

Relationship diagram

flowchart LR
    AG[agent entry] --> MOD[model provider]
    AG --> PL[plugins list]
    AG --> IB[inbound_bindings]
    AG --> AT[allowed_tools]
    AG --> OA[outbound_allowlist]
    AG --> WS[workspace]
    AG --> HB[heartbeat]
    AG --> DEL[delegation gates]
    IB -->|per-binding override| AT
    IB -->|per-binding override| OA
    MOD -->|resolved from| LLM[llm.yaml]
    PL -->|tools from| PLUG[plugins/*.yaml]
    WS -->|files| SOUL[SOUL.md /<br/>IDENTITY.md /<br/>MEMORY.md]

Per-binding capability override

A single agent can expose distinct capability surfaces per InboundBinding without running two agent processes. Typical use: the same Ana agent answers WhatsApp with a narrow sales-only surface and Telegram with the full catalogue.

Schema

Every inbound_bindings[] entry accepts the following optional overrides. Unset fields inherit the agent-level value.

Anything else (workspace, transcripts_dir, heartbeat, memory, workspace_git, google_auth) stays at the agent level — identity and persistent state do not change per channel.

Example

agents:
  - id: ana
    model: { provider: anthropic, model: claude-haiku-4-5 }
    plugins: [whatsapp, telegram]
    workspace: ./data/workspace/ana
    skills_dir: ./skills
    system_prompt: |
      You are Ana.
    allowed_tools: []            # agent-level = permissive; bindings narrow
    outbound_allowlist: {}
    inbound_bindings:
      - plugin: whatsapp
        allowed_tools: [whatsapp_send_message]
        outbound_allowlist:
          whatsapp: ["573115728852"]
        skills: []
        sender_rate_limit: { rps: 0.5, burst: 3 }
        system_prompt_extra: |
          Channel: WhatsApp sales. Follow the ETB/Claro lead flow.
      - plugin: telegram
        instance: ana_tg
        allowed_tools: ["*"]
        outbound_allowlist:
          telegram: [1194292426]
        skills: [browser, github, openstreetmap]
        model: { provider: anthropic, model: claude-sonnet-4-5 }
        allowed_delegates: ["*"]
        sender_rate_limit: disable
        system_prompt_extra: |
          Channel: private Telegram. Full tool access allowed.

Boot-time validation

The runtime rejects configs with:

• Duplicate (plugin, instance) tuples in the same agent.
• Telegram instance referenced by a binding but not declared in config/plugins/telegram.yaml.
• Binding model.provider different from the agent-level provider (the LLM client is wired once per agent).
• Skills listed in a binding whose directory does not exist under skills_dir.

A binding that sets no overrides is allowed but logs a warn.

Matching order

Bindings are evaluated top-to-bottom; the first match wins. Because matching is strict on the instance axis, {plugin: telegram, instance: null} does not capture plugin.inbound.telegram.admin traffic.

Runtime isolation

• Tool list shown to the LLM is filtered through the binding's allowed_tools; tools hidden on WhatsApp remain invisible even if the LLM hallucinates the name.
• Tool-call execution re-checks the allowlist and returns not_allowed for anything outside — stops hallucination loops without executing the forbidden tool.
• Outbound tools (whatsapp_send_message, telegram_send_message) read outbound_allowlist from the matched binding, so WhatsApp sends on the sales channel cannot reach numbers that only the private channel allows.
• Sender rate limit buckets are keyed per binding; flood on one channel cannot drain the quota on another.

Back-compat

Agents without inbound_bindings do not consume plugin inbound events. Internal runtime paths that are not plugin inbound (for example heartbeat/delegation paths) still synthesize an effective policy from agent-level defaults.

Output language

Operators pin the language an agent replies in without rewriting workspace markdown. Workspace docs (IDENTITY, SOUL, MEMORY, USER, AGENTS) and tool descriptions stay in English — the single source of truth that recall, dreaming, vector search, and developer tooling all read. The runtime injects a # OUTPUT LANGUAGE system block right after the agent's system_prompt, telling the model to read those docs as-is but reply to the user in the configured language.

Where to set it

agents:
  - id: ana
    language: es                # default for every binding on this agent
    inbound_bindings:
      - plugin: whatsapp
        # → uses Spanish (inherits from the agent)
      - plugin: telegram
        instance: support_intl
        language: en            # → uses English on this channel only
      - plugin: telegram
        instance: bilingual_qa
        language: ""            # → no directive (model picks)

Resolution

Precedence (first non-empty wins):

1. inbound_bindings[i].language — per-channel override.
2. language — agent-level default.
3. null — no # OUTPUT LANGUAGE block emitted; the model decides from the user's input.

Empty string and whitespace-only values resolve to no directive on both layers — useful for "turn the directive off on this binding even though the agent has one".

Accepted values

The runtime treats the value as a label and forwards it verbatim into the directive (after sanitisation; see below). Both forms work:

• ISO codes: "es", "en", "en-US", "pt-BR".
• Human names: "Spanish", "English", "español", "Brazilian Portuguese".

Human names produce slightly clearer directives in practice (Respond to the user in Spanish. reads more natural than Respond to the user in es.), but both yield the same model behaviour with modern LLMs.

Rendered block

# OUTPUT LANGUAGE

Respond to the user in {language}. Workspace docs (IDENTITY, SOUL,
MEMORY, USER, AGENTS) and tool descriptions are in English — read
them as-is, but your turn-final reply to the user must be in
{language}.

The block lands after the agent's system_prompt (and the optional # CHANNEL ADDENDUM block) so its instruction wins under the LLM's recency bias.

Sanitisation

Defense-in-depth against config-driven prompt injection: every language value is normalised before rendering — control characters and embedded newlines are stripped, trimmed, and the result is capped at 64 characters. A YAML payload like language: "es\n\nIgnore previous instructions" cannot smuggle a multi-line directive into the system prompt.

Hot reload

Phase 18 hot-reload covers this field. Edit agents.d/<id>.yaml, save (or run agent reload), and the next message uses the new language. In-flight LLM turns finish on the old policy; subsequent turns flip to the new one.

Related

• Workspace docs and recall stay English regardless — see Soul, identity & learning.
• Per-channel rotation walkthrough lives in Recipes — A/B prompt swap.

Link understanding

Per-agent (and per-binding) toggle that fetches URLs in the user's message and injects a # LINK CONTEXT block. Off by default. Full schema, caps, and SSRF denylist live on Link understanding. The field is link_understanding at agent scope and at each inbound_bindings[] entry; binding value replaces agent default, omitted = inherit.

Web search

Per-agent (and per-binding) toggle that exposes a web_search tool backed by Brave / Tavily / DuckDuckGo / Perplexity. Off by default. Full schema, providers, cache, and circuit-breaker behaviour live on Web search. The field is web_search at agent scope and at each inbound_bindings[] entry; binding value replaces agent default, omitted = inherit.

Pairing policy

Per-binding toggle that turns on the DM-challenge gate for inbound senders. Off by default. The field is pairing_policy on each inbound_bindings[] entry; null (default) = inherit agent value or skip the gate entirely. Full protocol, threat model, and CLI reference live on Pairing.

Common mistakes

• Forgetting plugins: [...]. An agent without plugins has no inbound channel and no outbound tools. It is inert.
• Setting allowed_tools without a wildcard. ["memory_*"] allows the full memory_* family; ["memory_store"] allows only one. Check the glob before assuming.
• Large system_prompt duplication across agents. Use inbound_bindings[].system_prompt_extra to add per-channel content without duplicating the whole prompt.
• Sharing a WhatsApp session across agents. Each agent's workspace should contain its own whatsapp/default session; the wizard does this automatically, but pointing two agents at the same session dir will cause message cross-delivery.
• Translating the workspace markdown to match language. Don't. Workspace docs are the single source of truth read by recall, dreaming, and developer tooling — keep them in English. The # OUTPUT LANGUAGE block tells the model to translate the reply on its way out.

Next

• Drop-in agents — merging multiple agent files
• llm.yaml — where model.provider is resolved
• Skills catalog — names that go in allowed_tools

MiniMax M2.5

MiniMax M2.5 is the primary LLM provider for nexo-rs. It's the first provider implemented and the recommended default for new agents.

Source: crates/llm/src/minimax.rs, crates/llm/src/minimax_auth.rs.

Why it's primary

• Strong tool-calling support on both the OpenAI-compat wire and the Anthropic Messages wire
• Token Plan auth lets you run agents on a subscription without per-request billing headaches
• Aggressive price/performance for multi-agent deployments

If you don't have a specific reason to pick another provider, start with MiniMax.

Configuration

# config/llm.yaml
providers:
  minimax:
    api_key: ${MINIMAX_API_KEY:-}
    group_id: ${MINIMAX_GROUP_ID:-}
    base_url: https://api.minimax.io
    rate_limit:
      requests_per_second: 2.0
      quota_alert_threshold: 100000

Per-agent selection:

# config/agents.d/ana.yaml
agents:
  - id: ana
    model:
      provider: minimax
      model: MiniMax-M2.5

Wire formats (api_flavor)

MiniMax exposes two HTTP shapes. The client auto-detects from base_url but can be overridden via api_flavor.

Auto-detection: if base_url ends in /anthropic, the client picks anthropic_messages automatically.

Authentication

Static API key

Simple path: put the key in env or a secrets file.

Env var precedence (first wins):

1. MINIMAX_CODE_PLAN_KEY
2. MINIMAX_CODING_API_KEY
3. ./secrets/minimax_code_plan_key.txt
4. api_key field in llm.yaml

Token Plan OAuth bundle

For subscription-based access. The wizard writes a bundle to ./secrets/minimax_token_plan.json:

{
  "access_token": "...",
  "refresh_token": "...",
  "expires_at": "2026-05-01T12:00:00Z",
  "region": "https://api.minimax.io"
}

Auto-refresh: 60 seconds before expires_at, a background task POSTs to {region}/oauth/token with grant_type=refresh_token and rewrites the bundle atomically. Concurrent refreshes are serialized behind a mutex — you never get two refresh calls in flight.

Mid-flight 401: if an API call returns 401 while holding what we thought was a valid token (clock skew, revocation), the client force-refreshes once and retries the request. A second 401 is surfaced as a credential error.

Shared OAuth client id for the MiniMax Portal flow: 78257093-7e40-4613-99e0-527b14b39113.

Request / response flow

sequenceDiagram
    participant A as Agent loop
    participant RL as RateLimiter
    participant C as MiniMaxClient
    participant AU as AuthSource
    participant MX as MiniMax API

    A->>C: chat(ChatRequest)
    C->>RL: acquire()
    C->>AU: fresh_bearer()
    AU->>AU: refresh if <60s to expiry
    AU-->>C: access_token
    C->>MX: POST chatcompletion_v2 / v1/messages
    alt 200
        MX-->>C: ChatResponse
    else 401
        C->>AU: force_refresh()
        C->>MX: retry once
    else 429
        MX-->>C: Retry-After
        C-->>A: LlmError::RateLimit
    else 5xx
        MX-->>C: error body
        C-->>A: LlmError::ServerError
    end

Supported features

Rate limiting

Per-provider token bucket. requests_per_second: 2.0 refills one slot every 500 ms. Acquired before every request.

An optional quota_alert_threshold emits a structured warn log when the remaining quota (if the provider reports it) crosses the threshold. Useful for Prometheus alerting.

Error classification

See Retry & rate limiting.

Common mistakes

• Forgetting group_id. MiniMax requires a group id alongside the key for most endpoints. The wizard sets this; manual configs often miss it.
• Pointing base_url at /anthropic with a regular API key. That endpoint is for Token Plan / Coding keys only — regular keys will 401. Leave base_url at https://api.minimax.io.
• Refreshing the bundle manually mid-flight. The client already serializes refreshes. Editing the file while the agent runs can lead to an atomic write race — stop the agent, edit, restart.

Short-term memory

Per-session conversational buffer held entirely in memory. Tracks the turns of the ongoing conversation so the LLM has context on every completion request.

Source: crates/core/src/session/ (types.rs, manager.rs) — the Session struct owns the short-term buffer.

What lives in a session

Each Session stores:

An Interaction is {role: User | Assistant | Tool, content, timestamp}.

Sliding window — max_history_turns

short_term:
  max_history_turns: 50

Hard cap, sliding FIFO. When history.len() > max_history_turns, the oldest entry is removed on the next push:

flowchart LR
    MSG[new turn] --> PUSH[history.push]
    PUSH --> CHECK{len > max?}
    CHECK -->|no| DONE[done]
    CHECK -->|yes| DROP[history.remove(0)]
    DROP --> DONE

Old content is lost, not promoted. If you need long-term persistence, the agent must explicitly call the memory tool with action remember. See Long-term memory.

Session cap and eviction

short_term:
  max_sessions: 10000

Soft cap across the whole process. On overflow, the oldest-idle session (lowest last_access) is evicted to make room. Eviction fires the on_expire callbacks — used by workspace-git to checkpoint before tearing down the session.

max_sessions: 0 disables the cap (unbounded). Leave it at the default unless you have a specific reason — the cap is DoS protection against a spammer rotating chat_ids.

TTL sweeper

short_term:
  session_ttl: 24h

Sessions expire after session_ttl of inactivity. The sweeper runs every ttl / 4 (so every 6 h with the default 24 h TTL) and drops expired sessions.

stateDiagram-v2
    [*] --> Active: first message
    Active --> Active: message / event<br/>(last_access updated)
    Active --> Expired: idle > session_ttl
    Active --> Evicted: cap exceeded
    Expired --> [*]: sweeper
    Evicted --> [*]: on_expire callbacks fire

Expiry also fires on_expire — good place to hook session-close commits to a workspace-git repo.

Relationship to other memory layers

flowchart LR
    STM[short-term<br/>in-memory Vec] -.->|tool call:<br/>memory.remember| LTM[(long-term<br/>SQLite)]
    LTM -.->|vector enabled| VEC[(sqlite-vec)]
    STM -.->|transcripts_dir| TR[(JSONL transcripts)]
    STM -.->|session close| WSG[(workspace-git)]

STM does not auto-promote to LTM. Promotion happens via:

• Explicit memory.remember tool call from the agent
• Dream sweeps (Phase 10.6) that scan recall-event signals and promote hot memories
• Session-close commits to workspace-git if enabled

Gotchas

• Lost turns are gone. Once a turn falls off the sliding window it is not recoverable. If it mattered, save it to LTM before the next turn.
• max_sessions: 0 has no DoS guard. Only do this in single-tenant setups where you control the sender id space.
• last_access updates on any access. That includes heartbeat ticks if they read the session — effectively keeping a session alive past its TTL as long as the agent is alive.

WhatsApp

End-to-end WhatsApp channel: Signal Protocol pairing, inbound message bridge, outbound send/reply/reaction/media tools, optional voice transcription.

Source: standalone repo at nexo-rs-plugin-whatsapp (extracted from crates/plugins/whatsapp/ per Phase 81.19.a; see PHASES.md for the migration notes). The crate ships as a lib + bin Shape B package: the lib re-exports WhatsappPlugin for an Android embedded host tomorrow, the bin is the subprocess entrypoint the daemon spawns per cfg.plugins.whatsapp entry (Phase 81.18.b.2). Internally the plugin wraps the wa-agent (a.k.a. whatsapp-rs) crate for Signal Protocol session lifecycle, QR pairing and the Bot API surface.

Install (Phase 81.18.b.2 — operator action required)

The daemon stopped constructing WhatsappPlugin in-tree as of Phase 81.18.b.2; it spawns the standalone subprocess binary per cfg entry. Operators with cfg.plugins.whatsapp populated must install the binary and surface its directory through plugins.discovery.search_paths before starting the daemon, or the discovery walker logs a clear warning and the plugin never boots:

# Recommended — download the pre-built tarball from the plugin's
# GitHub Releases into the daemon's plugin dir:
nexo plugin install lordmacu/nexo-plugin-whatsapp
nexo plugin list

# Or build from source:
cargo install --git https://github.com/lordmacu/nexo-plugin-whatsapp

nexo plugin install lands the binary + plugin.toml under <state_dir>/plugins/whatsapp/, which the daemon's discovery walker scans by default — no search_paths edit needed. If you build with cargo install --git instead, point discovery at the install dir in agents.yaml:

plugins:
  discovery:
    search_paths:
      - ~/.cargo/bin   # or wherever you installed the binary

Each cfg.plugins.whatsapp[] entry maps to one subprocess; per- instance state (session_dir Signal Protocol creds, media_dir, instance topic suffix, bridge.response_timeout_ms, acl.allow_list) is seeded into the child via NEXO_PLUGIN_WHATSAPP_* env vars at spawn time. Multi-account operators get true process isolation — one bot's creds.json corruption can't take down the others.

The admin RPC /whatsapp/<instance>/pair* HTTP endpoints keep working: a daemon-side broker subscriber (spawn_whatsapp_pairing_state_subscriber) listens on plugin.inbound.whatsapp.> and mirrors the subprocess's Connected / Disconnected / Reconnecting / Qr events into a daemon-owned PairingState per instance.

Known limitation (Phase 81.20.c follow-up)

Subprocess whatsapp instances do not currently surface AgentEventKind::PeerTyping events on the SSE live transcript stream. The daemon's AgentEventEmitter Arc doesn't cross the process boundary; bridging typing events through the broker ships in follow-up 81.20.c.typing-presence-rpc. Inbound message routing, outbound dispatch, pairing UI, and reconnect telemetry are unaffected.

Topics

During pairing the plugin also publishes qr lifecycle events on the inbound topic so the wizard can render the QR.

Config

# config/plugins/whatsapp.yaml
whatsapp:
  enabled: true
  session_dir: ""            # empty → per-agent default
  media_dir: ./data/media/whatsapp
  instance: default
  acl:
    allow_list: []           # empty + empty env = open ACL
    from_env: WA_AGENT_ALLOW
  behavior:
    ignore_chat_meta: true
    ignore_from_me: true
    ignore_groups: false
  bridge:
    response_timeout_ms: 30000
    on_timeout: noop         # noop | apology_text
  transcriber:
    enabled: false
    skill: whisper
  public_tunnel:
    enabled: false
    only_until_paired: true

Key fields:

Pairing

Pairing is setup-time only. The runtime refuses to start without paired credentials.

sequenceDiagram
    participant U as Operator
    participant W as agent setup
    participant WA as whatsapp-rs Client
    participant P as Phone

    U->>W: setup pair whatsapp --agent ana
    W->>WA: new_in_dir(session_dir)
    WA-->>W: QR image
    W-->>U: render QR (Unicode blocks)
    U->>P: Settings → Linked Devices → scan
    P->>WA: pair
    WA-->>W: Connected
    W->>W: persist creds to session_dir/.whatsapp-rs/creds.json

• Credentials at <session_dir>/.whatsapp-rs/creds.json
• Daemon-collision check at <session_dir>/.whatsapp-rs/daemon.json blocks a second process on the same account
• Multi-account via Client::new_in_dir() — no XDG_DATA_HOME mutation
• Credential expiry mid-run (401 loop) → operator must re-pair; no runtime QR fallback

Tools exposed to the LLM

All tools honor the per-binding outbound_allowlist.whatsapp — empty list = unrestricted, populated = hard allowlist.

Event shapes

Inbound payloads (on plugin.inbound.whatsapp[.<instance>]):

// message
{
  "kind": "message",
  "from": "573000000000@s.whatsapp.net",
  "chat": "573000000000@s.whatsapp.net",
  "text": "hi",
  "reply_to": null,
  "is_group": false,
  "timestamp": 1714000000,
  "msg_id": "3EB0..."
}

// media_received
{
  "kind": "media_received",
  "from": "...",
  "chat": "...",
  "msg_id": "...",
  "local_path": "./data/media/whatsapp/abc.jpg",
  "mime": "image/jpeg",
  "caption": null
}

// qr  (pairing only)
{"kind": "qr", "ascii": "...", "png_base64": "...", "expires_at": ...}

// lifecycle
{"kind": "connected" | "disconnected" | "reconnecting" | "credentials_expired"}

// observability
{"kind": "bridge_timeout", "msg_id": "...", "waited_ms": 30000}

Presence indicators

While the agent prepares a reply, the WhatsApp plugin pulses the <chatstate> stanza on the peer phone so the user sees a live "escribiendo…" / "grabando audio…" indicator instead of dead silence. The wire shape matches what WhatsApp Web emits natively:

<!-- text reply (default) -->
<chatstate to="JID"><composing/></chatstate>

<!-- voice note about to be sent -->
<chatstate to="JID"><composing media="audio"/></chatstate>

<!-- pulse stops -->
<chatstate to="JID"><paused/></chatstate>

The plugin switches the media attr automatically based on the outbound OutboundReplyKind:

• Text reply → <composing/> for the LLM round-trip; pauses before the message lands.
• Voice note (PTT) → <composing/> while the LLM thinks, flips to <composing media="audio"/> ~250 ms before the upload + ack so the peer client has time to repaint "grabando audio…", then pauses.
• Image / video / document → not media-flagged in v1 (queued as follow-up).

Proactive voice notes (microapp-driven, no inbound trigger) get the same recording-presence wrap via the outbound dispatcher, so the indicator is consistent regardless of who initiated the send.

typing_mode knob

Plugin-instance YAML override. Default reproduces the historic behaviour.

whatsapp:
  enabled: true
  session_dir: ...
  typing_mode: instant   # default; see table below

Unknown values warn-degrade to instant rather than failing boot, so a YAML typo cannot wedge the daemon.

The keepalive cadence (10 s), TTL safety cap (60 s) and consecutive-failure circuit breaker (2 strikes) are not exposed as YAML knobs in v1 — the defaults are what every agent wants. Crate consumers that need other values can pass a PresenceHeartbeatConfig through Session::chat_presence_heartbeat_with directly.

Old-client compatibility

Pre-2021 WhatsApp clients ignore the media attribute and paint "escribiendo…" regardless. That's a degradation but harmless: the voice note still arrives; only the indicator lies. Affects <0.5 % of installs.

Idioma del agente y voz (locale BCP-47)

The agent's language field accepts a full BCP-47 locale — es-AR, es-ES, es-US, en-GB, pt-BR, etc. — and the runtime honours both the language and the region for three things on every turn:

1. Per-locale system addendum locks the LLM into the regional register: voseo for es-AR (vos, tenés, podés), tuteo + castellano vocab for es-ES (vosotros, vale, coger), Spanglish-aware for es-US (loanwords like email/parking not auto-translated), British spelling + vocab for en-GB, etc. Operators shipping language: "es" (no region) get a Latam-neutral tuteo template.

2. Voice-mode SSML tutorial — when voice mode is toggled for the conversation, the marker tutorial appended to the system prompt uses the locale's native register (so the examples don't teach the LLM a dialect it shouldn't speak).

3. Default Edge voice — when the per-conversation voice_id is the install-wide default, the picker resolves a region-matched voice:

   Locale	Voice
   es-AR	es-AR-ElenaNeural
   es-MX	es-MX-DaliaNeural
   es-ES	es-ES-ElviraNeural
   es-CO	es-CO-SalomeNeural
   es-PE	es-PE-CamilaNeural
   es-CL	es-CL-CatalinaNeural
   es-US	es-US-PalomaNeural
   en-US	en-US-AriaNeural
   en-GB	en-GB-SoniaNeural
   en-AU	en-AU-NatashaNeural
   en-CA	en-CA-ClaraNeural
   pt-BR	pt-BR-FranciscaNeural
   pt-PT	pt-PT-RaquelNeural
   fr-FR	fr-FR-DeniseNeural
   fr-CA	fr-CA-SylvieNeural
   it-IT	it-IT-ElsaNeural
   de-DE	de-DE-KatjaNeural
   ja-JP	ja-JP-NanamiNeural
   zh-CN	zh-CN-XiaoxiaoNeural

   Language-only locales fall back to the canonical region (es → es-MX, en → en-US, pt → pt-BR, …). Operators with a manually-picked voice_id keep their choice; the picker only fires when the stored voice is the install default.

The supported locale set is closed (lives in nexo_microapp_sdk::Locale); unsupported strings (klingon, es-419, zh-Hant) are rejected by the admin RPC with invalid_locale so a YAML typo cannot reach the daemon.

Behaviour change — language: "es" agents

Before this change, language: "es" agents inherited an Argentine voseo flavour from the legacy voice-mode addendum constant. The new behaviour routes language: "es" to the Latam-neutral template (tuteo, no voseo). Operators who want the previous Argentine flavour set language: "es-AR" explicitly.

Gotchas

• Shared session_dir across agents = cross-delivery. Each agent should point at its own <workspace>/whatsapp/default. The wizard does this automatically; manual configs need care.
• ignore_chat_meta: true silently skips muted/archived chats. If a user archives a chat on the phone, the agent never sees it again until they unarchive.
• Credential expiry is irreversible without re-pair. whatsapp-rs will loop on 401. Watch for credentials_expired lifecycle events and alert.

See Setup wizard — WhatsApp pairing.

Skills catalog

nexo-rs uses "skill" to mean two different things. Both are covered on this page; gating semantics for each live in Gating by env / bins.

1. Extension skills — shipped under extensions/ in the repo, discovered and spawned like any other stdio extension. 22 of them landed in Phase 13.
2. Local skills — markdown files under an agent's skills_dir/ that get injected into the system prompt at turn start.

The two overlap in name but not in mechanism:

Extension skills (Phase 13)

All shipped as stdio extensions written in Rust. _common is a shared Rust library (circuit-breaker primitives), not an extension itself.

Core utilities

Search & knowledge

Infra & ops

Media & content

Google (phase 13.18)

Single google extension covering 32 tools across Gmail, Calendar, Tasks, Drive, People, and Photos. Uses OAuth refresh-token flow. Writes gated by five independent env flags:

• GOOGLE_ALLOW_SEND — Gmail send
• GOOGLE_ALLOW_CALENDAR_WRITE
• GOOGLE_ALLOW_DRIVE_WRITE
• GOOGLE_ALLOW_TASKS_WRITE
• GOOGLE_ALLOW_PEOPLE_WRITE

See Plugins — Google for the OAuth setup and the generic google_call tool that fronts the extension.

LLM providers (phase 13.19)

anthropic and gemini are native LLM clients living under crates/llm/, not extensions. See LLM providers and children.

Templates

See Extensions — Templates.

Local skills

Local skills are markdown files loaded by SkillLoader and injected into the system prompt at turn time. Defined in the agent config:

# agents.yaml
agents:
  - id: kate
    skills_dir: ./skills
    skills:
      - weather
      - github
      - summarize
      - google-auth

Each entry resolves to <skills_dir>/<name>/SKILL.md:

---
name: "Weather"
description: "Current conditions and forecasts"
requires:
  bins: ["curl"]
  env: ["WEATHER_API_KEY"]
max_chars: 5000
---
# Weather skill

Call `weather_forecast(city)` to get a 3-day forecast.
Use metric units. Default to the user's locale when unspecified.

Bundled local skills currently shipped in this repo:

loop can be attached from setup wizard like any other skill (nexo setup → Configurar agente → Skills) because it is registered in the setup skill catalog and requires no secrets.

stuck is also attachable from setup wizard and requires no secrets.

simplify is also attachable from setup wizard and requires no secrets.

verify is also attachable from setup wizard and requires no secrets.

skillify is also attachable from setup wizard and requires no secrets.

remember is also attachable from setup wizard and requires no secrets.

update-config is also attachable from setup wizard and requires no secrets.

Loading flow

flowchart TD
    CFG[agents.yaml skills: list] --> LOOP[for each name]
    LOOP --> READ[read skills_dir/name/SKILL.md]
    READ --> FM[parse YAML frontmatter]
    FM --> GATE{bins on PATH<br/>AND env set?}
    GATE -->|no| SKIP[warn + skip<br/>not injected]
    GATE -->|yes| RENDER[render into prompt:<br/>heading + blockquote + body]
    RENDER --> TRUNC[truncate to max_chars]
    TRUNC --> INJECT[inject into system prompt]

Why local skills skip-on-miss (vs extensions warn-and-continue)

A local skill is a text instruction to the LLM describing a capability. If the backing bin/env isn't available the tool will fail — but worse, the LLM was told the capability exists and will repeatedly try to use it. Skipping the skill prevents lying to the model.

An extension is a registered tool. If the LLM invokes it and the backing bin is missing, the tool returns an error — the LLM observes and adapts. Warn-and-continue is fine.

See Gating for the full semantics.

How to pick

• Need the LLM to know how to do something (usage pattern, style rules, examples)? → local skill.
• Need the LLM to do something (make a call, return data)? → extension skill.
• Both? → ship the extension and write a local skill next to it that explains when to use it.

Plugin quickstart — zero to installed in 10 minutes

Phase 31.9. Linear, copy-paste path from empty directory to a plugin running inside an operator's daemon. Take this page once end-to-end before reading Plugin authoring overview, the Rust SDK reference, or the Plugin contract — those documents make sense faster after you have shipped one toy plugin.

Single-language path (Rust). Python / TypeScript / PHP quickstarts share the exact same shell commands; only the --lang flag and the in-repo source tree differ. Pointers to the sister SDKs appear at the bottom.

What you build

A plugin called hello_plugin that echoes every event arriving on its inbound topic onto plugin.inbound.hello_plugin_echo. By the end of this page:

• A new GitHub repository under your account holds the plugin's source.
• A signed (optional) GitHub release ships per-target tarballs.
• An operator on a separate host runs nexo plugin install <you>/<repo> and the daemon spawns your plugin inside the next 10 seconds, then logs the handshake.

This is the same pipeline that ships the in-house plugins — see github.com/lordmacu/nexo-plugin-browser for a real-world output of the same quickstart, scaled up to 12 tools.

Prerequisites

Verify each:

cargo --version          # cargo 1.80+
nexo --version           # nexo 0.1.6+
git --version
gh auth status           # if using `gh` CLI for the repo create

If nexo is not yet on PATH: curl -fsSL https://lordmacu.github.io/nexo-rs/install.sh | bash (or cargo install nexo-rs) — then make sure ~/.cargo/bin is on PATH.

1. Scaffold

The CLI bundles the same Rust template that produces the in-tree template-plugin-rust — one command lands a fresh project on disk:

nexo plugin new hello_plugin --lang rust --owner alice
cd hello_plugin

Flags that matter:

• <id> — the plugin's globally unique id. Must satisfy ^[a-z][a-z0-9_]{0,31}$. It becomes the prefix for any tool name, channel kind, or config namespace your plugin contributes.
• --lang rust — switch to python, typescript, or php for the matching template. The remaining steps are identical.
• --owner alice — your GitHub username. Used in the generated README + CI workflow's release URL.
• --description "..." — optional one-liner; flows into the manifest + README + Cargo description.
• --git — runs git init for you and stages the initial commit.
• --dest /custom/path — emit elsewhere (default is ./<id>/).

Re-running the command on a non-empty directory aborts; pass --force only if you mean it.

2. Inspect what landed

hello_plugin/
├── Cargo.toml               # name = "hello_plugin", bin name matches plugin.id
├── nexo-plugin.toml         # manifest — read by the daemon at handshake
├── README.md                # operator-facing docs (edit these later)
├── scripts/
│   └── pack-tarball.sh      # the per-target tarball packer the CI uses
├── src/
│   └── main.rs              # tokio::main + PluginAdapter
└── tests/
    └── pack_tarball.rs      # regression test for the asset shape

Two files you must know intimately. Open both:

nexo-plugin.toml:

[plugin]
id = "hello_plugin"
version = "0.1.0"
name = "Hello Plugin"
description = "Echoes inbound events back onto the broker."
min_nexo_version = ">=0.1.0"

[plugin.requires]
nexo_capabilities = ["broker"]

[[plugin.channels.register]]
kind = "hello_plugin_inbound"
description = "Inbound events the plugin emits onto the broker."

[plugin.entrypoint]
command = "./bin/hello_plugin"   # resolved relative to this file

plugin.entrypoint.command = "./bin/hello_plugin" is the Phase 31.1.c install convention. The daemon's discovery walker reads the manifest, then spawns whatever command resolves to, relative to the manifest's containing directory. The pack-tarball step (step 8) copies your release binary into bin/hello_plugin so this entrypoint resolves on the operator host.

src/main.rs (truncated):

use nexo_broker::Event;
use nexo_microapp_sdk::plugin::{BrokerSender, PluginAdapter};

const MANIFEST: &str = include_str!("../nexo-plugin.toml");

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt()
        .with_writer(std::io::stderr)
        .init();

    PluginAdapter::new(MANIFEST)?
        .on_broker_event(handle_event)
        .on_shutdown(|| async { Ok(()) })
        .run_stdio()
        .await?;
    Ok(())
}

async fn handle_event(topic: String, event: Event, broker: BrokerSender) {
    let echo = Event::new(
        "plugin.inbound.hello_plugin_echo",
        "hello_plugin",
        serde_json::json!({
            "echoed_from": topic,
            "echoed_payload": event.payload,
        }),
    );
    let _ = broker.publish("plugin.inbound.hello_plugin_echo", echo).await;
}

The contract is small: build a PluginAdapter from your manifest text, register handlers, call run_stdio().await. The SDK owns the JSON-RPC envelope — you only see decoded Events.

Stdout discipline — every byte on stdout must be a JSON-RPC frame. Use eprintln! / tracing::* for plugin-side logs; a stray println! will corrupt the wire and the daemon will tear the subprocess down at handshake.

3. Build

cargo build

A debug binary lands at target/debug/hello_plugin in well under a second on a warm cache (mold + sccache, configured machine-wide on the dev box, are not required — vanilla cargo works too).

4. Smoke-test the handshake

Two probes the daemon performs at boot. Both must pass before the plugin shows up in nexo plugin list.

4.a — --print-manifest

The discovery walker (Phase 81.33 Stage 8) invokes each nexo-plugin-* binary with --print-manifest and reads the embedded TOML from stdout. Confirm yours obeys:

./target/debug/hello_plugin --print-manifest

Expected output: verbatim contents of nexo-plugin.toml, followed by exit 0. The scaffold wires the print_manifest_if_requested(MANIFEST) call into the first line of main(); if you see logs, JSON-RPC frames, or empty stdout, the helper is missing.

4.b — initialize handshake

Hand-feed a JSON-RPC initialize frame to verify the wire shape:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
    | ./target/debug/hello_plugin

Expected output (one line of JSON, formatted here for readability):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "manifest": { "plugin": { "id": "hello_plugin", ... } },
    "server_version": "hello_plugin-0.1.0",
    "tools": []
  }
}

If you see anything else — extra blank lines, panic backtrace, malformed JSON — fix that before moving on. The daemon will reject the same frame your terminal saw.

5. Local dev loop

Boot a daemon with this directory injected at the head of plugins.discovery.search_paths. No install, no GitHub round trip, no signature verification — pure inner-loop dev:

nexo plugin run .

Expected stderr trace:

INFO local plugin override applied (plugin_id=hello_plugin)
INFO subprocess plugin spawned (id=hello_plugin, pid=...)
INFO hello_plugin starting
INFO subprocess plugin handshake ok (id=hello_plugin, version=0.1.0)

The plugin is now live inside the daemon. Ctrl+C tears both processes down cleanly.

Edit src/main.rs, re-run cargo build, and the daemon's hot-reload walker (Phase 81.10) re-spawns the subprocess automatically — no daemon restart.

For isolated contract debugging without your real agents.yaml, add --no-daemon-config. See Local dev loop conventions for the inner-loop reference.

6. Customize the handler

Replace the body of handle_event with whatever your plugin should do — call a third-party API, persist to disk, trigger a downstream agent. Re-publish the API's reply back through broker.publish so agents can observe it.

Eight common shapes (channel plugin, poller, hybrid bridge, etc.) are pre-baked in Patterns. Browse those once before designing — most plugins fit one of those shapes exactly.

7. Push to GitHub

gh repo create alice/hello_plugin --public --source=. --push

Or, with plain git:

git init && git add . && git commit -m "initial plugin"
git remote add origin git@github.com:alice/hello_plugin.git
git push -u origin main

The scaffolded repo already contains .github/workflows/release.yml (the Phase 31.2 template). The workflow fires on tag push (v*).

8. Cut a release

Bump the version in Cargo.toml and nexo-plugin.toml (must match), then tag and push:

# bump both files first — keep them in lock-step
git add Cargo.toml nexo-plugin.toml
git commit -m "v0.1.0"
git tag v0.1.0
git push origin main v0.1.0

Watch the workflow in the GitHub Actions tab. The four jobs shipped by the template:

1. validate-tag — refuses to release if the manifest version does not match the tag.
2. build — compiles the plugin for linux-x64 and macos-arm64 (extend the matrix yourself for more targets), runs pack-tarball.sh to produce the bin/hello_plugin + nexo-plugin.toml archive layout operators expect, and uploads <id>-<version>-<target>.tar.gz plus .sha256 sidecars.
3. sign (optional, gated by repo variable COSIGN_ENABLED) — cosign keyless signature against the GitHub Actions OIDC identity. See Signing & publishing for the full keyless tutorial.
4. release — creates the GitHub Release, attaches every tarball, every .sha256, the bare nexo-plugin.toml (so nexo plugin install can resolve manifest URL early), and the optional cosign material.

When the workflow turns green, the release page contains the exact asset shape nexo plugin install resolves against. See Publishing a plugin for the full asset naming convention.

9. Install on an operator host

Three install routes, depending on how you shipped the plugin:

9.a — cargo install (zero config)

Recommended for crates.io-published plugins. The daemon's discovery defaults already cover $HOME/.cargo/bin:

cargo install nexo-plugin-hello_plugin
nexo plugin list

The discovery walker invokes the binary with --print-manifest on next daemon boot (or next hot-reload tick under Phase 81.10), extracts the embedded TOML, and registers the plugin. No operator YAML edit. Authoring detail: Auto-discovery quickstart.

9.b — nexo plugin install (GitHub releases)

When you ship tarballs to GitHub releases instead of (or in addition to) crates.io:

nexo plugin install alice/hello_plugin@v0.1.0

The installer (Phase 31.1.c):

1. Hits https://api.github.com/repos/alice/hello_plugin/releases/tags/v0.1.0.
2. Picks the tarball matching the host's target triple.
3. Downloads tarball + .sha256, verifies the digest.
4. Optionally verifies cosign signature (default off; flip on with --require-signature after configuring trusted keys — see Plugin trust).
5. Extracts to <state_root>/plugins/hello_plugin-0.1.0/{nexo-plugin.toml, bin/hello_plugin, .nexo-install.json}.
6. Records the install in the per-host install ledger.

The daemon's plugins.discovery.search_paths defaults include $HOME/.local/share/nexo/plugins and /usr/local/libexec/nexo/plugins. Move (or symlink) the extracted directory under one of those to skip the YAML edit, or point a custom search_paths entry at <state_root>/plugins/.

9.c — Drop-in (manual)

Copy the binary into any default search path:

cp ./target/release/hello_plugin ~/.cargo/bin/nexo-plugin-hello_plugin
chmod +x ~/.cargo/bin/nexo-plugin-hello_plugin

Re-discovery happens on next daemon boot (or hot-reload).

10. Verify

nexo plugin list

Expected output:

ID            VERSION  TARGET                       CHANNEL  INSTALLED
hello_plugin  0.1.0    x86_64-unknown-linux-gnu     latest   2026-05-07T18:20:42+00:00

Daemon stderr should show the handshake within ~5 seconds:

INFO subprocess plugin spawned (id=hello_plugin, pid=...)
INFO subprocess plugin handshake ok (id=hello_plugin, version=0.1.0)

Publish anything onto an inbound topic the plugin subscribed to (e.g. agent broker publish-equivalent inside your microapp) and the echo lands on plugin.inbound.hello_plugin_echo.

Iterate

# bump in source, push tag
git tag v0.1.1 && git push origin v0.1.1

# operator-side
nexo plugin upgrade hello_plugin            # pulls latest tag
# or pin: nexo plugin upgrade hello_plugin --version v0.1.1

nexo plugin upgrade (Phase 31.8) atomically swaps the on-disk copy + restarts the subprocess inside the daemon. To roll back, re-run install against the older tag.

To remove:

nexo plugin remove hello_plugin

Troubleshooting

Going deeper

You shipped one plugin. From here:

• Plugin authoring overview — the full picture (plugin vs extension vs microapp, plugin config dir, sandboxing, contributing tools / channel kinds / LLM providers / memory backends / hooks).
• Rust SDK reference — full PluginAdapter surface, manifest schema, per-target tarball convention.
• Plugin contract — the wire spec every SDK implements. Read this once and you can debug any plugin in any language.
• Patterns (8 common shapes) — pre-baked designs for channels, pollers, hybrid bridges.
• Publishing a plugin — full asset naming convention and the 4-job CI workflow shape.
• Signing & publishing — cosign keyless tutorial.

Other languages

Same flow, swap step 1's --lang:

Steps 2–10 read identically; the source tree differs (no Cargo.toml, language-appropriate runtime). The wire contract is the same.

Plugin authoring overview

Phase 31.9. Entry point for authors building anything that extends nexo-rs from the outside. This page gets you to the right deeper guide in 60 seconds.

Read this when

• You want to add capability to nexo-rs and have not yet picked between a plugin, an extension, or a microapp.
• You have picked "plugin" and need to know which language SDK to start with.
• You want a 5-minute end-to-end smoke test before committing to a language choice.

Plugin vs Extension vs Microapp

nexo-rs ships three extension surfaces. They differ in who owns the runtime, who owns the UI, and how operators install them.

If you are still unsure:

• Plugin if your code is reactive (broker.event fires → you do something) and ships as a binary the daemon spawns.
• Extension if your code is declarative (skills + agents + prompts) and ships as a tarball operators install with nexo ext install.
• Microapp if your code is the product. End users see your UI, your domain, your billing — nexo-rs is invisible infrastructure.

This page covers plugins. For extensions, jump to Manifest reference. For microapps, jump to Microapps · getting started.

Pick a language

All four SDKs implement the same wire contract — your choice is purely about ergonomics. Operators don't care which SDK you picked; they just run nexo plugin install <owner>/<repo>.

Cross-cutting reference: Plugin contract is the wire spec all four SDKs implement. Read it once and you understand every SDK.

SDK packages

nexo plugin new --lang <lang> vendors the SDK for you, so you don't normally install it by hand — but if you're wiring the SDK into an existing project, the published packages are:

The Python / TypeScript / PHP SDKs live in one mono-repo — lordmacu/nexo-plugin-sdks (per-language release tags python-v* / ts-v* / php-v*). The Rust SDK ships from this repo (crates/microapp-sdk, feature plugin).

Microapp, not plugin? The product layer uses the same nexo-microapp-sdk crate without the plugin feature (its admin / voice / stt / wizard / events modules instead), plus the @lordmacu/nexo-microapp-ui-react React kit for the frontend. See Microapps · getting started and the agent-creator reference microapp.

5-min quickstart

The shortest path from zero to a running plugin uses Rust because the toolchain ships with cargo. Adapt the nexo plugin new --lang <other> step for Python / TypeScript / PHP — the rest is identical.

For the full zero-to-installed flow (scaffold → publish to crates.io → operator-side cargo install nexo-plugin-X → daemon auto-discovery), see the linear Plugin quickstart (10 min). This section is the abridged inner-loop version.

# 1. Scaffold from the bundled template (Phase 31.6).
nexo plugin new my_plugin --lang rust --owner alice
cd my_plugin

# 2. Build (under a second on a warm cache).
cargo build

# 3. Boot the daemon with this directory injected at the head
#    of plugins.discovery.search_paths. No install, no verify,
#    no GitHub round-trip — pure inner-loop dev.
nexo plugin run .

Expected stderr trace from step 3:

INFO local plugin override applied (plugin_id=my_plugin)
INFO subprocess plugin spawned (id=my_plugin, pid=...)
INFO my_plugin starting
INFO subprocess plugin handshake ok (id=my_plugin, version=0.1.0)

The plugin is now live. Publishing any event on a topic the plugin's manifest registers (default plugin.inbound.my_plugin_echo) reaches the handler in src/main.rs::handle_event.

To exit, send Ctrl+C — the daemon issues a shutdown request, the plugin's on_shutdown runs, and both processes return cleanly.

Plugin config dir

Phase 81.4 — operators place per-plugin YAML config under <config_dir>/plugins/<plugin_id>/. The daemon reads every *.yaml / *.yml file in that directory at boot, deep-merges them alphabetically, resolves ${ENV_VAR} placeholders, and (when your manifest declares a schema_path) validates the merged tree against your JSONSchema before calling init(). Validation failure aborts plugin load with InitOutcome::Failed; the daemon continues without the plugin.

Multi-file sharding lets operators split sensitive settings from declarative ones:

<config_dir>/plugins/slack/
  01-credentials.yaml   # api_token: "${SLACK_BOT_TOKEN}"
  02-channels.yaml      # channels: [...]
  03-allowlist.yaml     # rate limits per channel

Mappings deep-merge across files (later wins per-key). Arrays full-replace — they don't concat — so an operator override file completely substitutes the array from earlier files. Comment-only and non-.yaml files are ignored.

Declare your config schema in nexo-plugin.toml:

[plugin.config]
schema_path = "config.schema.json"   # relative to plugin root
hot_reload = true                    # parsed; wiring lands in 81.4.b

The schema validator currently supports the JSONSchema subset type / required / properties / additionalProperties / enum. Plugins needing oneOf / $ref / pattern will get richer validation in a future 81.4.c slice — for now, those keywords pass through silently.

Inside your plugin, consume ctx.plugin_config (an Arc<serde_yaml::Value>):

#![allow(unused)]
fn main() {
let api_token = ctx
    .plugin_config
    .get("api_token")
    .and_then(serde_yaml::Value::as_str)
    .ok_or_else(|| anyhow::anyhow!("api_token missing"))?;
}

When the operator hasn't placed any config files, the value is an empty mapping — your plugin sees Value::Mapping(empty), not Null. Plugins with all-optional fields boot cleanly without operator action.

Contributing channel kinds

Phase 81.24 — subprocess plugins that declare [plugin.extends].channels = [...] automatically get a host-side RemoteChannelAdapter registered for each kind. The daemon's ChannelAdapterRegistry routes outbound dispatches to your subprocess via three JSON-RPC methods:

• channel.start { kind, instance } — subscribe outbound topics + begin publishing inbound (default 30 s timeout)
• channel.stop { kind } — release resources (30 s)
• channel.send_outbound { kind, msg } — send one outbound message; reply with { message_id, sent_at_unix } (60 s)

Wire spec + error codes: Plugin contract §5.x.

Sketch (Rust subprocess plugin) — handle each request from your adapter's reader loop:

#![allow(unused)]
fn main() {
match method {
    "channel.start" => reply_ok(id, serde_json::json!({ "ok": true })),
    "channel.stop"  => reply_ok(id, serde_json::json!({ "ok": true })),
    "channel.send_outbound" => {
        let msg = params.get("msg").cloned().unwrap_or_default();
        // Forward `msg` to your provider's API; map the API's
        // response into OutboundAck.
        let ack = send_to_slack(msg).await?;
        reply_ok(id, serde_json::json!({
            "message_id": ack.id,
            "sent_at_unix": ack.ts,
        }));
    }
    _ => reply_method_not_found(id, method),
}
}

For typed errors (rate-limit, recipient invalid, etc.), reply with the channel-specific error codes from the contract table — the host's adapter maps them to ChannelAdapterError variants the agent runtime understands.

The matching SDK helpers (handle_channel_start / handle_channel_send_outbound etc.) ship in Phase 81.24.b. Until then, hand-handle the JSON-RPC frames using the SDK's existing primitives.

Contributing LLM providers

Phase 81.25 — subprocess plugins that declare [plugin.extends].llm_providers = [...] get one host-side RemoteLlmFactory registered into LlmRegistry per provider name. When the agent runtime resolves model.provider = "<name>", the factory builds a RemoteLlmClient that translates trait calls into llm.chat JSON-RPC requests over your subprocess plugin's stdio pipe.

[plugin.extends]
llm_providers = ["cohere", "mistral"]

Two modes supported on the wire:

• Sync — params.stream = false; reply once with WireChatResponse (default 60 s timeout).
• Streaming — params.stream = true; emit zero or more llm.chat.delta { request_id, chunk } notifications + one final response carrying usage / finish_reason (default 300 s timeout).

Wire spec + error codes: Plugin contract §5.y.

Sketch (Rust subprocess plugin) — handle llm.chat from your adapter's reader loop:

#![allow(unused)]
fn main() {
match method {
    "llm.chat" => {
        let provider = params["provider"].as_str().unwrap_or("");
        let stream = params["stream"].as_bool().unwrap_or(false);
        let request = serde_json::from_value::<WireChatRequest>(
            params["request"].clone()
        )?;
        if stream {
            // Emit zero or more deltas
            send_notification("llm.chat.delta", json!({
                "request_id": id,
                "chunk": { "type": "text_delta", "delta": "Hello" },
            }));
            // ...then the final response.
            reply_ok(id, /* WireChatResponse with usage + finish_reason */);
        } else {
            // Sync: call your provider's API, build WireChatResponse.
            let resp = call_my_provider(provider, &request).await?;
            reply_ok(id, resp);
        }
    }
    _ => reply_method_not_found(id, method),
}
}

For typed errors (rate-limit, auth failed, model not found), reply with the LLM-specific error codes from the contract table — the host's RemoteLlmClient surfaces them as anyhow::Error with operator-greppable messages.

The matching SDK helpers (PluginAdapter::handle_llm_chat, streaming sender, etc.) ship in Phase 81.25.b. Until then, hand-handle the JSON-RPC frames.

Contributing hook handlers

Phase 81.27 — subprocess plugins that declare [plugin.extends].hooks = [...] get one host-side RemoteHookHandler registered into HookRegistry per hook name. When the daemon fires that hook, the handler translates the call into a hook.on_hook JSON-RPC request over your subprocess plugin's stdio pipe.

[plugin.extends]
hooks = ["before_message", "after_message"]

Wire spec + error semantic: Plugin contract §5.z.

The reply shape is the existing HookResponse struct:

#![allow(unused)]
fn main() {
HookResponse {
    abort: bool,                     // legacy block signal
    reason: Option<String>,          // operator-readable
    override: Option<Value>,         // key-by-key mutation
    decision: Option<String>,        // "allow" | "block" | "transform"
    transformed_body: Option<String>,// for "transform"
    do_not_reply_again: bool,        // anti-loop signal
}
}

Sketch (Rust subprocess plugin) — handle each hook by name:

#![allow(unused)]
fn main() {
match method {
    "hook.on_hook" => {
        let hook_name = params["hook_name"].as_str().unwrap_or("");
        let event = params["event"].clone();
        let response = match hook_name {
            "before_message" => check_pii(&event)?,    // your logic
            "after_message"  => log_audit(&event)?,
            _ => HookResponse::default(),               // Continue
        };
        reply_ok(id, serde_json::to_value(&response)?);
    }
    _ => reply_method_not_found(id, method),
}
}

Continue-on-error semantic — the host swallows every dispatch failure (timeout, malformed reply, JSON-RPC error) and returns HookResponse::default() so the registry's fire loop keeps iterating. Failures land in tracing::warn! for operator debugging but never break the agent flow. This means:

• Returning -32601 method_not_found for an unknown hook is fine — host logs + continues.
• A hung subprocess hook eventually times out (5s default; NEXO_PLUGIN_HOOK_TIMEOUT_MS env override) and the agent proceeds.
• Returning a malformed HookResponse still continues; only well-formed responses with abort: true or decision: "block" actually block.

Hooks fire on the message hot path — keep handler latency low (<50 ms typical). Use the decision: "transform" path sparingly: every transform rewrites the event payload for subsequent handlers.

Contributing memory backends

Phase 81.26 — subprocess plugins that declare [plugin.extends].memory_backends = [...] get one host-side RemoteVectorBackend registered into the daemon's VectorBackendRegistry per backend name. v1 covers VECTOR storage only — short/long-term memory keep their SQLite implementation; plugins replace only the vector index. Primary use case: Pinecone / Qdrant / Weaviate / pgvector.

[plugin.extends]
memory_backends = ["pinecone"]

Three wire methods (default timeouts 30s upsert/delete, 10s search):

• memory.vector_upsert { backend, collection, records } → { count }
• memory.vector_search { backend, collection, query } → { matches: [...] }
• memory.vector_delete { backend, collection, ids } → { count }

NEXO_PLUGIN_MEMORY_TIMEOUT_MS env overrides all three.

Wire spec + error codes: Plugin contract §5.w.

Sketch (Rust subprocess plugin) — handle each method by name:

#![allow(unused)]
fn main() {
match method {
    "memory.vector_upsert" => {
        let collection = params["collection"].as_str().unwrap_or("");
        let records: Vec<VectorRecord> = serde_json::from_value(
            params["records"].clone()
        )?;
        let count = my_pinecone_client.upsert(collection, records).await?;
        reply_ok(id, serde_json::json!({"count": count}));
    }
    "memory.vector_search" => {
        let collection = params["collection"].as_str().unwrap_or("");
        let query: VectorQuery = serde_json::from_value(
            params["query"].clone()
        )?;
        let matches = my_pinecone_client.search(collection, query).await?;
        reply_ok(id, serde_json::json!({"matches": matches}));
    }
    "memory.vector_delete" => {
        let collection = params["collection"].as_str().unwrap_or("");
        let ids: Vec<String> = serde_json::from_value(
            params["ids"].clone()
        )?;
        let count = my_pinecone_client.delete(collection, ids).await?;
        reply_ok(id, serde_json::json!({"count": count}));
    }
    _ => reply_method_not_found(id, method),
}
}

For typed errors (collection-not-found, dimension-mismatch, rate-limited, write-failed), reply with the memory-specific error codes from the contract table — the host's RemoteVectorBackend surfaces them as anyhow::Error with operator-greppable messages.

v1 limitation: registered backends are NOT yet consumed at runtime — LongTermMemory.recall_vector still uses sqlite-vec. Operators audit registered backends today via wire.vector_backend_registry.names(). Consumer-side dispatch (agents.yaml.<id>.vector_backend = "pinecone") lands in Phase 81.26.b.

Contributing tools

Phase 81.29 — subprocess plugins can expose tools that the daemon's LLM picks via function-calling. Each tool name lives in [plugin.extends].tools = [...] plus the subprocess advertises the matching schema at handshake.

[plugin]
id = "browser"
# ... other manifest fields ...

[plugin.extends]
tools = ["browser_navigate", "browser_click"]

The subprocess MUST advertise these tools in the initialize-reply's tools array:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "manifest": { "plugin": { "id": "browser", ... } },
    "server_version": "browser-0.1.1",
    "tools": [
      {
        "name": "browser_navigate",
        "description": "Navigate to a URL",
        "input_schema": {
          "type": "object",
          "properties": { "url": { "type": "string" } },
          "required": ["url"]
        }
      }
    ]
  }
}

When the agent's LLM picks a tool the daemon issues a tool.invoke JSON-RPC request to the subprocess:

{
  "jsonrpc": "2.0",
  "id": 80,
  "method": "tool.invoke",
  "params": {
    "plugin_id": "browser",
    "tool_name": "browser_navigate",
    "args": { "url": "https://example.com" },
    "agent_id": "shopper"
  }
}

The plugin replies with the tool's result (typically a ToolResponse-shaped object). Errors use the -33401..=-33405 band documented in Plugin contract §5.t.

Validation rules (host-side):

• Tool names MUST satisfy the per-plugin namespace policy from Phase 81.3 (<plugin_id>_* or ext_<plugin_id>_*).
• The advertised tools array MUST be a subset of extends.tools — drift in this direction is a hard failure at handshake.
• Manifest entries WITHOUT an advertised counterpart are tolerated but logged at warn; runtime calls yield -33401 ToolNotFound.

Plugin-side responsibilities:

• Validate args against the published input_schema before executing (defense in depth — host already validates host- side, but plugins should re-check).
• Return -33402 ToolArgumentInvalid with details: <Value> pointing to the offending field if validation fails.
• Return -33404 ToolUnavailable with data: { retry_after_ms: <u64> } for transient failures (rate-limits, locked resources).

Default timeout: 60 s (matches the LLM band — tools span fast browser_click to slow browser_navigate). Operator override via NEXO_PLUGIN_TOOL_TIMEOUT_MS.

v1 limitations — see follow-ups in FOLLOWUPS.md: streaming tools (chunked outputs via tool.invoke.delta), per-tool timeout knobs in manifest, SDK helper PluginAdapter::on_tool(name, handler).

Sandboxing your plugin

Phase 81.22 — Linux subprocess plugins can opt into bubblewrap isolation by declaring [plugin.sandbox] in nexo-plugin.toml. Default is disabled, so existing plugins keep today's behavior; opt in when you want defense-in-depth.

[plugin.sandbox]
enabled = true
network = "deny"                       # "deny" | "host"
fs_read_paths = ["/etc/ssl/certs"]    # absolute paths only
fs_write_paths = ["${state_dir}"]     # ${state_dir} = per-plugin
                                       # state root, the only safe
                                       # writable place by default
drop_user = true                       # nobody:nogroup uid mapping

Linux prereq: install bubblewrap (apt install bubblewrap on Debian/Ubuntu, available on Arch + Alpine + Fedora). The daemon discovers bwrap once at boot via PATH lookup. Without bwrap, sandbox-enabled plugins log a warning and run unsandboxed unless NEXO_PLUGIN_SANDBOX_REQUIRE=1 is set (in which case boot fails).

macOS: not yet enforced. The daemon logs a tracing::warn! at every spawn and runs the plugin without sandbox. Native sandbox-exec integration is deferred to follow-up 81.22.macos (deprecated-API risk noted).

Network policy:

• network = "deny" → plugin runs in an isolated network namespace with only loopback. Use the host's daemon-mediated RPCs (llm.complete, memory.recall, broker.publish) for any external IO. Recommended default.
• network = "host" → plugin shares the daemon's network. Operator must opt in via NEXO_PLUGIN_SANDBOX_HOST_NET_ALLOW=1; manifest validation rejects this otherwise. Use only when daemon-mediated RPCs cannot satisfy your plugin's IO needs.

Filesystem allowlist:

• fs_read_paths = host paths bound read-only into the sandbox (bwrap --ro-bind). Common: /etc/ssl/certs for outbound TLS verification.
• fs_write_paths = host paths bound read-write (bwrap --bind). The literal ${state_dir} token expands at spawn time to <state_root>/plugins/<plugin_id> — that is your plugin's per-instance owned scratch space. Only token recognized; only valid in fs_write_paths.

Hard denylist (compile-time, not configurable): allowlist entries that equal or include any of these paths are rejected at manifest validation:

/etc/shadow, /etc/sudoers, /etc/sudoers.d
/proc/sys, /proc/kcore, /proc/kallsyms
/sys/firmware, /sys/kernel
/dev/mem, /dev/kmem, /dev/port
/var/run/docker.sock, /run/docker.sock,
  /private/var/run/docker.sock
/root, /boot

Operator capability env knobs:

Recommended pattern: enabled = true, network = "deny", fs_write_paths = ["${state_dir}"], no fs_read_paths unless your plugin truly needs to read host config (e.g. CA bundles for TLS). Use daemon-mediated RPCs for everything else.

v1 out of scope — see follow-ups in FOLLOWUPS.md: granular network egress allowlist (81.22.b), per-syscall seccomp filters (81.22.c), nexo agent doctor plugins sandbox section (81.22.d), native macOS sandbox-exec (81.22.macos).

Future capability extensions

Phase 81.28 — subprocess plugins that contribute new channel kinds, LLM providers, memory backends, or HookInterceptor IDs declare them via an additive [plugin.extends] manifest section:

[plugin.extends]
channels         = ["slack"]              # paired with Phase 81.24 wrapper
llm_providers    = ["cohere"]             # paired with Phase 81.25
memory_backends  = ["pinecone"]           # paired with Phase 81.26
hooks            = ["pii_redact"]         # paired with Phase 81.27

Each list names the IDs the plugin contributes. Validation rules + the canonical schema live in Plugin contract §2.1. Daemon dispatch wiring (actually populating the matching registry slots) ships per-registry across Phase 81.24-27 — the schema is shipped today so subprocess plugin authors can declare intent ahead of those wrappers landing.

Local dev loop conventions

• nexo plugin run <path> — boots the daemon with one local plugin overriding discovery; the rest of the system (broker, agents, channels) runs as configured.
• nexo plugin run <path> --no-daemon-config — same, but clears cfg.agents.agents so the plugin runs in isolation for contract debugging.
• Rebuild → respawn — Phase 81.10 hot-reload re-walks search_paths periodically, so a fresh cargo build triggers the daemon to respawn the subprocess automatically. No --watch flag yet (Phase 31.7.b deferred).

Next steps

• Rust SDK — full Rust API + manifest example.
• Python SDK, TypeScript SDK, PHP SDK — language-specific references with the same shape.
• Plugin contract — wire spec; read this once and you can debug any SDK.
• Patterns (8 common shapes) — pre-baked designs for channel plugins, pollers, hybrid bridges.
• Publishing a plugin — asset naming convention + 4-job CI workflow shape.
• Signing & publishing — cosign keyless tutorial that operators on --require-signature need.
• Plugin trust (trusted_keys.toml) — operator-side verification policy your readers will configure to trust your releases.

Plugin manifest (Phase 81.13 unified)

Phase 81.13 unified the framework's two manifest parsers (nexo-extensions::manifest Phase 11 + nexo-plugin-manifest Phase 31.5+) into a single source of truth. Plugin authors now ship one TOML manifest at the plugin root that declares both the legacy contributions (tools / hooks / channels / providers / pollers) AND the modern admin RPC + HTTP server capabilities.

Filename

The canonical filename is plugin.toml. The framework also accepts nexo-plugin.toml as a legacy fallback for one deprecation cycle so existing plugins keep loading without an immediate rename. When both files are present in the same plugin root, plugin.toml wins and the daemon emits a warning.

Plugins authored after 81.13 should ship plugin.toml only.

Versioning

The TOML root may carry a manifest_version integer:

• omitted or 1 → legacy v1 shape (flat [capabilities], [transport], [meta], [mcp_servers], [outbound_bindings], [context], [requires]). The parser auto-translates to v2 in memory and emits a one-shot deprecation warn per plugin.
• 2 → canonical Phase 81.13 shape. New plugins should set this explicitly to opt out of the deprecation warn.

Unknown values produce a clear parse error.

ID regex

Plugin ids match ^[a-z][a-z0-9_-]{0,63}$ (lowercase, starts with letter, body of letters/digits/underscores/hyphens, length 64). Both agent_creator and agent-creator styles are valid; the framework normalises neither so plugin authors get to pick.

Reserved ids that no plugin can claim (defended at boot): agent, browser, core, email, heartbeat, memory, telegram, whatsapp.

Where the legacy fields land

Pre-81.13 plugins kept their plugin.toml flat (Phase 11 shape). Those still parse — the compat layer translates each section as follows:

The "DROPPED" entries don't break boot — the parser logs the list of legacy fields it saw + skipped per plugin. Consumers that needed those fields keep reading them via the legacy nexo-extensions::manifest::ExtensionManifest::from_path path, which still parses the v1 shape directly.

Single-file canonical example

manifest_version = 2

[plugin]
id               = "agent_creator"
version          = "0.0.35"
name             = "Agent Creator"
description      = "Operator UI microapp."
min_nexo_version = ">=0.1.0"

[plugin.entrypoint]
command = "./agent-creator"
args    = []

[plugin.capabilities.admin]
required = ["agents_crud", "skills_crud", "llm_keys_crud"]
optional = ["channels_crud", "auth_rotate", "secrets_write"]

[plugin.capabilities.http_server]
port        = 8765
bind        = "127.0.0.1"
token_env   = "AGENT_CREATOR_TOKEN"
health_path = "/healthz"

[plugin.meta]
author     = "Cristian García"
license    = "MIT OR Apache-2.0"
homepage   = "https://example.com"
repository = "https://github.com/x/y"

Pre-81.13 example (still valid via compat)

[plugin]
id          = "agent-creator"
version     = "0.0.34"
name        = "Agent Creator"
description = "Operator UI microapp."

[capabilities]
tools = ["agent_list", "agent_get"]
hooks = ["before_message"]

[capabilities.admin]
required = ["agents_crud"]
optional = ["channels_crud"]

[transport]
kind    = "stdio"
command = "./agent-creator"

[meta]
author = "Cristian"

The framework parses this as manifest_version = 1 (auto- detected), translates to v2 in memory + emits a deprecation warn once at boot. Operator can migrate at their own pace.

Deferred (sub-phase 81.13.b)

• Preserve legacy mcp_servers / outbound_bindings / context / requires.bins+env / capabilities.tools+hooks+channels+providers+pollers / transport.kind=nats|http / plugin.priority in the canonical v2 shape so the migrator stops dropping them.
• Hard removal of nexo-plugin.toml filename + manifest_version = 1 mode (target: 0.2.0).
• JSON-Schema export for editor autocomplete (mirrors OpenClaw's openclaw.plugin.json).

[plugin.config_schema] (Phase 93.1)

Plugins ship their config contract inside their own manifest so the daemon never hardcodes a per-plugin field. Optional — plugins without a config block (or those still on typed cfg.plugins.X through the Phase 93.5 deprecation window) omit the section.

# Multi-instance plugin (telegram, whatsapp, …).
[plugin.config_schema]
shape = "array"
schema = """{
  "type": "object",
  "properties": {
    "instance":      { "type": "string" },
    "bot_token_env": { "type": "string" },
    "enabled":       { "type": "boolean" }
  },
  "required": ["instance", "bot_token_env"]
}"""

# Single-instance plugin (email, browser, google).
[plugin.config_schema]
shape = "object"
schema = """{
  "type": "object",
  "properties": {
    "imap_host":    { "type": "string" },
    "smtp_host":    { "type": "string" },
    "username_env": { "type": "string" }
  },
  "required": ["imap_host", "smtp_host", "username_env"]
}"""

Fields

Static validation

cargo run --bin nexo manifest validate rejects malformed schemas with ManifestError::PluginConfigInvalidSchema { plugin_id, reason }:

• Empty schema string.
• schema is not valid JSON.
• schema parses to a JSON value that is not an object.
• Root object's "type" is not "object".

Operator YAML against schema runs at boot (Phase 93.2) using the same lightweight validator already shipping for install-time microapp config (Phase 83.17).

Runtime delivery (Phase 93.2)

Once schema validation passes, the host calls the plugin's NexoPlugin::configure(value) async hook with the operator's YAML slice. The trait method has a default no-op so plugins that haven't migrated keep working through the Phase 93.5 deprecation window.

Subprocess plugins receive the same value over their stdio JSON-RPC channel as a plugin.configure request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "plugin.configure",
  "params": { "value": <operator-YAML-as-JSON> }
}

The host BUFFERS the value during the brief window between configure(value) and the child's spawn completing; the buffered value is delivered automatically after initialize acks. Plugin SDKs should treat plugin.configure as re-entrant — hot-reload sends a fresh request when the operator's YAML changes.

Three error categories from PluginConfigureError:

Configure-then-init is the boot order: init's registrations may inspect what configure accepted, so the plugin sees a consistent world from the first init call onward.

Operator config delivery (Phase 93.3)

The daemon walks <config_dir>/plugins/*.yaml at boot and feeds each file into cfg.plugins.entries.<plugin_id> keyed by the filename stem. A new community plugin lands by dropping <config_dir>/plugins/slack.yaml; the daemon discovers it, matches the file's stem to manifest.plugin.id == "slack", and routes the parsed value into NexoPlugin::configure(value). Zero daemon-side edits.

Outer-wrapper-key strip is conservative — only when the YAML's single top-level key matches the filename stem:

# config/plugins/slack.yaml
slack:                            # ← stripped
  token_env: SLACK_BOT_TOKEN

becomes entries["slack"] == { token_env: SLACK_BOT_TOKEN }. If the operator's top-level key doesn't match the stem, the whole mapping is preserved verbatim — plugins decide how to interpret.

discovery.yaml is filtered (framework-internal). Parse failures log tracing::warn! on the plugins.config target and skip the file; other plugins still boot. Init-loop emits a tracing::info! when both entries.<id> AND the legacy plugins/<id>/*.yaml subdir populate — operator-visible deprecation-window state; entries always wins.

[plugin.pairing.adapter] — manifest-driven pairing adapter

Phase 81.33.b.real (Stage 1 of the plugin auto-discovery design). Status: shipped 2026-05-15.

Plugins that expose a channel with a DM-pairing flow declare the broker dispatch contract for the daemon's PairingChannelAdapter in nexo-plugin.toml. The daemon constructs a GenericBrokerPairingAdapter from the manifest and registers it into the shared PairingAdapterRegistry. This replaces the previous design where the daemon had to hardcode Arc::new(<plugin>PairingAdapter::new(broker)) blocks for every canonical plugin.

Manifest section

[plugin.pairing.adapter]
channel_id           = "whatsapp"
broker_topic_prefix  = "plugin.whatsapp"
# Optional knobs:
# format_challenge_text_kind = "broker"   # default: trait's built-in formatter
# normalize_cache_ttl_seconds = 3600      # default: unbounded

Required fields:

• channel_id — stable string id matching what the gate stores in pairing_pending.channel and pairing_allow_from.channel. The registry uses this as the key under register(). Plugins that also ship [plugin.pairing] UI (kind = "qr" | "form" | "info" | "custom") should use the same channel_id so the registry + UI agree.
• broker_topic_prefix — broker subject prefix the daemon dispatches JSON-RPC requests under (see contract below).

Optional fields:

• format_challenge_text_kind — "default" (the value the trait already supplies) or "broker" (asks the plugin per challenge). Default is default; channels needing custom challenge formatting (e.g. Telegram MarkdownV2 escape) flip to broker.
• normalize_cache_ttl_seconds — TTL for normalize_sender cache entries. None (default) = unbounded (cache lives the daemon's lifetime). Set when the plugin can return different canonical forms for the same raw over time.

Broker JSON-RPC dispatch contract

Daemon publishes JSON-RPC request messages on <broker_topic_prefix>.pairing.<method>. Plugin subscribes, handles, replies. All payloads are JSON.

<prefix>.pairing.normalize_sender

Request. { "raw": "<raw-sender>" }.

Reply. { "normalized": "<canonical>" } to accept, or { "normalized": null } to reject (the gate treats reject as Decision::Drop).

Examples:

The daemon caches (raw → normalized) in memory. Cache hits do NOT round-trip the broker. With normalize_cache_ttl_seconds unset the cache grows bounded by distinct-sender count; typically < 10⁴ entries.

<prefix>.pairing.send_reply

Request. { "account": "<inst>", "to": "<sender>", "text": "<challenge>" }.

Reply. { "ok": true } or { "ok": false, "error": "<message>" }.

Delivers the pairing challenge text. account is the multi-instance discriminator (operators set it via config/plugins/<channel>.yaml's instance field).

<prefix>.pairing.send_qr_image

Request. { "account": "<inst>", "to": "<sender>", "png_base64": "<base64>" }.

Reply. { "ok": true } or { "ok": false, "error": "<message>" }.

Plugin decodes the base64 PNG and delivers it as a media message. Plugins whose channel cannot send media should reply { "ok": false, "error": "channel does not support media" } — the trait's default impl bails for plugins that haven't overridden, but explicit failure with a clear error helps operators diagnose.

<prefix>.pairing.format_challenge_text (only when format_challenge_text_kind = "broker")

Request. { "code": "<setup-code>" }.

Reply. { "text": "<formatted-challenge>" }.

When the manifest sets format_challenge_text_kind = "broker" the daemon issues this RPC instead of using the trait's built-in formatter. Used for channels that need plugin-specific escaping (Telegram MarkdownV2, Discord embed JSON, …).

Migration path

Plugins migrate by adding the manifest section in their next release. Until then the daemon's legacy hardcoded build_known_pairing_registry() registration (gated by #[cfg(feature = "plugin-<id>")]) continues to serve. When a plugin ships the manifest section, the registry's register() overwrites by channel_id so the generic adapter wins without operator action.

Canonical plugins

• nexo-plugin-whatsapp — pending. When shipped, the daemon's L1654 Arc::new(WhatsappPairingAdapter::new(broker)) becomes dead code (still cfg-gated, removable in a follow-up).
• nexo-plugin-telegram — pending. Same shape, L1657.
• Future plugins (signal, matrix, sms, discord) — drop manifest in plugins.discovery.search_paths; no daemon edit needed.

Implementing the broker side (plugin authors)

Subprocess plugins built on the nexo-microapp-sdk register the three handlers (normalize_sender, send_reply, send_qr_image) during PluginAdapter::init. Reference implementations land in the next nexo-plugin-whatsapp + nexo-plugin-telegram release; until then plugins can mirror the canonical <channel>PairingAdapter::normalize_sender Rust logic into the broker handler verbatim.

Daemon-side wiring

SubprocessNexoPlugin::build_pairing_adapter() (crates/core/src/agent/nexo_plugin_registry/subprocess.rs) checks self.cached_manifest.plugin.pairing.adapter. When present, returns Some(Arc::new(GenericBrokerPairingAdapter::from_manifest(broker, section))).

The daemon's boot loop (src/main.rs:6416) iterates every loaded plugin handle and calls build_pairing_adapter(broker.clone()). Same loop runs in the hot-spawn path (src/main.rs:7224+). Dispatch-ctx mode (boot_dispatch_ctx_if_enabled / autonomous-worker) uses only the legacy hardcoded registry today; threading plugin_handles_cell into that function is a follow-up if dispatch-ctx flows grow pairing-aware hooks.

Validation

• cargo build --release-fast --bin nexo (default) — 3m09s.
• cargo build --release-fast --bin nexo --no-default-features — 2m50s (nexo-plugin-whatsapp + nexo-plugin-telegram absent from the compile graph; manifest-section parsing still compiles because it's in nexo-plugin-manifest).
• cargo nextest run --workspace — 6280/6280 (4 new tests for GenericBrokerPairingAdapter).
• cargo nextest run -p nexo-pairing — 67/67.
• cargo nextest run --no-default-features -p nexo-rs — 105/105.

Trade-offs

[plugin.pairing.trigger] — manifest-driven pairing trigger

Phase 81.20.x Stage 7 Phase 2. Status: introduced 2026-05-16.

Plugins that own a QR-pairing pump (e.g. WhatsApp wa-agent, future Signal QR-link) declare which admin RPC methods the daemon should forward pairing/start and pairing/cancel to. The daemon constructs a BrokerPairingTrigger (in nexo-pairing) from the manifest and inserts it into the dispatcher's PairingChannelTriggers map under the same channel_id as the sibling [plugin.pairing.adapter] section.

This replaces the previous design where the daemon had to import nexo_plugin_whatsapp::pairing_trigger::WhatsappPairingTrigger and call from_configs(...) — daemon no longer needs to link the plugin crate to drive its pump.

Manifest section

[plugin.pairing]
kind  = "qr"
label = "WhatsApp"

[plugin.pairing.trigger]
start_method  = "nexo/admin/whatsapp/pairing/start"
cancel_method = "nexo/admin/whatsapp/pairing/cancel"
# Optional knob:
# timeout_seconds = 120   # default: PAIRING_DEFAULT_TIMEOUT (180s)

Required fields:

• start_method — full admin RPC method name the daemon forwards the pump-start request to. MUST live under the plugin's own [plugin.admin] method_prefix (e.g. "nexo/admin/<plugin_id>/pairing/start"). Forwarded via PluginAdminRouter so the plugin's existing admin subscriber pipeline serves it.
• cancel_method — full admin RPC method name for pump cancellation. Same routing rules as start_method.

Optional fields:

• timeout_seconds — per-call broker forward timeout. Defaults to PAIRING_DEFAULT_TIMEOUT (180s), the upper bound for the whole pairing handshake.

Compatibility constraints

• [plugin.pairing.trigger] is only valid with kind = "qr". Form and Info kinds are operator-driven and need no remote pump. Custom kinds use their own nexo/notify/<rpc_namespace>/status_changed channel. Manifest validation rejects mismatched combinations at boot.
• start_method and cancel_method MUST be non-empty.

Broker JSON-RPC dispatch contract

The daemon's BrokerPairingTrigger.start(ctx):

1. Forwards start_method via PluginAdminRouter, passing { challenge_id, agent_id, instance } as params.
2. Plugin's admin handler spawns its pump (wa-agent QR pump for whatsapp). The handler returns immediately — the pump runs in the subprocess.
3. The plugin publishes QR and state updates on plugin.inbound.<channel_id>.<instance>.pairing.qr and .../pairing.state (new contract). Daemon's single generic subscriber updates ctx.store.update_qr + notify_status.
4. On pairing/cancel, daemon forwards cancel_method via the same router. Plugin tears down the pump cleanly.

Inbound topics (plugin → daemon)

plugin.inbound.<channel_id>.<instance>.pairing.qr
plugin.inbound.<channel_id>.<instance>.pairing.state

QR payload: { "challenge_id": "<uuid>", "png_base64": "<base64>", "rotates_at": "<rfc3339>" }.

State payload: { "challenge_id": "<uuid>", "state": "Linked" | "Error" | "Pending", "error": "<msg-if-Error>" }.

Migration path

Plugins migrate by adding the manifest section in their next release. Until a plugin ships the section, the daemon falls back to its legacy hardcoded WhatsappPairingTrigger import (gated by #[cfg(feature = "plugin-whatsapp")]). Once the plugin manifests the section, the boot loop's generic registration overwrites by channel_id, so the broker trigger wins without operator action.

Canonical plugins

• nexo-plugin-whatsapp — pending v0.4.4. When shipped, the daemon's WhatsappPairingTrigger::from_configs registration in src/main.rs (cfg-gated) becomes dead code; removable once v0.4.4 lands on crates.io.
• Future pairing channels (signal, matrix, sms with QR-link) — drop manifest into plugins.discovery.search_paths; no daemon edit needed.

Implementing the broker side (plugin authors)

Subprocess plugins built on the nexo-microapp-sdk register the start_method and cancel_method handlers via their existing [plugin.admin] subscriber (the broker topic prefix is <plugin.admin.broker_topic_prefix>.<suffix>, where <suffix> is the trailing portion of the admin method after the plugin's prefix).

Reference impl lands in nexo-plugin-whatsapp v0.4.4. The handler should:

1. Read { challenge_id, agent_id, instance } from params.
2. Spawn an async task that drives the pump (wa-agent's pair_with_callback).
3. As QR frames rotate, publish to plugin.inbound.whatsapp.<instance>.pairing.qr.
4. On connect success, publish state Linked. On terminal error, publish state Error with the error message.
5. Return { "ok": true } from the admin RPC reply (the start was accepted; success/failure flows through the inbound topics).

Cancellation: the daemon forwards cancel_method with { challenge_id }. Handler aborts the spawned pump task and returns { "ok": true }.

Validation

• cargo nextest run -p nexo-plugin-manifest — manifest schema
  • validator tests.
• cargo nextest run -p nexo-pairing — BrokerPairingTrigger unit tests.
• cargo nextest run -p nexo-rs — daemon boot-loop integration.

Trade-offs

[plugin.public_tunnel] — manifest-driven Cloudflare quick tunnel

Phase 81.20.x Stage 7 Phase 2. Status: introduced 2026-05-16.

Plugins that expose HTTP routes the operator might want to reach from outside the LAN (e.g. WhatsApp pairing while the daemon runs on a desktop and the QR is scanned on a phone) declare this section. The daemon spawns a Cloudflare quick tunnel pointed at its HTTP port; plugin routes exposed via [plugin.http] become reachable at https://*.trycloudflare.com/<plugin-mount-prefix>/....

Two-key opt-in

The daemon opens a public tunnel only when both are true:

1. Plugin manifest: [plugin.public_tunnel] enabled = true.
2. Operator capability env: NEXO_PLUGIN_PUBLIC_TUNNEL_ALLOW=1.

A manifest declaration alone is not enough — the daemon still honours the operator's hardening choice. Declaring the section with enabled = false (or omitting it) keeps the plugin forever-private even if the operator flips the env on for another plugin.

Manifest section

[plugin.public_tunnel]
enabled = true
# Optional — when set, the daemon subscribes to this exact broker
# subject and closes the tunnel on the first published message.
# Wildcards (`*`, `>`) are rejected at manifest validation.
close_on_event = "plugin.lifecycle.whatsapp.tunnel_done"

Fields

• enabled (bool, default false) — plugin-side opt-in. When false, the section behaves identically to "no section declared".
• close_on_event (string, optional) — literal broker subject. When set, the daemon subscribes once and tears the tunnel down on the first inbound message. Typical use: a pairing-channel plugin publishes <plugin>.tunnel_done after the operator completes pairing so the public URL stops responding immediately. When None, the tunnel stays up for the daemon's lifetime.

Validation

Rejected at boot:

• close_on_event is the empty string or whitespace (PublicTunnelCloseEventEmpty).
• close_on_event contains a NATS wildcard (* or >). The daemon refuses wildcards so a stray plugin event can't race-close a healthy tunnel (PublicTunnelCloseEventWildcard).

URL sidecar file

When a tunnel comes up, the daemon writes the public URL to $NEXO_HOME/state/tunnel.url (or ~/.nexo/state/tunnel.url). The nexo pair start CLI reads this file directly so the operator doesn't have to copy/paste from logs.

Migration from wa_tunnel_cfg

Earlier daemon revisions extracted public_tunnel from each WhatsApp YAML entry under config/plugins/whatsapp.yaml and spawned a Cloudflare tunnel inline. That orchestration was removed (Phase 81.20.x Stage 7 Phase 2) — plugins now declare the intent in their manifest, the daemon iterates uniformly, and the operator's env flag stays authoritative.

Daemon-side wiring

main.rs iterates wire.plugin_handles after wire_plugin_registry returns. For every plugin with [plugin.public_tunnel] enabled = true, the daemon:

1. Spawns nexo_tunnel_quick::TunnelManager::new(8080).start().
2. Logs the URL + writes it to the sidecar file.
3. If close_on_event is set, spawns a broker subscriber that awaits one message then calls tunnel.shutdown().await.

The capability gate is checked once at the top of the iterator block. When OFF, the iterator logs a single informational line ("declared by at least one plugin but env is not set") and skips every tunnel spawn — useful for hardened deployments that want a visible audit trail.

Threat model

https://*.trycloudflare.com/<plugin-prefix>/... is reachable from anywhere the URL is shared. Cloudflare provides DDoS protection + edge TLS but does NOT enforce authentication. The plugin's HTTP handler is responsible for any access control on the exposed paths.

Pairing pages are time-limited (the QR rotates ~every 20s, the challenge expires in 5 minutes). When close_on_event is set, the tunnel is teardown-immediate post-pairing — the URL becomes 404 the moment the plugin signals completion.

Validation commands

• cargo nextest run -p nexo-plugin-manifest — manifest schema
  • validator tests.
• Manual smoke: NEXO_PLUGIN_PUBLIC_TUNNEL_ALLOW=1 cargo run --bin nexo with a manifest declaring the section. Daemon log should show "public tunnel up" with the assigned URL.

[plugin.http] — daemon-proxied HTTP routes

Phase 81.33.b.real Stage 2 (Layer 8 of the plugin auto-discovery design). Status: shipped 2026-05-15.

Plugins that need to expose HTTP endpoints to operators or external callers declare a mount prefix in their nexo-plugin.toml. The daemon's HTTP server (port :8080) matches every request against the registered prefixes and forwards matches to the plugin's subprocess via broker JSON-RPC. The plugin handles internal routing under the prefix.

Distinct from [plugin.http_server], which advertises a plugin-bound port the daemon does NOT proxy.

Manifest section

[plugin.http]
mount_prefix     = "/whatsapp"
# Optional:
# timeout_seconds = 60     # default: 30

Fields:

• mount_prefix (required) — path prefix the daemon mounts. Must start with /. Cannot contain ? or #. The daemon matches path.starts_with(mount_prefix).
• timeout_seconds (optional) — per-request broker RPC timeout. Default 30s. Plugins serving slow flows (image generation, OAuth dances) extend.

Broker JSON-RPC contract

Daemon → plugin on plugin.<id>.http.request:

{
  "method": "GET",
  "path": "/whatsapp/pair",
  "query": "instance=default",
  "headers": [["Host", "127.0.0.1:8080"], ["User-Agent", "..."]],
  "body_base64": ""
}

Plugin replies:

{
  "status": 200,
  "headers": [["Content-Type", "text/html; charset=utf-8"]],
  "body_base64": "<base64-encoded body bytes>"
}

Body bytes are base64-encoded so binary payloads (PNGs, PDFs, small file uploads) round-trip cleanly through JSON. The daemon decodes server-side and writes raw bytes back to the TCP stream.

Route matching

The router stores all prefixes in longest-first order. A request matches the most-specific prefix:

A miss falls through to the daemon's legacy hardcoded paths (/health, /metrics, etc.).

Reserved prefixes. The router refuses to register any plugin mount under these daemon-internal paths:

• /health — liveness checks
• /metrics — Prometheus scrape
• /pair — daemon's WS pairing companion
• /admin — admin RPC surface (port 9091, not 8080, but reserved here too for safety against future shared-port designs)
• /.well-known — protocol probes (RFC 8615)

A plugin manifest declaring any of these (or a sub-path like /health/foo) is rejected at registration with a warn-level log; the plugin's broker handler stays unhooked for that prefix and the daemon's internal handler serves uninterrupted.

Plugins choosing non-reserved prefixes (/whatsapp, /oauth, /api/v1/..., /healthy, etc.) register normally.

Error rendering

The daemon writes the plugin's headers + body_base64 verbatim for non-error replies — the plugin owns the response shape.

Limitations (Stage 2)

• No streaming responses. SSE / chunked transfer / progressive rendering NOT supported. Plugin must buffer the full response before replying. Use [plugin.http_server] (own port) for streaming endpoints.
• No WebSocket upgrades. The daemon's /pair WS handshake is daemon-internal (Phase 87 pairing companion). Plugins wanting WS endpoints bind their own port.
• Body size cap. Daemon reads up to 16KB upfront. Larger bodies require streaming, which Stage 2 does not support.
• No request-id header injection. Plugins should generate their own trace ids if needed; the daemon does not auto-stamp X-Request-Id.

Implementing the plugin side

Subprocess plugins built on the Rust nexo-microapp-sdk register a broker handler on plugin.<plugin_id>.http.request:

#![allow(unused)]
fn main() {
// Sketch (final SDK helpers ship alongside the next plugin release):
ctx.broker
    .subscribe("plugin.<id>.http.request")
    .await?
    .for_each(|msg| async {
        let req: HttpRequest = serde_json::from_value(msg.payload)?;
        let res = my_router.dispatch(&req).await;
        broker
            .publish(&msg.reply_to.unwrap(), Event::new(/* ... */, res))
            .await
    });
}

Reference impl lands with the next nexo-plugin-whatsapp release; until then plugins copy the dispatch logic from the daemon's current nexo_plugin_whatsapp::pairing::dispatch_route.

Migration status

Canonical plugin crates have NOT yet shipped a manifest revision adding [plugin.http]. Daemon's legacy hardcoded if let Some(rest) = path.strip_prefix("/whatsapp/") block (gated by #[cfg(feature = "plugin-whatsapp")] via 93.12.c.2) continues to serve. When a plugin ships the section, the router matches before the legacy block and the plugin's broker handler takes over without operator action; the legacy block becomes dead code (still cfg-gated, removable in a follow-up after the canonical plugins migrate).

Validation

• cargo build --release-fast --bin nexo (default) — 3m11s.
• cargo build --release-fast --bin nexo --no-default-features — 2m53s.
• cargo nextest run --workspace — 6294/6294 (8 new tests in plugin_http::tests covering router matching, response decoding, broker error path).
• cargo nextest run --no-default-features -p nexo-rs — 105/105.
• cargo nextest run -p nexo-pairing — 75/75.

Trade-offs

[plugin.admin] — daemon-forwarded admin RPC commands

Phase 81.33.b.real Stage 4 (Layer 9 of the plugin auto-discovery design). Status: shipped 2026-05-15.

Plugins that expose admin RPC commands (bot inspectors, account listers, channel-specific control planes) declare a method prefix in their nexo-plugin.toml. The daemon's admin dispatcher matches every incoming method against the registered prefixes and forwards matches to the plugin's subprocess via broker JSON-RPC. The plugin handles internal dispatch.

Replaces the previous pattern where each plugin needed a hardcoded .with_<plugin>_handle(Arc<dyn XxxHandle>) builder method on the dispatcher (e.g. the legacy with_wa_bot_handle integration for nexo/admin/whatsapp/bot/*).

Manifest section

[plugin.admin]
method_prefix       = "nexo/admin/whatsapp/"
broker_topic_prefix = "plugin.whatsapp.admin"
# Optional:
# timeout_seconds = 30

Fields:

• method_prefix (required) — admin RPC method prefix the plugin owns. Must start with nexo/admin/ and end with /. Example: nexo/admin/whatsapp/.
• broker_topic_prefix (required) — broker subject prefix the daemon forwards under. Example: plugin.whatsapp.admin.
• timeout_seconds (optional) — per-method broker RPC timeout. Default 30s.

Broker JSON-RPC contract

Daemon → plugin on <broker_topic_prefix>.<verb>:

{
  "method": "nexo/admin/whatsapp/bot/list",
  "params": { "agent_id": "kate" }
}

Plugin replies:

{ "ok": true,  "result": { "bots": [...] } }
{ "ok": false, "error": "session not connected" }

The daemon emits the broker subject by stripping method_prefix from the incoming method, replacing / with ., and appending to broker_topic_prefix. So nexo/admin/whatsapp/bot/list → bot/list → bot.list → plugin.whatsapp.admin.bot.list.

Reserved prefixes

The router refuses to register any plugin whose method_prefix collides with daemon-internal admin handlers. The reserved list:

• nexo/admin/agents/
• nexo/admin/credentials/
• nexo/admin/pairing/
• nexo/admin/llm/
• nexo/admin/channels/
• nexo/admin/tenants/
• nexo/admin/memory/
• nexo/admin/sessions/
• nexo/admin/snapshots/
• nexo/admin/policy/

Comparison is bidirectional — nexo/admin/agents/sneaky/ (subpath of reserved) AND nexo/admin/ (super-prefix that would shadow reserved) are both rejected. Plugins choosing non-reserved prefixes (nexo/admin/whatsapp/, nexo/admin/signal/, nexo/admin/oauth/) register normally.

Rejected registrations log at warn level; the daemon's internal handlers continue to serve uninterrupted.

Capability enforcement

Plugin admin methods that match the router are gated by the existing channels_crud capability (reused so operators already granted channel admin can call plugin admin without a fresh capability). Per-plugin capability grants are a follow-up when finer control is needed.

Error rendering

The daemon does NOT translate plugin error strings; the typed error surfaces verbatim through the JSON-RPC response.

Migration status

The legacy with_wa_bot_handle builder on AdminRpcDispatcher is preserved. Until nexo-plugin-whatsapp ships a manifest revision with [plugin.admin], the daemon's hardcoded nexo/admin/whatsapp/bot/list + bot/send match arms continue to serve. When whatsapp ships the section, the router matches BEFORE the typed match arms (generic forward wins) and the legacy block becomes dead code (cfg-gated, removable in follow-up).

Implementing the plugin side

Subprocess plugins built on nexo-microapp-sdk subscribe to <broker_topic_prefix>.> and dispatch:

#![allow(unused)]
fn main() {
// Sketch (final SDK helpers ship with the next plugin release):
ctx.broker
    .subscribe("plugin.whatsapp.admin.>")
    .await?
    .for_each(|msg| async {
        let topic = msg.topic.strip_prefix("plugin.whatsapp.admin.").unwrap();
        match topic {
            "bot.list" => handle_bot_list(msg.payload).await,
            "bot.send" => handle_bot_send(msg.payload).await,
            _ => reply_err(msg, "method not found"),
        }
    });
}

Validation

• cargo build --release-fast --bin nexo (default) — 3m10s clean.
• cargo build --release-fast --bin nexo --no-default-features — 2m53s clean.
• cargo nextest run --workspace — 6312/6312 (9 new tests in plugin_admin::tests).
• cargo nextest run -p nexo-pairing — covers router matching, reserved-prefix rejection, subpath/super-prefix safety, method-to-broker-suffix translation, broker error path.
• cargo nextest run --no-default-features -p nexo-rs — 105/105.
• cargo nextest run --no-default-features -p nexo-setup — 317/317.

Trade-offs

[plugin.metrics] — Prometheus scrape contribution

Phase 81.33.b.real Stage 5 (Layer 11 of the plugin auto-discovery design). Status: shipped 2026-05-15.

Plugins exposing Prometheus metrics declare a broker topic the daemon scrapes on every /metrics HTTP request. The plugin's subprocess handles the scrape, returns Prometheus text, and the daemon concatenates it into the aggregate response.

Replaces the previous pattern where each plugin's metrics call was hardcoded inside src/main.rs::run_metrics_server (e.g. the legacy nexo_plugin_email::metrics::render_prometheus(...) direct call).

Manifest section

[plugin.metrics]
prometheus          = true
broker_topic_prefix = "plugin.email"
# Optional:
# timeout_seconds = 5

Fields:

• prometheus (default false) — opt the plugin into the /metrics scrape loop.
• broker_topic_prefix (required when prometheus = true) — daemon publishes to <broker_topic_prefix>.metrics.scrape.
• timeout_seconds (optional, default 5s) — per-scrape broker RPC timeout. Scrapes happen per /metrics HTTP request so the daemon-side latency budget is tight; plugins exceeding the timeout warn-log + contribute nothing for that scrape.

Broker JSON-RPC contract

Daemon → plugin on <broker_topic_prefix>.metrics.scrape:

{}

Plugin replies:

{ "text": "# HELP <metric> ...\n# TYPE ...\n<metric> <value>\n..." }

Empty / missing text is treated as a successful scrape with no metrics. The daemon does NOT validate Prometheus text shape — plugin owns the surface entirely. Adding a trailing newline is optional; the daemon appends \n if missing.

Daemon-side aggregation

run_metrics_server (src/main.rs:15097+) concatenates from:

1. nexo_core::telemetry::render_prometheus(nats_open) — daemon-internal counters.
2. nexo_llm::telemetry::render_prometheus() — LLM provider stats.
3. nexo_mcp::telemetry::render_prometheus() + server-side dispatch metrics.
4. nexo_poller::telemetry::render_prometheus() — Gmail / generic poller counters.
5. nexo_plugin_email::metrics::render_prometheus(...) — legacy direct call, kept until email plugin migrates to broker scrape.
6. nexo_tunnel_quick::metrics::render_prometheus_for(...) — tunnel supervisor counters.
7. Phase 5: nexo_pairing::plugin_metrics::scrape_all(...) — every plugin that declared [plugin.metrics] prometheus = true.

Order matters for Prometheus scrape — duplicate metric names across sources are not deduplicated; the LAST occurrence wins when the scraper rebuilds its state. Plugins should namespace their metrics with a prefix (my_plugin_<metric>) to avoid collisions.

Failure isolation

One slow / unresponsive plugin does NOT stall the /metrics response. Each scrape has its own timeout (default 5s). On failure (timeout, broker error, malformed reply) the daemon:

1. Logs a warn-level event with plugin id + error string.
2. Contributes empty string for that plugin in the aggregate.
3. Continues with the remaining plugins.

This trades immediate observability of plugin metric outages for operator UX — a watchdog scraping every 15s sees gaps when a plugin is unhealthy, but the daemon's own metrics (CPU, memory, LLM, MCP, tunnels) keep flowing.

Implementing the plugin side

Subprocess plugins subscribe to <broker_topic_prefix>.metrics.scrape and reply:

#![allow(unused)]
fn main() {
// Sketch (final SDK helpers ship with the next plugin release):
ctx.broker
    .subscribe("plugin.<id>.metrics.scrape")
    .await?
    .for_each(|msg| async {
        let text = my_metrics_module::render_prometheus(...);
        broker.publish(
            &msg.reply_to.unwrap(),
            json!({ "text": text }),
        ).await
    });
}

Reference impl lands with the next nexo-plugin-email release; until then the daemon's legacy hardcoded call keeps email metrics flowing.

Migration status

• nexo-plugin-email — NOT migrated. Legacy in-process call at src/main.rs:15295 continues to serve. When email ships the manifest section, BOTH paths fire (legacy direct call AND broker scrape) until the legacy call is retired in a follow-up.
• Other canonical plugins — none currently expose Prometheus metrics. New plugins opting into metrics declare the manifest section directly with no legacy fallback to maintain.

Validation

• cargo build --release-fast --bin nexo (default) — 3m clean.
• cargo build --release-fast --bin nexo --no-default-features — 3m01s clean.
• cargo nextest run --workspace — 6321/6321 (5 new tests in plugin_metrics::tests covering descriptor construction, empty-descriptors short-circuit, failure isolation across multiple plugins, broker error path).
• mdbook build docs clean.

Trade-offs

[plugin.dashboard] — setup wizard surface

Phase 81.33.b.real Stage 6 (Layer 10 polish of the plugin auto-discovery design). Status: shipped 2026-05-15.

Plugins that want to appear in the setup wizard's channel dashboard declare how the daemon detects their instances + auth state via this manifest section. A generic ManifestDashboardSource in nexo-setup consumes the section and runs the right discovery / auth check, eliminating the need for per-channel hardcoded crates/setup/src/services/channels_dashboard.rs impls (the 3 canonical ones — telegram, whatsapp, email — stay as fallback until canonical plugin crates ship manifest revisions).

Manifest section

[plugin.dashboard]
# Instance enumeration strategy:
[plugin.dashboard.layout]
kind = "single"                          # | "workspace_walk"

# Auth-state probe strategy:
[plugin.dashboard.auth_check]
kind = "file_presence"                   # | "session_dir_files"
path = "telegram_bot_token.txt"          # for file_presence (relative to secrets_dir)

Telegram shape (single instance, file-presence auth)

[plugin.dashboard.layout]
kind = "single"

[plugin.dashboard.auth_check]
kind = "file_presence"
path = "telegram_bot_token.txt"

Email shape

[plugin.dashboard.layout]
kind = "single"

[plugin.dashboard.auth_check]
kind = "file_presence"
path = "email_password.txt"

Whatsapp shape (multi-instance via workspace walk, session-dir auth)

[plugin.dashboard.layout]
kind = "workspace_walk"
subdir = "whatsapp"

[plugin.dashboard.auth_check]
kind = "session_dir_files"
candidates = ["session.db", "state.db", "device.json", "registration.json"]

Field reference

layout

• kind = "single" — exactly one instance labelled "default". Used by channels with one account per agent (telegram, email).
• kind = "workspace_walk", subdir = "<name>" — walk <workspace>/<agent>/<subdir>/<instance>/ for every directory entry. Used by channels with multi-instance per-agent layouts (whatsapp). subdir must be a single segment (no /).

auth_check

• kind = "file_presence", path = "<rel>" — authenticated if <secrets_dir>/<rel> exists + is non-empty. Path must be relative (no leading /). <secrets_dir> is the operator's secrets root (typically ~/.nexo/secrets or $NEXO_HOME/secrets).
• kind = "session_dir_files", candidates = [...] — authenticated if the per-instance directory contains ANY of the listed filenames. Only meaningful with layout.kind = "workspace_walk"; the per-instance dir is <workspace>/<agent>/<subdir>/<instance>/. If the directory exists with OTHER files (but none of the candidates), reports Stale; empty dir reports NotAuthenticated.

Daemon-side dispatch

crates/setup/src/services/channels_dashboard.rs ships:

• pub trait ChannelDashboardSource — channel_id() + discover().
• pub struct ManifestDashboardSource — generic impl that consumes a parsed PluginDashboardSection + plugin id.
• pub fn dashboard_sources_from_manifests(manifests) -> Vec<Box<dyn ChannelDashboardSource>> — helper that filters manifests + builds a source per declaring plugin.
• pub fn default_dashboard_sources() -> Vec<Box<dyn ChannelDashboardSource>> — the 3 hardcoded canonical impls (telegram, whatsapp, email). Kept for backwards compat until canonical plugin crates ship manifest revisions.

Operators combining both:

#![allow(unused)]
fn main() {
let mut sources = default_dashboard_sources();
sources.extend(dashboard_sources_from_manifests(&discovered_manifests));
let entries = detect_channels_with_sources(&sources, &config_dir, &secrets_dir)?;
}

Migration

Canonical plugin crates currently ship NO [plugin.dashboard] section. The 3 hardcoded sources in nexo-setup continue to serve the wizard. When a plugin ships the section AND the wizard caller discovers manifests + extends the source list, the manifest-driven source contributes alongside the hardcoded one. Once all 3 canonical plugins migrate, the hardcoded sources can be retired in a Stage 7 cleanup follow-up.

New canonical channels added in the future (signal, sms, …) ship the manifest section directly + skip the hardcoded path entirely.

Validation

• cargo build --release-fast --bin nexo (default) — 3m13s.
• cargo build --release-fast --bin nexo --no-default-features — 2m54s.
• cargo nextest run --workspace — 6334/6334 (13 new tests: 8 in nexo-plugin-manifest::dashboard::tests, 5 in nexo-setup::services::channels_dashboard::manifest_dashboard_tests).
• mdbook build docs clean.

Trade-offs

nexo Plugin Contract

This contract describes how an out-of-tree plugin binary communicates with the nexo daemon. A conforming plugin can be written in any language — Rust, Python, TypeScript, Go, etc. — as long as it implements the protocol defined here.

1. Transport

• Plugin runs as a child process of the daemon.
• Daemon writes to the child's stdin. Child writes to its stdout.
• stderr is closed by the daemon (currently /dev/null — Phase 81.23 will collect it into structured tracing).
• Each direction is a stream of newline-delimited UTF-8 lines.
• Each line is exactly one JSON-RPC 2.0 message — request, response, or notification.
• Lines must not exceed the platform pipe buffer (typically 4 KiB on Linux); fragmenting one JSON object across multiple lines is not supported.

2. Manifest

The plugin ships a nexo-plugin.toml file — schema defined by the nexo-plugin-manifest crate. The fields relevant to this contract are:

[plugin]
id = "slack"                       # ASCII slug, ^[a-z][a-z0-9_]{0,31}$
version = "0.2.0"                  # semver
name = "Slack Channel"
description = "..."
min_nexo_version = ">=0.1.0"

[plugin.requires]
nexo_capabilities = ["broker"]

# Phase 81.14 — subprocess entrypoint.
[plugin.entrypoint]
command = "/usr/local/bin/plugin-slack"  # absolute path or PATH binary
args = ["--mode", "stdio"]               # optional
env = { "RUST_LOG" = "info" }            # optional, MUST NOT begin with "NEXO_"

# Phase 81.8 — channel kinds the plugin exposes. Drives the
# broker subscribe / publish allowlist (see §6).
[[plugin.channels.register]]
kind = "slack"
adapter = "SlackChannelAdapter"

The host parses this manifest at boot and uses plugin.id to verify the child's identity in the initialize handshake (§4.1). It uses plugin.entrypoint.command to spawn the child process. Any env key beginning with NEXO_ is rejected at boot — those names are reserved for the daemon's own runtime configuration.

2.1 Extends section (Phase 81.28)

A subprocess plugin that contributes to a daemon-side registry beyond [plugin.channels.register] declares its capabilities in an additive [plugin.extends] section:

[plugin.extends]
channels         = ["slack", "discord"]    # paired with Phase 81.24 wrapper
llm_providers    = ["cohere", "mistral"]   # paired with Phase 81.25
memory_backends  = ["pinecone", "qdrant"]  # paired with Phase 81.26
hooks            = ["pii_redact"]          # paired with Phase 81.27

Each list names the IDs the plugin contributes to the matching registry. Validation rules:

• Each id MUST match ^[a-z][a-z0-9_]{0,31}$.
• No duplicates within a single list.
• No cross-list duplicates — an id MUST occupy at most one of the four lists within a single plugin.
• All four fields default to empty; legacy manifests parse unchanged.

The four canonical sections are fixed in code (EXTENDS_SECTIONS); adding a new capability surface requires a manifest-crate change. This is intentional — the closed schema keeps serde(deny_unknown_fields) defense intact and gates new extension points behind a coordinated rollout.

[plugin.extends] is the declarative half of the capability story. Daemon dispatch wiring — actually populating LlmClientRegistry / memory backend store / HookInterceptor registry — ships with Phase 81.24 (channels), 81.25 (LLM providers), 81.26 (memory backends), and 81.27 (hooks). Capability-negotiation handshake (verifying the subprocess's initialize reply matches the declared extensions) is a follow-up (81.28.b).

[plugin.extends].channels exists in parallel with [plugin.channels.register] (§6 — topic allowlist). Use extends for subprocess plugins routed through the future remote ChannelAdapter wrapper; use register for in-tree adapters that link directly into the daemon binary. Both surfaces stay independent.

2.2 Sandbox section (Phase 81.22)

Subprocess plugins on Linux can opt into bubblewrap-based isolation via an additive [plugin.sandbox] section. Default = disabled — every existing manifest parses unchanged; the daemon spawns the plugin as a normal child process.

[plugin.sandbox]
enabled = true                        # default false (opt-in)
network = "deny"                       # "deny" | "host"
fs_read_paths = ["/etc/ssl/certs"]    # absolute, ro-bind into sandbox
fs_write_paths = ["${state_dir}"]     # absolute, rw-bind. ${state_dir}
                                       # token expands to the plugin's
                                       # per-instance state root.
drop_user = true                       # default true; bwrap maps the
                                       # child to nobody:nogroup (uid
                                       # 65534) via --unshare-user.

When enabled, the daemon wraps the spawn Command with bwrap flags:

• Process hardening: --die-with-parent --unshare-pid --unshare-uts --unshare-ipc --new-session.
• Filesystem skeleton: --proc /proc --dev /dev --tmpfs /tmp plus read-only binds for /usr /bin /sbin /lib /lib64 /etc/ssl. The plugin command's parent dir is also auto-bound read-only so the binary is reachable inside the sandbox.
• Network: --unshare-net for network = "deny". For network = "host" the operator must set the NEXO_PLUGIN_SANDBOX_HOST_NET_ALLOW=1 capability env var; the manifest validator otherwise rejects the field.
• User: --unshare-user --uid 65534 --gid 65534 when drop_user = true.
• Allowlist: each fs_read_paths entry becomes --ro-bind <path> <path>; each fs_write_paths entry becomes --bind <path> <path> after ${state_dir} expansion.

Operators control sandbox enforcement via two env knobs:

Hard denylist (compile-time const) — operator-supplied allowlists that equal or include any of these paths are rejected at manifest load:

• /etc/shadow, /etc/sudoers, /etc/sudoers.d
• /proc/sys, /proc/kcore, /proc/kallsyms
• /sys/firmware, /sys/kernel
• /dev/mem, /dev/kmem, /dev/port
• /var/run/docker.sock, /run/docker.sock, /private/var/run/docker.sock
• /root, /boot

Validation errors surface as ManifestError::Sandbox* variants (SandboxAllowlistTouchesDenylist, SandboxRelativePath, SandboxInvalidStateDirInterpolation, SandboxHostNetworkWithoutCapability).

Platform support: Linux requires bubblewrap in PATH (apt install bubblewrap). macOS is currently a no-op + tracing::warn! log per spawn — native sandbox-exec integration is deferred to follow-up 81.22.macos. With NEXO_PLUGIN_SANDBOX_REQUIRE=1 on macOS, the daemon refuses to spawn (treats macOS as unsupported).

Out of scope for v1:

• Granular network egress allowlist (network = "allowlist", network_allowlist = ["host:port"]) — defers to 81.22.b (slirp4netns + nftables).
• Per-syscall seccomp filters — defers to 81.22.c.
• Cgroup / rlimit resource caps — Phase 81.21.c.
• Doctor CLI surface — defers to 81.22.d.

3. JSON-RPC envelope

All frames are valid JSON-RPC 2.0:

Request

{
  "jsonrpc": "2.0",
  "id": <integer or string>,
  "method": "<method-name>",
  "params": <object | null>
}

Response (success)

{
  "jsonrpc": "2.0",
  "id": <same as request>,
  "result": <object | null>
}

Response (error)

{
  "jsonrpc": "2.0",
  "id": <same as request, null if request was un-parseable>,
  "error": {
    "code": <integer>,
    "message": "<string>"
  }
}

Notification

A notification is a request without an id field. The peer must not reply.

{
  "jsonrpc": "2.0",
  "method": "<method-name>",
  "params": <object | null>
}

The contract uses notifications for unidirectional broker events — see §5.

4. Lifecycle

4.1 initialize (host → child request)

After spawning the child, the daemon writes one initialize request and awaits the response. The child must respond before NEXO_PLUGIN_INIT_TIMEOUT_MS (default 5000) elapses or the daemon kills it and surfaces PluginInitError::Other.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": { "nexo_version": "0.1.5" }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "manifest": { "plugin": { "id": "slack", "version": "0.2.0", ... } },
    "server_version": "slack-0.2.0"
  }
}

The child must echo a manifest whose plugin.id matches the id the daemon expected (the id under which the plugin was registered in the factory registry). Mismatch is a hard failure — the daemon kills the child and refuses to load the plugin. This defends against an out-of-tree binary impersonating a different plugin.

server_version is a free-form string identifying the running binary; the SDK defaults it to <id>-<version> from the manifest.

4.1.1 Tool catalog advertisement (Phase 81.29, optional)

Plugins declaring [plugin.extends].tools = [...] MUST include a tools array in the initialize-reply result. Each entry is a RemoteToolDef:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "manifest": { "plugin": { "id": "browser", ... } },
    "server_version": "browser-0.1.1",
    "tools": [
      {
        "name": "browser_navigate",
        "description": "Navigate to a URL",
        "input_schema": {
          "type": "object",
          "properties": { "url": { "type": "string" } },
          "required": ["url"]
        }
      }
    ]
  }
}

Validation rules at the host:

• The tools field is OPTIONAL when extends.tools is empty. Required (non-empty) when the manifest declares any tool.
• Every advertised name MUST appear in manifest.plugin.extends.tools. Drift in this direction (advertised but not declared) is a hard failure: the daemon kills the child and refuses to load.
• Manifest entries WITHOUT an advertised counterpart are tolerated but logged at warn — runtime calls to those tools yield -33401 ToolNotFound.
• name must satisfy the per-plugin namespace rule (<plugin_id>_* or ext_<plugin_id>_*).
• input_schema is an arbitrary JSONSchema object; the daemon caches it for arg validation before each tool.invoke.

4.2 shutdown (host → child request)

The daemon sends shutdown when it wants the plugin to exit gracefully. The child should flush state, then reply.

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "shutdown",
  "params": { "reason": "host requested" }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": { "ok": true }
}

Reply with an error object instead of result if shutdown fails — the host surfaces PluginShutdownError::Other to the operator.

After the reply, the daemon waits 1 second for the process to exit on its own. If the child is still alive, the daemon sends SIGKILL. So: reply, then exit.

5. Broker bridge

The wire-level shape of the broker bridge is two notifications:

5.1 broker.event (host → child)

Whenever the daemon's broker delivers an event on a topic matching one of the plugin's outbound subscriptions (derived from manifest.channels.register[].kind — see §6), the daemon sends:

{
  "jsonrpc": "2.0",
  "method": "broker.event",
  "params": {
    "topic": "plugin.outbound.slack.team_a",
    "event": {
      "id": "01940000-0000-0000-0000-000000000001",
      "timestamp": "2026-05-01T00:00:00Z",
      "topic": "plugin.outbound.slack.team_a",
      "source": "agent.coordinator",
      "session_id": "01940000-0000-0000-0000-000000000099",
      "payload": { "text": "hello", ... }
    }
  }
}

The event field is a serialised nexo_broker::Event. The plugin processes the event (e.g. forwards payload.text to Slack's API) and may reply with a broker.publish notification (§5.2) — but it is not required to reply.

5.2 memory.recall (child → host request) <Phase 81.20.a>

When the plugin needs to look up agent memory entries, it issues a JSON-RPC request to the daemon. Unlike broker.event / broker.publish which are notifications, this is a request-response flow: the child sends with an id and awaits the matching reply.

Child → host request:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "memory.recall",
  "params": {
    "agent_id": "ventas_v1",
    "query": "user prefers concise answers",
    "limit": 5
  }
}

Host → child reply (success):

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "entries": [
      {
        "id": "01940000-0000-0000-0000-000000000001",
        "agent_id": "ventas_v1",
        "content": "user prefers concise answers",
        "tags": ["preference"],
        "concept_tags": [],
        "created_at": "2026-04-30T18:22:31Z",
        "memory_type": null
      }
    ]
  }
}

Host → child reply (error):

• -32601 method not found (only memory.recall wired in 81.20.a; llm.complete / tool.dispatch ship in 81.20.b/.c).
• -32602 invalid params (missing agent_id / wrong type for query).
• -32603 memory not configured (operator hasn't enabled long-term memory) OR memory backend returned an error.

limit defaults to 10, capped hard at 1000. The handler calls LongTermMemory::recall(agent_id, query, limit) which already expands the query with up to 3 derived concept tags so FTS5 hits memories whose stored content diverges from the query surface.

5.3 llm.complete (child → host request) <Phase 81.20.b>

When the plugin needs an LLM completion, it issues a request and awaits the response.

Child → host request:

{
  "jsonrpc": "2.0",
  "id": 50,
  "method": "llm.complete",
  "params": {
    "provider": "minimax",
    "model": "minimax-m2.5",
    "messages": [
      {"role": "user", "content": "summarize this in one line: ..."}
    ],
    "max_tokens": 1024,
    "temperature": 0.7,
    "system_prompt": "You answer concisely."
  }
}

messages[].role is one of system, user, assistant, tool. max_tokens defaults to 4096; temperature defaults to 0.7; system_prompt is optional.

Host → child reply (success):

{
  "jsonrpc": "2.0",
  "id": 50,
  "result": {
    "content": "Concise reply text.",
    "finish_reason": "stop",
    "usage": {
      "prompt_tokens": 25,
      "completion_tokens": 8
    }
  }
}

finish_reason is one of stop, length, tool_use, other:<reason>.

Host → child reply (errors):

• -32602 invalid params (missing provider / model / messages, malformed message, empty messages array).
• -32603 LLM not configured (operator hasn't wired the registry to the subprocess pipeline) OR client build failed (provider name not registered, config invalid) OR chat() call returned an error.
• -32601 provider returned tool calls instead of text — MVP surfaces this as not_implemented. The tool-call wire shape (which lets the child re-submit tool_result follow-ups) lands in a future contract bump.

Daemon-side caps max_tokens at u32::MAX. Streaming via llm.complete.delta notifications is opt-in via params.stream = true (Phase 81.20.b.c).

Streaming flow

When the request includes "stream": true, the host calls LlmClient::stream instead of chat. Each text chunk arrives as a notification correlated to the original request id:

{
  "jsonrpc": "2.0",
  "method": "llm.complete.delta",
  "params": { "request_id": 50, "chunk": "hello" }
}
{
  "jsonrpc": "2.0",
  "method": "llm.complete.delta",
  "params": { "request_id": 50, "chunk": " world" }
}

The final reply matches the original id but carries only finish_reason + usage — content is omitted because the child reassembled it from deltas:

{
  "jsonrpc": "2.0",
  "id": 50,
  "result": {
    "finish_reason": "stop",
    "usage": { "prompt_tokens": 12, "completion_tokens": 7 }
  }
}

Tool-call deltas in streaming mode are dropped (same scope as the non-streaming MVP). If the provider returns ONLY tool calls during a stream (no text), the final reply is -32601 not_implemented.

5.4 broker.publish (child → host)

When the plugin wants to push an event onto the broker (e.g. delivering an inbound message from Slack), it writes:

{
  "jsonrpc": "2.0",
  "method": "broker.publish",
  "params": {
    "topic": "plugin.inbound.slack.team_a",
    "event": {
      "id": "01940000-0000-0000-0000-000000000002",
      "timestamp": "2026-05-01T00:01:00Z",
      "topic": "plugin.inbound.slack.team_a",
      "source": "slack",
      "session_id": null,
      "payload": { "from": "U01ABC", "text": "hi", ... }
    }
  }
}

The host validates the topic against the allowlist (§6) before forwarding to the broker. Topics outside the allowlist are dropped with a tracing::warn! log and never reach the broker.

5.x Channel methods (Phase 81.24)

Subprocess plugins that contribute new channel kinds (declared in [plugin.extends].channels, §2.1) implement three host- initiated request methods. The host's RemoteChannelAdapter wraps each ChannelAdapter trait method into a JSON-RPC request; the child replies with the corresponding result or a typed error.

Every payload carries kind so a single subprocess advertising multiple kinds (extends.channels = ["slack", "discord"]) can dispatch via one request handler.

channel.start

// host → child
{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "channel.start",
  "params": {
    "kind": "slack",
    "instance": "primary"   // null when no per-instance multiplexing
  }
}

// child → host
{ "jsonrpc": "2.0", "id": 42, "result": { "ok": true } }

Subscribe to plugin.outbound.<kind> (or per-instance plugin.outbound.<kind>.<instance> when instance is set) and begin publishing inbound events. Default host-side timeout 30 seconds.

channel.stop

// host → child
{
  "jsonrpc": "2.0",
  "id": 43,
  "method": "channel.stop",
  "params": { "kind": "slack" }
}

// child → host
{ "jsonrpc": "2.0", "id": 43, "result": { "ok": true } }

Release resources, drop subscriptions, stop publishing inbound. Idempotent. Default host-side timeout 30 seconds.

channel.send_outbound

// host → child
{
  "jsonrpc": "2.0",
  "id": 44,
  "method": "channel.send_outbound",
  "params": {
    "kind": "slack",
    "msg": { "kind": "text", "to": "U123", "body": "hi" }
  }
}

// child → host (success)
{
  "jsonrpc": "2.0",
  "id": 44,
  "result": { "message_id": "1234.5678", "sent_at_unix": 1741032000 }
}

msg.kind is one of text, media, or custom (see OutboundMessage in §3 for the full enum). Default host-side timeout 60 seconds. Operator override via NEXO_PLUGIN_CHANNEL_TIMEOUT_MS env (single value applied to all 3 methods).

Channel-specific error codes

In addition to the JSON-RPC standard codes (§7), channel.* methods MAY return:

Error example:

{
  "jsonrpc": "2.0",
  "id": 44,
  "error": {
    "code": -33004,
    "message": "rate limited",
    "data": { "retry_after_secs": 42 }
  }
}

-32601 method_not_found from a child means the plugin declared the kind in extends.channels but did not implement the requested method; the host surfaces this as ChannelAdapterError::Unsupported { feature: "<method>" }.

5.y LLM provider methods (Phase 81.25)

Subprocess plugins that contribute LLM providers (declared in [plugin.extends].llm_providers, §2.1) implement one host- initiated request method with two modes (sync + streaming). The host's RemoteLlmClient wraps each LlmClient trait call into a JSON-RPC request; the child replies with the corresponding result or a typed error.

Every payload carries provider so a single subprocess advertising multiple providers (extends.llm_providers = ["cohere", "mistral"]) can dispatch via one request handler.

llm.chat (non-streaming)

// host → child
{
  "jsonrpc": "2.0",
  "id": 50,
  "method": "llm.chat",
  "params": {
    "provider": "cohere",
    "model": "command-r",
    "stream": false,
    "request": {
      "model": "command-r",
      "messages": [{ "role": "user", "content": "hi" }],
      "max_tokens": 1024,
      "temperature": 0.7
    }
  }
}

// child → host
{
  "jsonrpc": "2.0",
  "id": 50,
  "result": {
    "content": { "type": "text", "text": "Hello world" },
    "usage": { "prompt_tokens": 12, "completion_tokens": 4 },
    "finish_reason": { "kind": "stop" }
  }
}

The full request schema mirrors nexo_llm::types::ChatRequest fields (messages / tools / max_tokens / temperature / system_prompt / stop_sequences / tool_choice / system_blocks / cache_tools). tool_choice serializes as {"kind":"auto"|"any"|"none"|"specific","name":"<n>"?}.

The full result schema:

• content — {type:"text", text:"..."} OR {type:"tool_calls", tool_calls:[{id, name, arguments}]}
• usage — {prompt_tokens, completion_tokens}
• finish_reason — {kind:"stop"|"tool_use"|"length"|"other","reason":"<r>"?}
• cache_usage — optional {cache_read_input_tokens, cache_creation_input_tokens, input_tokens, output_tokens}

Default host-side timeout 60 seconds.

llm.chat (streaming)

// host → child
{
  "jsonrpc": "2.0",
  "id": 51,
  "method": "llm.chat",
  "params": {
    "provider": "cohere",
    "model": "command-r",
    "stream": true,
    "request": { "...": "as above" }
  }
}

// child → host: zero or more deltas
{
  "jsonrpc": "2.0",
  "method": "llm.chat.delta",
  "params": {
    "request_id": 51,
    "chunk": { "type": "text_delta", "delta": "Hello" }
  }
}
{
  "jsonrpc": "2.0",
  "method": "llm.chat.delta",
  "params": {
    "request_id": 51,
    "chunk": { "type": "text_delta", "delta": " world" }
  }
}

// child → host: final response (id matches request)
{
  "jsonrpc": "2.0",
  "id": 51,
  "result": {
    "content": { "type": "text", "text": "" },
    "usage": { "prompt_tokens": 12, "completion_tokens": 4 },
    "finish_reason": { "kind": "stop" }
  }
}

chunk.type values:

• text_delta — { delta: "<text>" }
• tool_call_start — { id, name }
• tool_call_args_delta — { id, delta }
• tool_call_end — { id }
• usage — { usage: {prompt_tokens, completion_tokens} }
• end — { finish_reason: {kind, reason?} }

Default host-side stream timeout 300 seconds. Operator override via NEXO_PLUGIN_LLM_TIMEOUT_MS env (single value applied to both sync + streaming).

LLM-specific error codes

In addition to the JSON-RPC standard codes (§7), llm.chat MAY return:

Error example:

{
  "jsonrpc": "2.0",
  "id": 50,
  "error": {
    "code": -33103,
    "message": "rate limited",
    "data": { "retry_after_secs": 30 }
  }
}

The host surfaces these as anyhow::Error with messages operators can grep ("rate limited", "authentication failed", etc.). Structured retry-after info lands in the message string for v1; future contract bumps may add a typed LlmProviderError enum.

5.z Hook methods (Phase 81.27)

Subprocess plugins that contribute hook handlers (declared in [plugin.extends].hooks, §2.1) implement one host-initiated request method.

hook.on_hook

// host → child
{
  "jsonrpc": "2.0",
  "id": 60,
  "method": "hook.on_hook",
  "params": {
    "plugin_id": "compliance_plugin",
    "hook_name": "before_message",
    "event": {
      "sender": "alice",
      "body": "ping"
    }
  }
}

// child → host (block)
{
  "jsonrpc": "2.0",
  "id": 60,
  "result": {
    "abort": true,
    "reason": "PII detected",
    "decision": "block"
  }
}

// child → host (transform — rewrite payload)
{
  "jsonrpc": "2.0",
  "id": 60,
  "result": {
    "abort": false,
    "decision": "transform",
    "transformed_body": "[REDACTED]"
  }
}

// child → host (allow / no-op)
{
  "jsonrpc": "2.0",
  "id": 60,
  "result": {}
}

The result shape is HookResponse (defined in crates/extensions/src/runtime/mod.rs). Fields:

• abort: bool (legacy block signal — Phase 11.6)
• reason: Option<String> (operator-readable explanation)
• override: Option<JsonValue> (key-by-key event mutation; non-object values logged + ignored)
• decision: Option<"allow" | "block" | "transform"> (Phase 83.3 — richer audit signal)
• transformed_body: Option<String> (only meaningful with decision: "transform")
• do_not_reply_again: bool (anti-loop signal — host suppresses pending auto-replies for the conversation)

Default host-side timeout: 5 seconds (lower than channel 30s and LLM 60s — hooks fire on the message hot path; long timeouts block agent flow). Operator override via NEXO_PLUGIN_HOOK_TIMEOUT_MS env.

Continue-on-error semantic

Every dispatch failure (transport closed, subprocess crash, timeout, JSON-RPC error, malformed reply) returns HookResponse::default() (Continue) on the host side. The HookRegistry::fire loop continues iterating remaining handlers and the agent flow does NOT break on subprocess misbehavior.

This is the explicit philosophy from hook_registry.rs:

"extension misbehavior must not take down agent flow."

Operators see the failures via tracing::warn! (target plugins.init and the handler's own dispatch logs).

-32601 method_not_found from a child means the plugin declared extends.hooks = [...] but did not implement the wire method; the host treats this as Continue (no hard failure).

5.w Memory backend methods (Phase 81.26)

Subprocess plugins that contribute vector store backends (declared in [plugin.extends].memory_backends, §2.1) implement three host-initiated request methods. The host's RemoteVectorBackend wraps each VectorBackend trait method into a JSON-RPC request; the child replies with the corresponding result or a typed error.

Every payload carries backend so a single subprocess advertising multiple backends (extends.memory_backends = ["pinecone", "qdrant"]) can dispatch via one request handler.

v1 ships the wire surface + registry only — operator-side consumer wiring (LongTermMemory.recall_vector reading from wire.vector_backend_registry) lands in 81.26.b. Operators can audit registered backends today via wire.vector_backend_registry.names().

memory.vector_upsert

// host → child
{
  "jsonrpc": "2.0",
  "id": 70,
  "method": "memory.vector_upsert",
  "params": {
    "backend": "pinecone",
    "collection": "kb",
    "records": [
      {
        "id": "r1",
        "content": "hello",
        "embedding": [0.1, 0.2, 0.3],
        "metadata": {"source": "kb"}
      }
    ]
  }
}

// child → host
{ "jsonrpc": "2.0", "id": 70, "result": { "count": 1 } }

embedding is a pre-computed dense vector (host-side embedder or LLM provider produces it; backend stores). metadata is opaque JSON the backend may filter against. Default host-side timeout 30 seconds.

memory.vector_search

// host → child
{
  "jsonrpc": "2.0",
  "id": 71,
  "method": "memory.vector_search",
  "params": {
    "backend": "pinecone",
    "collection": "kb",
    "query": {
      "embedding": [0.1, 0.2, 0.3],
      "limit": 10,
      "filter": {"namespace": "tenant-1"}
    }
  }
}

// child → host
{
  "jsonrpc": "2.0",
  "id": 71,
  "result": {
    "matches": [
      {
        "id": "r1",
        "content": "hello",
        "score": 0.97,
        "metadata": {"source": "kb"}
      }
    ]
  }
}

filter is opaque — backend interprets per its native convention (Pinecone metadata filter, Qdrant filter expression, Weaviate where, etc.). The host does NOT validate or rewrite. score uses the backend's native scale (cosine vs dot-product vs distance). Default host-side timeout 10 seconds (search is hot-path).

memory.vector_delete

// host → child
{
  "jsonrpc": "2.0",
  "id": 72,
  "method": "memory.vector_delete",
  "params": {
    "backend": "pinecone",
    "collection": "kb",
    "ids": ["r1", "r2"]
  }
}

// child → host
{ "jsonrpc": "2.0", "id": 72, "result": { "count": 2 } }

Default host-side timeout 30 seconds. Operator override via NEXO_PLUGIN_MEMORY_TIMEOUT_MS env (single value applied to all 3 methods).

Memory-specific error codes

In addition to the JSON-RPC standard codes (§7), memory.* methods MAY return:

Error example:

{
  "jsonrpc": "2.0",
  "id": 70,
  "error": {
    "code": -33302,
    "message": "dimension mismatch",
    "data": { "expected": 768, "got": 2 }
  }
}

The host surfaces these as anyhow::Error with messages operators can grep ("dimension mismatch: expected 768, got 2", "rate limited; retry after 60s", etc.).

5.t Tool methods (Phase 81.29)

Plugins declaring [plugin.extends].tools = [...] get a host-initiated tool.invoke request per agent-loop tool call. The daemon's LLM picks a tool name from the cached function- calling spec (built from initialize-reply's tools array, see §4.1.1), the agent's tool registry routes the call to a RemoteToolHandler, and the handler serializes the call into a tool.invoke JSON-RPC frame over the existing stdio bridge.

Default timeout: 60 s. Operator override via NEXO_PLUGIN_TOOL_TIMEOUT_MS.

tool.invoke

Host → child request:

{
  "jsonrpc": "2.0",
  "id": 80,
  "method": "tool.invoke",
  "params": {
    "plugin_id": "browser",
    "tool_name": "browser_navigate",
    "args": { "url": "https://example.com" },
    "agent_id": "shopper"
  }
}

Child → host reply on success — the result body is whatever JSON shape the daemon's ToolHandler::call returns to the agent loop. The conventional shape mirrors the in-tree ToolResponse:

{
  "jsonrpc": "2.0",
  "id": 80,
  "result": {
    "content": [
      { "type": "text", "text": "Navigated to https://example.com" }
    ],
    "is_error": false
  }
}

Plugins MAY return any JSON Value — the daemon does not validate the result shape beyond the JSON-RPC envelope. Tool authors using the Rust SDK return ToolResponse directly.

Tool-specific error codes

The host surfaces these as anyhow::Error with messages operators can grep ("tool not found", "argument invalid", "unavailable; retry after 5s", etc.). The agent loop receives the error and decides what to do (LLM retry, abort tool plan, escalate).

6. Topic allowlist

The host derives subscribe + publish patterns from the manifest's [[plugin.channels.register]] entries.

For each entry with kind = K:

Wildcard semantics follow nexo_broker::topic::topic_matches:

• * matches exactly one path segment.
• > matches one or more trailing segments (must have ≥1).
• Plain segments match literally.

So plugin.inbound.slack.> matches plugin.inbound.slack.team_a and plugin.inbound.slack.team_a.thread_42 but not plugin.inbound.slack (no trailing segments). That's why both exact and wildcard patterns are in the allowlist for each kind.

A child publish to a topic that does not match any pattern in the allowlist is dropped — this is the host's primary defense against a plugin attempting to hijack core nexo topics like agent.route.* or command.*.

7. Error codes

-32xxx is JSON-RPC reserved range; nexo extensions live in -31xxx (none used yet) and -32000..-32099 (implementation defined).

The host translates each of these into a structured PluginInitError or PluginShutdownError variant for operator diagnostics.

8. Backpressure

The host's stdin writer feeds the child via a bounded mpsc channel of depth 64. When the channel is full (the child is processing more slowly than the broker is delivering events to it), new broker.event notifications are dropped with a warn-level log rather than blocking the daemon's broker.

This matches the at-most-once delivery semantics the broker itself promises — no plugin should be relying on every event arriving. Plugins that need durable delivery should subscribe to a NATS jetstream stream out-of-band, which is outside the scope of this contract.

9. Examples

9.1 Rust

Using the nexo-microapp-sdk crate with the plugin feature (Phase 81.15.a):

use nexo_microapp_sdk::plugin::{PluginAdapter, BrokerSender};
use nexo_broker::Event;

const MANIFEST: &str = include_str!("../nexo-plugin.toml");

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    PluginAdapter::new(MANIFEST)?
        .on_broker_event(|topic: String, event: Event, broker: BrokerSender| async move {
            // Outbound: deliver to the external service.
            // (Pseudocode; replace with your channel client.)
            let payload = event.payload.clone();
            let text = payload.get("text").and_then(|v| v.as_str()).unwrap_or("");
            send_to_slack(text).await;

            // Inbound: relay any reply back via the broker.
            let reply = Event::new(
                "plugin.inbound.slack",
                "slack",
                serde_json::json!({"echo": text}),
            );
            let _ = broker.publish("plugin.inbound.slack", reply).await;
        })
        .on_shutdown(|| async { Ok(()) })
        .run_stdio()
        .await?;
    Ok(())
}

async fn send_to_slack(_text: &str) {}

9.2 Python — nexoai

pip install nexoai (the nexo-plugin-sdk name was taken on PyPI; the importable module stays nexo_plugin_sdk). Source: nexo-plugin-sdks/python/.

import asyncio
from nexo_plugin_sdk import PluginAdapter, Event

MANIFEST = open("nexo-plugin.toml").read()

async def on_event(topic: str, event: Event, broker) -> None:
    # call back into the host (memory.recall §5.2 / llm.complete §5.3):
    entries = await broker.memory_recall(agent_id="my_agent", query="user prefers concise answers", limit=5)
    result = await broker.llm_complete(provider="minimax", model="minimax-m2.5",
                                       messages=[{"role": "user", "content": "summarize: ..."}])
    await broker.publish("plugin.inbound.slack",
                         Event.new("plugin.inbound.slack", "slack", {"summary": result.content}))

async def main() -> None:
    await PluginAdapter(manifest_toml=MANIFEST, on_event=on_event).run()

asyncio.run(main())

9.3 TypeScript / Node — nexo-plugin-sdk

npm install nexo-plugin-sdk. Source: nexo-plugin-sdks/typescript/.

import { readFileSync } from "node:fs";
import { PluginAdapter, Event } from "nexo-plugin-sdk";

const adapter = new PluginAdapter({
  manifestToml: readFileSync("nexo-plugin.toml", "utf-8"),
  onEvent: async (topic, event, broker) => {
    const entries = await broker.memoryRecall({ agentId: "my_agent", query: "user prefers concise answers", limit: 5 });
    const result = await broker.llmComplete({ provider: "minimax", model: "minimax-m2.5",
      messages: [{ role: "user", content: "summarize: ..." }] });
    await broker.publish("plugin.inbound.slack",
      Event.new("plugin.inbound.slack", "slack", { summary: result.content }));
  },
});
await adapter.run();

9.4 PHP — nexo/plugin-sdk

composer require nexo/plugin-sdk (PHP ≥ 8.1 — uses Fibers). Source: nexo-plugin-sdks/php/ (mirrored to nexo-plugin-sdk-php for Packagist).

<?php declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use Nexo\Plugin\Sdk\{PluginAdapter, BrokerSender, Event};

$adapter = new PluginAdapter([
    'manifestToml' => file_get_contents(__DIR__ . '/nexo-plugin.toml'),
    'onEvent' => function (string $topic, Event $event, BrokerSender $broker): void {
        $entries = $broker->memoryRecall(['agentId' => 'my_agent', 'query' => 'user prefers concise answers', 'limit' => 5]);
        $r = $broker->llmComplete(['provider' => 'minimax', 'model' => 'minimax-m2.5',
            'messages' => [['role' => 'user', 'content' => 'summarize: ...']]]);
        $broker->publish('plugin.inbound.slack', Event::new('plugin.inbound.slack', 'slack', ['summary' => $r->content]));
        // streaming: $broker->llmCompleteStream($opts, fn(string $chunk) => /* ... */);
    },
]);
$adapter->run();

9.5 Tools — host-initiated tool.invoke (Phase 81.29)

A plugin that declares [plugin.extends].tools = ["myplugin_weather"] in its manifest advertises a tool catalog at handshake (the initialize reply's tools array, §4.1.1) and handles one tool.invoke request per agent-loop tool call (§5.t). All four SDKs expose the same surface: a catalog of tool definitions, one dispatch handler (optionally with a context giving broker access mid-invocation), and a typed -33401..-33405 error band.

Rust — crates/microapp-sdk with feature plugin:

use nexo_microapp_sdk::plugin::{PluginAdapter, ToolDef, ToolInvocation, ToolInvocationError};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    PluginAdapter::new(include_str!("../nexo-plugin.toml"))?
        .declare_tools(vec![ToolDef {
            name: "myplugin_weather".into(),
            description: "Current weather for a city".into(),
            input_schema: serde_json::json!({
                "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"]
            }),
        }])
        .on_tool(|inv: ToolInvocation| async move {
            let city = inv.args.get("city").and_then(|v| v.as_str())
                .ok_or_else(|| ToolInvocationError::ArgumentInvalid("missing `city`".into()))?;
            Ok(serde_json::json!({ "content": [{ "type": "text", "text": format!("Sunny in {city}") }], "is_error": false }))
        })
        .run_stdio().await?;
    Ok(())
}

Python — nexoai:

import asyncio
from nexo_plugin_sdk import PluginAdapter, ToolDef, ToolInvocation, ToolArgumentInvalid, text_result

MANIFEST = open("nexo-plugin.toml").read()

async def on_tool(inv: ToolInvocation):
    city = (inv.args or {}).get("city")
    if not city:
        raise ToolArgumentInvalid("missing `city`")
    return text_result(f"Sunny in {city}")

async def main() -> None:
    await PluginAdapter(
        manifest_toml=MANIFEST,
        tools=[ToolDef("myplugin_weather", "Current weather for a city",
                       {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]})],
        on_tool=on_tool,           # or on_tool_with_context=fn(inv, ctx) — ctx.broker = the on_event broker handle
    ).run()

asyncio.run(main())

TypeScript — nexo-plugin-sdk:

import { readFileSync } from "node:fs";
import { PluginAdapter, ToolArgumentInvalidError, textResult } from "nexo-plugin-sdk";

const adapter = new PluginAdapter({
  manifestToml: readFileSync("nexo-plugin.toml", "utf-8"),
  tools: [{ name: "myplugin_weather", description: "Current weather for a city",
    inputSchema: { type: "object", properties: { city: { type: "string" } }, required: ["city"] } }],
  onTool: (inv) => {
    const city = (inv.args as { city?: string } | null)?.city;
    if (!city) throw new ToolArgumentInvalidError("missing `city`");
    return textResult(`Sunny in ${city}`);
  },
  // or onToolWithContext: (inv, ctx) => { ... ctx.broker.memoryRecall(...) ... }
});
await adapter.run();

PHP — nexo/plugin-sdk:

<?php declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use Nexo\Plugin\Sdk\{PluginAdapter, Tool, ToolArgumentInvalid, ToolDef, ToolInvocation};

$adapter = new PluginAdapter([
    'manifestToml' => file_get_contents(__DIR__ . '/nexo-plugin.toml'),
    'tools' => [new ToolDef('myplugin_weather', 'Current weather for a city',
        ['type' => 'object', 'properties' => ['city' => ['type' => 'string']], 'required' => ['city']])],
    'onTool' => function (ToolInvocation $inv) {
        $city = $inv->args['city'] ?? null;
        if (!$city) { throw new ToolArgumentInvalid('missing `city`'); }
        return Tool::text("Sunny in {$city}");
    },
    // or 'onToolWithContext' => fn(ToolInvocation $inv, ToolContext $ctx) => /* $ctx->broker->memoryRecall(...) */
]);
$adapter->run();

Throwing one of the typed errors maps to the matching -33401..-33405 code: ToolNotFound (-33401), ToolArgumentInvalid (-33402, carries details), ToolExecutionFailed (-33403 — also the catch-all for an uncaught generic exception), ToolUnavailable (-33404, carries retry_after_ms), ToolDenied (-33405). A tool.invoke arriving when no handler is registered replies -32601. Declaring a tool whose name is not in the manifest's [plugin.extends].tools is a hard failure at construction (the daemon would otherwise kill the plugin — see §4.1.1).

10. Versioning + compatibility

This contract uses semver. The current version is 1.0.0.

Plugins should declare the contract version they target via the manifest's min_nexo_version field plus a future contract_version field (Phase 81.16 follow-up). The host rejects plugins targeting a major version it does not support.

11. Reference implementations

• Host adapter: crates/core/src/agent/nexo_plugin_registry/subprocess.rs (SubprocessNexoPlugin) — Phase 81.14 + 81.14.b.
• Rust child SDK: crates/microapp-sdk/src/plugin.rs (PluginAdapter, feature plugin) — Phase 81.15.a.
• Python / TypeScript / PHP child SDKs: github.com/lordmacu/nexo-plugin-sdks — python/ (PyPI nexoai), typescript/ (npm nexo-plugin-sdk), php/ (Packagist nexo/plugin-sdk, via the nexo-plugin-sdk-php mirror). All implement initialize / broker.event / shutdown / broker.publish, the child→host calls memory.recall / llm.complete (+ llm.complete.delta streaming), and the host→child tool.invoke request + the initialize-reply tool catalog (§4.1.1 / §5.t — Python nexoai ≥ 0.4.0, TypeScript / PHP ≥ 0.3.0).
• Go SDK: not yet planned.

11.1 Conformance kit

nexo-plugin-sdks/conformance/ is a cross-language conformance kit: one Python mock-host (conformance/mock_host.py), a set of declarative scenarios (conformance/scenarios/*.json — the expect* steps are the golden), and one config-driven fixture per SDK. An SDK is conformant iff python conformance/run.py --lang <lang> passes for it — the kit drives the fixture through every exchange this contract defines (initialize / shutdown / broker.event / broker.publish / memory.recall / llm.complete (+ streaming) / tool.invoke + the §4.1.1 catalog) and diffs the frames structurally (methods, ids, result/error shapes, error codes, error.data shape, key presence/absence — not message text). The nexo-plugin-sdks CI runs the {python, typescript, php} matrix; the Rust SDK runs the same kit in this repo's CI via a shallow clone (--lang rust --fixture <built-binary> --check-contract-version docs/src/plugins/contract.md — the version check ties §13's top entry to the kit's SCENARIOS_TARGET, so a contract bump that lands without updating the kit fails CI). The kit does not replace the per-SDK test suites, which cover lang-specific robustness (async readers, Fiber scheduling, the stdout guard, signal handling). Added in Phase 31.12; the Rust-fixture wiring + reconciling the divergences the kit surfaces (the Rust child SDK does not yet emit error.data.details / error.data.retry_after_ms, and its nexo_broker::Event serializes with extra id / timestamp / session_id fields the scripting SDKs omit) is follow-up 31.12.b.

12. Out of contract scope

The following are part of the broader plugin platform but are deliberately out of THIS document's scope:

• memory.recall / llm.complete / tool.dispatch RPC bridges (Phase 81.20) — let the child invoke daemon-mediated framework services.
• Supervisor + respawn + resource limits (Phase 81.21).
• Sandbox (network + filesystem allowlist via manifest, Phase 81.22).
• Stdio → tracing bridge (Phase 81.23).
• Plugin marketplace + signing (Phase 31).

Each of these will either extend this contract additively (in which case contract_version bumps minor) or live in a separate contract document.

13. Changelog

See also

• Authoring overview
• Rust SDK, Python SDK, TypeScript SDK, PHP SDK
• Publishing a plugin, Signing & publishing

Plugin patterns

Common shapes for nexo subprocess plugins. Each pattern is a template you adapt — pick the closest match to what you're building, copy the skeleton, modify.

All patterns work in any of the 4 SDK languages (Rust / Python / TypeScript / PHP). Examples below use the language that's clearest for the pattern.

Pattern 1 · Echo channel

When to use · You're learning the SDK or wiring a brand-new channel and want a smoke-test before adding logic.

The plugin echoes every inbound broker.event back as broker.publish on a mirrored topic. Useful for verifying the wire format end-to-end before you write business logic.

from nexo_plugin_sdk import PluginAdapter, Event

async def on_event(topic, event, broker):
    out_topic = topic.replace("plugin.outbound.", "plugin.inbound.")
    await broker.publish(out_topic, Event.new(out_topic, "my_plugin", event.payload))

await PluginAdapter(manifest_toml=MANIFEST, on_event=on_event).run()

→ Used in every template (extensions/template-plugin-{rust,python,typescript,php}/)

Pattern 2 · Webhook receiver

When to use · An external service POSTs JSON; you want the daemon to see it as a plugin.inbound.<kind> event.

Plugin runs an HTTP server (or listens on a Unix socket) for inbound POST requests. Each request becomes a broker publish. Plugin's manifest declares an http_server capability so the daemon's reverse-proxy / port-allocator wires the route.

use nexo_microapp_sdk::plugin::{BrokerSender, Event, PluginAdapter};
use axum::{Router, routing::post, extract::State, Json};

async fn webhook(State(broker): State<Arc<BrokerSender>>, Json(body): Json<Value>) {
    let event = Event::new("plugin.inbound.webhook", "my_plugin", body);
    let _ = broker.publish("plugin.inbound.webhook", event).await;
}

#[tokio::main]
async fn main() -> Result<()> {
    let adapter = PluginAdapter::new(MANIFEST);
    let broker = adapter.broker();
    tokio::spawn(async move {
        let app = Router::new().route("/webhook", post(webhook)).with_state(broker);
        axum::serve(listener, app).await
    });
    adapter.run().await
}

Manifest declares the inbound topic the plugin will publish to:

[[plugin.channels.register]]
kind = "webhook"
adapter = "WebhookAdapter"

Pattern 3 · RPC bridge to an external API

When to use · You're exposing a third-party service (Stripe, Twilio, internal CRM) as a tool the agent can call.

Plugin doesn't deal with channels — it registers as a tool provider. The agent sends a tool.call request; the plugin forwards to the external API and replies.

import { PluginAdapter } from "nexo-plugin-sdk";

const adapter = new PluginAdapter({
  manifestToml: MANIFEST,
  onEvent: async (topic, event, broker) => {
    if (topic === "plugin.tool.stripe.create_invoice") {
      const inv = await stripeClient.invoices.create(event.payload);
      await broker.publish("plugin.tool.stripe.create_invoice.reply",
        Event.new("plugin.tool.reply", "stripe-bridge", { result: inv }));
    }
  },
});

Manifest contributes the tool:

[[plugin.tools.expose]]
name = "stripe.create_invoice"
schema_path = "./tools/create_invoice.json"

Pattern 4 · Scheduled poller

When to use · You need to poll an external feed every N minutes and publish only changes (deltas) to the broker.

Plugin holds local state (last-seen IDs / etag / cursor), re-polls on a timer, dedupes against state, publishes new items. Persist state to <state_dir>/<plugin_id>/state.json so restarts don't re-emit historical items.

import asyncio, json, aiohttp
from pathlib import Path
from nexo_plugin_sdk import PluginAdapter, Event

STATE = Path(".nexo-state/poller.json")
seen_ids: set[str] = set(json.loads(STATE.read_text())) if STATE.exists() else set()

async def poll_loop(broker):
    while True:
        async with aiohttp.ClientSession() as s:
            items = await (await s.get("https://example.com/feed.json")).json()
        for item in items:
            if item["id"] in seen_ids:
                continue
            seen_ids.add(item["id"])
            await broker.publish("plugin.inbound.feed",
                Event.new("plugin.inbound.feed", "feed_poller", item))
        STATE.write_text(json.dumps(list(seen_ids)))
        await asyncio.sleep(300)  # 5 min

adapter = PluginAdapter(manifest_toml=MANIFEST)
asyncio.create_task(poll_loop(adapter.broker))
await adapter.run()

→ See Build a poller module for the YAML-only path that doesn't need a plugin at all.

Pattern 5 · Long-running connection (websocket / SSE)

When to use · The external service is push-based (Slack RTM, Discord gateway, MQTT broker, custom WebSocket).

Plugin opens the persistent connection at startup. Inbound messages from the external side become broker.publish events. On disconnect, the plugin reconnects with exponential backoff.

#![allow(unused)]
fn main() {
use tokio_tungstenite::connect_async;

let (ws, _) = connect_async("wss://gateway.discord.gg/").await?;
let (write, mut read) = ws.split();
// Auth handshake omitted...

while let Some(msg) = read.next().await {
    let evt = parse_discord(msg?)?;
    broker.publish("plugin.inbound.discord", evt).await?;
}
// On disconnect: reconnect with backoff.
}

The SDK's signal handling (default-on) lets the daemon shut the plugin down cleanly even mid-connection.

Pattern 6 · Stateful conversation glue

When to use · The external channel sends fragments (audio chunks, typing indicators, partial messages) and you want to assemble them before the agent sees a complete event.

Plugin maintains a per-conversation buffer; only emits a broker.publish when the message is "complete" (final chunk, silence timeout, or explicit done marker).

buffer: dict[str, list[str]] = {}
timers: dict[str, asyncio.Task] = {}

async def on_chunk(conv_id, fragment, broker):
    buffer.setdefault(conv_id, []).append(fragment)
    if conv_id in timers:
        timers[conv_id].cancel()
    timers[conv_id] = asyncio.create_task(flush_after(conv_id, broker, delay=2.0))

async def flush_after(conv_id, broker, delay):
    await asyncio.sleep(delay)
    text = "".join(buffer.pop(conv_id, []))
    await broker.publish("plugin.inbound.assembled",
        Event.new("plugin.inbound.assembled", "voice_glue", {"text": text}))

Pattern 7 · Outbound-only adapter

When to use · The plugin only sends (Twilio SMS sender, push notification dispatcher, Slack outbound webhook).

Plugin subscribes to plugin.outbound.<kind> events from the daemon, calls the external API, and publishes a delivery_status event back so the agent knows whether it landed.

const adapter = new PluginAdapter({
  manifestToml: MANIFEST,
  onEvent: async (topic, event, broker) => {
    if (topic.startsWith("plugin.outbound.sms")) {
      const result = await twilio.messages.create({
        to: event.payload.to,
        body: event.payload.body,
        from: TWILIO_FROM,
      });
      await broker.publish("plugin.delivery.sms",
        Event.new("plugin.delivery.sms", "twilio-out",
                  { sid: result.sid, status: result.status }));
    }
  },
});

Pattern 8 · Provider abstraction (multi-instance)

When to use · Operator wants 3 different Telegram bots, each isolated. Or 5 WhatsApp accounts.

Plugin manifest declares instance support. Operator's config spawns N copies, each with a distinct instance label. Topics become plugin.inbound.<kind>.<instance> so agent bindings can target a specific one.

# operator's pollers.yaml
plugins:
  telegram:
    - instance: support-bot
      bot_token_env: TG_SUPPORT_TOKEN
    - instance: sales-bot
      bot_token_env: TG_SALES_TOKEN

The plugin reads instance from args or env at startup and publishes to plugin.inbound.telegram.<instance>.

Choosing between patterns

See also

• Plugin contract — the wire format every plugin implements.
• Publishing a plugin — CI workflow + asset convention.
• Python SDK, TypeScript SDK, PHP SDK — language-specific guides.

Rust plugin SDK

Phase 31.9. Author plugins in Rust that the daemon spawns as subprocesses, talking the same JSON-RPC 2.0 wire format used by the Python / TypeScript / PHP SDKs.

The SDK lives in crates/microapp-sdk/ behind the plugin Cargo feature; the reference plugin template is at extensions/template-plugin-rust/. Use nexo plugin new <id> --lang rust to scaffold a fresh out-of-tree project from that template.

Read this when

• You picked Rust from the language picker in Plugin authoring overview and want the SDK reference.
• You are porting an in-tree plugin (crates/plugins/<id>) into an out-of-tree subprocess and need the wire-API mapping.
• You want the canonical Rust handler signature for broker.event notifications.

Why subprocess + Rust

Running Rust plugins as separate processes — instead of crates linked into the daemon — gives you:

• Isolation — a panic in your plugin terminates one process, not the daemon.
• One contract, every language — the daemon treats your binary the same way it treats Python or TypeScript plugins. Switching languages later is an SDK choice, not a daemon recompile.
• No link-time coupling — your plugin can use any Rust toolchain or tokio version that compiles; the daemon does not care.
• Single static binary — cargo build --release produces one file the publish workflow uploads as the per-target tarball.

Daemon-side spawn code in crates/core/src/agent/nexo_plugin_registry/subprocess.rs treats the plugin as an opaque executable; Rust plugins re-use that path without modification.

Architecture

Operator host                              Plugin process
┌──────────────────┐    stdin   ┌─────────────────────────────┐
│ daemon (Rust)    │──JSON-RPC──▶│ target/release/<id>         │
│ subprocess host  │             │   tokio::main async runtime │
│                  │◀──JSON-RPC──│   PluginAdapter.run_stdio() │
└──────────────────┘    stdout   └─────────────────────────────┘

The daemon writes newline-delimited JSON-RPC requests to your binary's stdin; you write replies + outbound broker.publish notifications back on stdout. stderr is collected by the operator's tracing pipeline (Phase 81.23 fold pending) — use it freely for plugin-side logs.

Public API

#![allow(unused)]
fn main() {
use nexo_broker::Event;
use nexo_microapp_sdk::plugin::{BrokerSender, PluginAdapter};
}

PluginAdapter builder methods:

Event (re-exported from nexo-broker) carries topic, source, payload: serde_json::Value, optional correlation_id

• metadata. Construct with Event::new(topic, source, payload) which stamps a fresh UUID + RFC3339 timestamp.

BrokerSender::publish(topic: &str, event: Event) -> Result<(), WireError> serializes a broker.publish notification to stdout under an internal write lock. The daemon's bridge re-checks the topic against the manifest's [[plugin.channels.register]] allowlist before forwarding to the broker.

Manifest example

[plugin]
id = "my_plugin"
version = "0.1.0"
name = "My Plugin"
description = "Forwards inbound events to a third-party API."
min_nexo_version = ">=0.1.0"

[plugin.requires]
nexo_capabilities = ["broker"]

[[plugin.channels.register]]
kind = "my_plugin_inbound"
description = "Inbound events the plugin emits onto the broker."

plugin.id MUST match ^[a-z][a-z0-9_]{0,31}$. Cargo's [[bin]] name MUST equal plugin.id so the publish workflow's pack-tarball.sh finds the artifact at target/<target>/release/<id>.

See Plugin contract for the full manifest schema and the JSON-RPC envelope every method exchanges.

Quickstart

Scaffold + build + run, copy-paste:

nexo plugin new my_plugin --lang rust --owner alice
cd my_plugin
cargo build
nexo plugin run .

nexo plugin run boots the daemon with your plugin injected at the head of plugins.discovery.search_paths, bypassing the install pipeline. See Local dev loop for the inner-loop conventions and --no-daemon-config.

The handler in the scaffolded src/main.rs echoes every inbound event back on plugin.inbound.<id>_echo:

use nexo_broker::Event;
use nexo_microapp_sdk::plugin::{print_manifest_if_requested, BrokerSender, PluginAdapter};

const MANIFEST: &str = include_str!("../nexo-plugin.toml");

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // First line — honour the daemon's plugin auto-discovery probe.
    // When invoked with `--print-manifest`, dump the embedded TOML
    // to stdout and exit 0 before constructing any runtime state.
    print_manifest_if_requested(MANIFEST);

    tracing_subscriber::fmt()
        .with_writer(std::io::stderr)
        .init();

    PluginAdapter::new(MANIFEST)?
        .on_broker_event(handle_event)
        .on_shutdown(|| async {
            tracing::info!("plugin shutdown handler invoked");
            Ok(())
        })
        .run_stdio()
        .await?;
    Ok(())
}

async fn handle_event(topic: String, event: Event, broker: BrokerSender) {
    let echo = Event::new(
        "plugin.inbound.my_plugin_echo",
        "my_plugin",
        serde_json::json!({
            "echoed_from": topic,
            "echoed_payload": event.payload,
        }),
    );
    let _ = broker
        .publish("plugin.inbound.my_plugin_echo", echo)
        .await;
}

Replace the body of handle_event with your channel's real outbound logic (forward to a third-party API, persist to disk, trigger a downstream agent, etc.) and re-publish the API's reply back through broker so agents can observe it.

Smoke test

Hand-run the binary against a synthetic JSON-RPC frame to confirm the handshake is well-formed:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
    | ./target/debug/my_plugin

The plugin should print one JSON-RPC response containing your manifest's id, version, name, and the SDK's server_version. If you see anything other than a single line of valid JSON on stdout, check that you have not added stray println!s in the handler — every byte on stdout must be a JSON-RPC frame. Use eprintln! / tracing::* for logs.

Auto-discovery probe

The daemon's discovery walker checks each candidate binary with --print-manifest (Phase 81.33 Stage 8). Verify your plugin answers it correctly:

./target/debug/my_plugin --print-manifest

The expected output is the verbatim contents of nexo-plugin.toml followed by exit 0. The print_manifest_if_requested(MANIFEST) call in main() handles this for you — if the smoke test prints anything else (logs, empty stdout, a JSON-RPC frame) the helper is missing from your entry point.

Per-target tarball convention

Operators install Rust plugins via the same nexo plugin install <owner>/<repo>[@<tag>] CLI. The resolver expects per-target tarballs:

<id>-<version>-<target>.tar.gz
├── nexo-plugin.toml
└── bin/<id>           # static binary, mode 0755

Targets follow Rust's standard target triples (x86_64-unknown-linux-gnu, aarch64-apple-darwin, x86_64-unknown-linux-musl, etc.). The shipped CI workflow in extensions/template-plugin-rust/.github/workflows/release.yml covers Linux musl + macOS by default; add additional matrix entries to support more.

CI publish workflow

The shipped workflow has 4 jobs: validate-tag → build (matrix) → optional sign (cosign keyless, gated by repo variable COSIGN_ENABLED) → release (uploads all tarballs + sha256 sidecars + signing material + a copy of nexo-plugin.toml). See Publishing a plugin for the full asset naming convention and Signing & publishing for the end-to-end signed-release tutorial.

Local validation

Before pushing a tag, dry-run the pack step:

cargo build --release --target x86_64-unknown-linux-gnu
bash scripts/pack-tarball.sh x86_64-unknown-linux-gnu
ls dist/
# my_plugin-0.1.0-x86_64-unknown-linux-gnu.tar.gz
# my_plugin-0.1.0-x86_64-unknown-linux-gnu.tar.gz.sha256

The Rust integration test extensions/template-plugin-rust/tests/pack_tarball.rs covers this end-to-end against a synthetic binary; copy it when you fork the template to keep the convention regression-tested.

SDK tests

cargo test -p nexo-microapp-sdk --features plugin

Covers handshake, manifest validation, dispatch (including non-blocking reader proof), shutdown lifecycle, unknown-method handling, oversized-frame rejection.

See also

• Plugin authoring overview — start here if you have not picked a language yet.
• Plugin contract — full wire spec every SDK implements.
• Patterns (8 common shapes) — channel / poller / hybrid plugin shapes.
• Publishing a plugin — CI workflow shape and asset naming convention.
• Signing & publishing — cosign keyless tutorial.
• Plugin trust (trusted_keys.toml) — operator-side verification policy.

Python plugin SDK

Author plugins in Python that the daemon spawns as subprocesses, talking the same JSON-RPC 2.0 wire format used by the Rust SDK in crates/microapp-sdk/. The robustness defaults (stdout guard, frame cap, signal handling) match the TypeScript and PHP SDKs (sub-phase 31.4.c).

Reference template: extensions/template-plugin-python/ (or run nexo plugin new --lang python). The SDK package lives in the nexo-plugin-sdks repo (python/ subdir) and ships on PyPI as nexoai — pip install nexoai (the nexo-plugin-sdk name was taken; the importable module is still nexo_plugin_sdk).