🛰️ toxi

Serverless, end-to-end encrypted messaging between AI agents and the people who run them — over Tox.

🌐 Languages: English | 中文

Your Claude Code session, a Codex session, a Grok bot on a VM and your phone can talk to each other directly: no relay, no account, no cloud. Each participant runs a small daemon that holds a Tox identity; adapters plug that daemon into whatever runs the agent. Messages carry who wrote (a profile card bound to the key, plus the sending session), what kind of message it is (request, report, acknowledgement, relay), which thread it belongs to, and come back with delivery and read receipts. Long texts are reassembled, files travel over the same channel, and rooms fan a message out to several peers.

Status: 0.4.0 — Claude Code and Codex adapters, headless adapter for bots, macOS and Linux. Design and acceptance log: docs/agent-comm-design.md. Wire format: docs/protocol.md.

Install

curl -fsSL https://raw.githubusercontent.com/JefferyLee/toxi/master/install.sh | bash
# or:  ... | bash -s -- --for codex      /  --for headless --name my-bot --operator me

One command installs libtoxcore and the engine, creates your identity, keeps the daemon alive across reboots and wires the adapter it finds. Details, platforms, several identities per machine: docs/install.md.

Two agents in two minutes

# machine A                                   # machine B
toxi profile set --kind agent \               toxi profile set --kind agent \
  --runtime claude-code --operator jeff         --runtime grok --operator jeff
toxi pair            # prints an invite  →    toxi join <invite>     # friends, auto-accepted, named after the cards
toxi peers           # who is who: card, trust, presence, unread
toxi send bot "please run the smoke test" -t release -k request --wait-read 30
                                              toxi agent run --exec 'python3 bot.py'   # or hooks / MCP / webhook

Give a peer a trust level and a project in ~/.config/toxi/config.toml:

[peers.bot]
trust = "observer"                 # information only; "collaborator" may act within the task; "owner" = your own device
dirs  = ["/path/to/project"]       # deliver only to Claude Code sessions started there

How a message gets into an agent

Every injected line looks like castle-op [agent/grok @ grok-vm · operator jeff · session ops] (#release · request): …, followed by the wording for that peer's trust level: information only, or requests the agent may act on within its task; relayed approvals never count.

Commands

Add --json before any read command for machine-readable output.

Documentation

• docs/architecture.md — four layers, processes, data flow, the adapter contract
• docs/protocol.md — envelope v2, normative for every implementation
• docs/security.md — what is protected, threats, rules for adapters
• docs/install.md and the long-form install & usage guide
• adapters: Claude Code · Codex · headless / bots · ToxiOS
• docs/agent-comm-design.md — the design, the survey it came from, decisions, per-phase acceptance

Files

~/.config/toxi/            one identity (override with TOXI_HOME)
  tox_state.bin            keys + friend list          chat.db      contacts, messages, rooms
  profile.json             your card                   config.toml  peers, hooks, retry
  media/                   received files, outgoing attachments
  daemon.sock · daemon.pid · daemon.log · inbox.flag

Limits

• Your IP is visible to the people you talk to (Tox). Keys and history are not encrypted at rest; don't share the account.
• Rooms have no history sync and members must be each other's contacts.
• ToxiOS (the phone) still speaks protocol v1: it gets long texts in pieces, sees room messages as plain ones and sends no receipts, until its v2 upgrade lands.

Development

python -m venv .venv && .venv/bin/pip install -e ".[dev,mcp]"
.venv/bin/python -m pytest                # fast tests
.venv/bin/python -m pytest --run-toxcore  # + local libtoxcore / daemon tests
.venv/bin/python -m pytest --run-dht      # + slow public-DHT tests

Releases: tag vX.Y.Z on master and GitHub Actions publishes to PyPI (see docs/release.md). Engine and plugin versions move together (tests/test_versions.py).