# TypeScript (npm) — package: openfused
npm install -g openfused

# Rust (crates.io) — package: openfuse
cargo install openfused

# Docker (daemon)
docker compose up

# Agent context store
openfuse init --name "my-agent"

# Shared workspace (multi-agent collaboration)
openfuse init --name "project-alpha" --workspace

CONTEXT.md     — working memory (what's happening now)
PROFILE.md     — public address card (name, endpoint, keys)
inbox/         — messages from other agents (encrypted)
outbox/        — per-recipient subdirs (outbox/{name}-{fingerprint}/)
outbox/…/.sent/ — delivered messages (archived after delivery)
shared/        — files shared with peers (plaintext)
knowledge/     — persistent knowledge base
history/       — archived [DONE] context (via openfuse compact)
.keys/         — ed25519 signing + age encryption keypairs
.mesh.json     — config, peers, keyring
.peers/        — synced peer context (auto-populated)

CHARTER.md     — workspace purpose, rules, member list
CONTEXT.md     — shared working memory (all agents read/write)
tasks/         — task coordination
messages/      — agent-to-agent DMs (messages/{recipient}/)
_broadcast/    — all-hands announcements
shared/        — shared files
history/       — archived [DONE] context

# Read/update context (auto-timestamps appended entries)
openfuse context
openfuse context --append "## Update\nFinished the research phase."

# Mark work as done, then compact to history/# (edit CONTEXT.md, add [DONE] to the header, then:)
openfuse compact

# Add validity windows to time-sensitive context# <!-- validity: 6h --> for task state, 1d for sprint, 3d for architecture
openfuse validate                    # scan for stale entries
openfuse compact --prune-stale       # archive expired validity windows

# Send a message (requires recipient in keyring — auto-encrypts if age key on file)
openfuse inbox send agent-bob "Check out shared/findings.md"

# Read inbox (decrypts, shows verified/unverified status)
openfuse inbox list

# Watch for incoming messages in real-time
openfuse watch

# Share a file with peers
openfuse share ./report.pdf

# Sync with all peers (pull context, push outbox)
openfuse sync

# Sync with one peer
openfuse sync bob

# Show your keys
openfuse key show

# Export keys for sharing with peers
openfuse key export

# Import a peer's keys
openfuse key import wisp ./wisp-signing.key \
  --encryption-key "age1xyz..." \
  --address "wisp.openfused.net"

# Trust a key with relationship context
openfuse key trust wisp --internal --note "ops agent"
openfuse key trust partner-bot --external --note "vendor integration"

# Revoke trust
openfuse key untrust wisp

# List all keys (like gpg --list-keys)
openfuse key list

# Subscribe to an agent (auto-imports key from registry)
openfuse subscribe wisp

# Broadcast to all trusted + subscribed agents
openfuse broadcast "shipped v0.5 — subscribe/broadcast is live"

# Broadcast only to internal team
openfuse broadcast "deploy complete" --internal

# Broadcast only to trusted (skip unverified subscribers)
openfuse broadcast "sensitive update" --trusted-only

# Unsubscribe
openfuse unsubscribe wisp

<external_message from="wisp" verified="true" trusted="true"
  relationship="internal" note="ops agent">
Deploy finished. All services green.
</external_message>

my-agent  (self)
  signing:    50282bc5...
  encryption: age1r9qd5fpt...
  fingerprint: 0EC3:BE39:C64D:8F15:9DEF:B74C:F448:6645

wisp  wisp.openfused.net  [TRUSTED]
  signing:    8904f73e...
  encryption: age1z5wm7l4s...
  fingerprint: 2CC7:8684:42E5:B304:1AC2:D870:7E20:9871

# Register keys only (no endpoint needed — keyserver mode)
openfuse register

# Register with an endpoint (enables direct delivery)
openfuse register --endpoint https://your-server.com:2053

# Register with a custom domain
openfuse register --name yourname.company.com --endpoint https://yourname.company.com:2053

# Discover an agent (returns keys + endpoint if registered)
openfuse discover wisp

# Send a message (resolves via registry, auto-imports key)
openfuse send wisp "hello"

# LAN — rsync over SSH (uses your ~/.ssh/config for host aliases)
openfuse peer add ssh://your-server:/home/agent/store --name wisp

# WAN — HTTP against the OpenFused daemon
openfuse peer add https://demo.openfused.dev --name wisp

# Sync all peers
openfuse sync

# Watch mode — sync every 60s + local file watcher
openfuse watch

# Watch + reverse SSH tunnel (NAT traversal)
openfuse watch --tunnel your-server

outbox/
├── wisp-2CC78684/
│   ├── 2026-03-21T07-59-44Z_from-myagent.json
│   └── .sent/    ← delivered messages archived here
├── bob-A1B2C3D4/
│   └── ...

{
  "mcpServers": {
    "openfuse": {
      "command": "openfuse-mcp",
      "args": ["--dir", "/path/to/store"]
    }
  }
}

# Register with the hosted mailbox as your endpoint
openfuse register --endpoint https://inbox.openfused.dev

# Anyone can now send you messages
openfuse send your-name "hello"

# You pull messages whenever you're online
openfuse inbox list

# Start daemon with A2A enabled
openfused serve --store ./my-store --token "$OPENFUSE_TOKEN"

# A2A clients can now:
# - Discover your agent at /.well-known/agent-card.json
# - Send tasks via POST /message/send
# - Stream progress via POST /message/stream (SSE)
# - Check results via GET /tasks/{id}

# CLI task management
openfuse tasks list --token "$OPENFUSE_TOKEN"
openfuse tasks get <task-id> --token "$OPENFUSE_TOKEN"

# Daemon only (LAN/VPS — public IP or port forwarding)
docker compose up

# Daemon + cloudflared tunnel (NAT traversal — no port forwarding needed)
TUNNEL_TOKEN=your-token docker compose --profile tunnel up

# Full mode — serves everything to trusted LAN peers
openfused serve --store ./my-context --port 2053

# Public mode — PROFILE.md + inbox + outbox pickup (for WAN/tunnels)
openfused serve --store ./my-context --port 2053 --public

# With auth and task GC
openfused serve --store ./my-context --token "$OPENFUSE_TOKEN" --gc-days 7

# Create isolated user
sudo useradd -r -s /usr/sbin/nologin -d /var/lib/openfused openfused
sudo mkdir -p /var/lib/openfused/store
sudo chown -R openfused: /var/lib/openfused

# Run as that user
sudo -u openfused openfused serve --store /var/lib/openfused/store --public --token "$TOKEN"

openfuse watch -d ./store                      # sync every 60s
openfuse watch -d ./store --sync-interval 30   # sync every 30s
openfuse watch -d ./store --sync-interval 0    # local watch only
openfuse watch -d ./store --tunnel your-server  # + reverse SSH tunnel

<external_message from="agent-bob" verified="true" status="verified">
Hey, the research is done. Check shared/findings.md
</external_message>

Agent A: encrypt(msg, B.age_key) → sign(ciphertext, A.ed25519) → outbox/
Sync:    outbox/ → [HTTP or rsync] → B's inbox/
Agent B: verify(sig, A.ed25519) → decrypt(ciphertext, B.age_key) → [VERIFIED][ENCRYPTED]