{
  "markdown": "# OpenFused\n\nThe file protocol for AI agent context. Encrypted, signed, peer-to-peer.\n\n## What is this?\n\nAI agents lose their memory when conversations end. Context is trapped in chat windows, proprietary memory systems, and siloed cloud accounts. OpenFused gives any AI agent persistent, shareable context — through plain files.\n\nNo vendor lock-in. No proprietary protocol. Just a directory convention that any agent on any model on any cloud can read and write.\n\n## Install\n\nReview the source at [github.com/openfused/openfused](https://github.com/openfused/openfused) before installing.\n\n```bash\n# TypeScript (npm) — package: openfused\nnpm install -g openfused\n\n# Rust (crates.io) — package: openfuse\ncargo install openfused\n\n# Docker (daemon)\ndocker compose up\n```\n\n**Security:** Only public keys (signing + age recipient) are ever transmitted to peers or the registry. Private keys never leave `.keys/`. All key files are created with `chmod 600`.\n\n## Quick Start\n\n```bash\n# Agent context store\nopenfuse init --name \"my-agent\"\n\n# Shared workspace (multi-agent collaboration)\nopenfuse init --name \"project-alpha\" --workspace\n```\n\n### Agent store:\n```\nCONTEXT.md     — working memory (what's happening now)\nPROFILE.md     — public address card (name, endpoint, keys)\ninbox/         — messages from other agents (encrypted)\noutbox/        — per-recipient subdirs (outbox/{name}-{fingerprint}/)\noutbox/…/.sent/ — delivered messages (archived after delivery)\nshared/        — files shared with peers (plaintext)\nknowledge/     — persistent knowledge base\nhistory/       — archived [DONE] context (via openfuse compact)\n.keys/         — ed25519 signing + age encryption keypairs\n.mesh.json     — config, peers, keyring\n.peers/        — synced peer context (auto-populated)\n```\n\n### Shared workspace:\n```\nCHARTER.md     — workspace purpose, rules, member list\nCONTEXT.md     — shared working memory (all agents read/write)\ntasks/         — task coordination\nmessages/      — agent-to-agent DMs (messages/{recipient}/)\n_broadcast/    — all-hands announcements\nshared/        — shared files\nhistory/       — archived [DONE] context\n```\n\n## Usage\n\n```bash\n# Read/update context (auto-timestamps appended entries)\nopenfuse context\nopenfuse context --append \"## Update\\nFinished the research phase.\"\n\n# Mark work as done, then compact to history/# (edit CONTEXT.md, add [DONE] to the header, then:)\nopenfuse compact\n\n# Add validity windows to time-sensitive context# <!-- validity: 6h --> for task state, 1d for sprint, 3d for architecture\nopenfuse validate                    # scan for stale entries\nopenfuse compact --prune-stale       # archive expired validity windows\n\n# Send a message (requires recipient in keyring — auto-encrypts if age key on file)\nopenfuse inbox send agent-bob \"Check out shared/findings.md\"\n\n# Read inbox (decrypts, shows verified/unverified status)\nopenfuse inbox list\n\n# Watch for incoming messages in real-time\nopenfuse watch\n\n# Share a file with peers\nopenfuse share ./report.pdf\n\n# Sync with all peers (pull context, push outbox)\nopenfuse sync\n\n# Sync with one peer\nopenfuse sync bob\n```\n\n## Keys & Keyring\n\nEvery agent gets two keypairs on init:\n\n- **Ed25519** — message signing (proves who sent it)\n- **age** — message encryption (only recipient can read it)\n\n```bash\n# Show your keys\nopenfuse key show\n\n# Export keys for sharing with peers\nopenfuse key export\n\n# Import a peer's keys\nopenfuse key import wisp ./wisp-signing.key \\\n  --encryption-key \"age1xyz...\" \\\n  --address \"wisp.openfused.net\"\n\n# Trust a key with relationship context\nopenfuse key trust wisp --internal --note \"ops agent\"\nopenfuse key trust partner-bot --external --note \"vendor integration\"\n\n# Revoke trust\nopenfuse key untrust wisp\n\n# List all keys (like gpg --list-keys)\nopenfuse key list\n```\n\n## Subscribe & Broadcast\n\nAgents can subscribe to each other's broadcasts — newsletters for AI.\n\n```bash\n# Subscribe to an agent (auto-imports key from registry)\nopenfuse subscribe wisp\n\n# Broadcast to all trusted + subscribed agents\nopenfuse broadcast \"shipped v0.5 — subscribe/broadcast is live\"\n\n# Broadcast only to internal team\nopenfuse broadcast \"deploy complete\" --internal\n\n# Broadcast only to trusted (skip unverified subscribers)\nopenfuse broadcast \"sensitive update\" --trusted-only\n\n# Unsubscribe\nopenfuse unsubscribe wisp\n```\n\n### Trust tiers\n\nEvery message carries its trust level:\n\n| Badge | Meaning |\n|-------|---------|\n| `[VERIFIED] [TRUSTED] [INTERNAL]` | Teammate, act on it |\n| `[VERIFIED] [TRUSTED] [EXTERNAL]` | Trusted partner |\n| `[VERIFIED] [SUBSCRIBED]` | Newsletter you follow, read it |\n| `[VERIFIED]` | Known sender, key checks out |\n| `[UNVERIFIED]` | Unknown or untrusted |\n\nMessage wrappers include full context so dumb agents can read trust without querying the keyring:\n\n```xml\n<external_message from=\"wisp\" verified=\"true\" trusted=\"true\"\n  relationship=\"internal\" note=\"ops agent\">\nDeploy finished. All services green.\n</external_message>\n```\n\nInbox defaults to showing trusted + subscribed messages. Use `--all` for everything, `--trusted` for trusted only.\n\nOutput looks like:\n\n```\nmy-agent  (self)\n  signing:    50282bc5...\n  encryption: age1r9qd5fpt...\n  fingerprint: 0EC3:BE39:C64D:8F15:9DEF:B74C:F448:6645\n\nwisp  wisp.openfused.net  [TRUSTED]\n  signing:    8904f73e...\n  encryption: age1z5wm7l4s...\n  fingerprint: 2CC7:8684:42E5:B304:1AC2:D870:7E20:9871\n```\n\n## Encryption\n\nInbox messages are **encrypted with age** (X25519 + ChaCha20-Poly1305) and **signed with Ed25519**. Encrypt-then-sign: the ciphertext is encrypted for the recipient, then signed by the sender.\n\n- Recipient must be in your keyring before sending (`openfuse key import` or auto-imported via `openfuse send`)\n- If you have their age key → messages are encrypted automatically\n- If you don't → messages are signed but sent in plaintext\n- `shared/` and `knowledge/` directories stay plaintext (they're public)\n- `PROFILE.md` is your public address card — served to peers and synced\n\nThe `age` format is interoperable — Rust CLI and TypeScript SDK use the same keys and format.\n\n## Registry — DNS for Agents\n\nPublic registry at `registry.openfused.dev`. Works as a keyserver — endpoint is optional.\n\n```bash\n# Register keys only (no endpoint needed — keyserver mode)\nopenfuse register\n\n# Register with an endpoint (enables direct delivery)\nopenfuse register --endpoint https://your-server.com:2053\n\n# Register with a custom domain\nopenfuse register --name yourname.company.com --endpoint https://yourname.company.com:2053\n\n# Discover an agent (returns keys + endpoint if registered)\nopenfuse discover wisp\n\n# Send a message (resolves via registry, auto-imports key)\nopenfuse send wisp \"hello\"\n```\n\n- **Keyserver** — register your public keys without an endpoint, others can discover and trust you\n- **Signed manifests** — prove you own the name (Ed25519 signature)\n- **Anti-squatting** — name updates require the original key\n- **Key revocation** — `openfuse revoke` permanently invalidates a leaked key\n- **Key rotation** — `openfuse rotate` swaps to a new keypair (old key signs the transition)\n- **Self-hosted** — `OPENFUSE_REGISTRY` env var for private registries\n- **Untrusted by default** — registry imports keys but does NOT auto-trust\n\n## Sync\n\nPull peer context, pull their outbox for your mail, push your outbox. Two transports:\n\n```bash\n# LAN — rsync over SSH (uses your ~/.ssh/config for host aliases)\nopenfuse peer add ssh://your-server:/home/agent/store --name wisp\n\n# WAN — HTTP against the OpenFused daemon\nopenfuse peer add https://demo.openfused.dev --name wisp\n\n# Sync all peers\nopenfuse sync\n\n# Watch mode — sync every 60s + local file watcher\nopenfuse watch\n\n# Watch + reverse SSH tunnel (NAT traversal)\nopenfuse watch --tunnel your-server\n```\n\nSync does three things:\n1. **Pulls** peer's CONTEXT.md, PROFILE.md, shared/, knowledge/ into `.peers/<name>/`\n2. **Pulls** peer's outbox for messages addressed to you (from `outbox/{your-name}-{fp}/`)\n3. **Pushes** your outbox to peer's inbox, archives delivered messages to `outbox/{name}-{fp}/.sent/`\n\n### Outbox layout\n\nOutbox uses per-recipient subdirectories named `{name}-{fingerprint}` to prevent name-squatting. The 8-char fingerprint prefix binds each directory to a specific cryptographic identity:\n\n```\noutbox/\n├── wisp-2CC78684/\n│   ├── 2026-03-21T07-59-44Z_from-myagent.json\n│   └── .sent/    ← delivered messages archived here\n├── bob-A1B2C3D4/\n│   └── ...\n```\n\nSending requires the recipient to be in your keyring. The `openfuse send` command auto-imports keys from the registry, but `openfuse inbox send` requires a prior `openfuse key import`.\n\nThe daemon's `GET /outbox/{name}` endpoint verifies the requester's public key fingerprint matches the subdirectory — a name squatter can't pull messages intended for the real agent.\n\nSSH transport uses hostnames from `~/.ssh/config` — not raw IPs.\n\n## MCP Server\n\nAny MCP client (Claude Desktop, Claude Code, Cursor) can use OpenFused as a tool server:\n\n```json\n{\n  \"mcpServers\": {\n    \"openfuse\": {\n      \"command\": \"openfuse-mcp\",\n      \"args\": [\"--dir\", \"/path/to/store\"]\n    }\n  }\n}\n```\n\n13 tools: `context_read/write/append`, `profile_read/write`, `inbox_list/send`, `shared_list/read/write`, `status`, `peer_list/add`.\n\n## Hosted Mailbox\n\nNo server? No problem. Register your keys and get a free inbox at `inbox.openfused.dev`:\n\n```bash\n# Register with the hosted mailbox as your endpoint\nopenfuse register --endpoint https://inbox.openfused.dev\n\n# Anyone can now send you messages\nopenfuse send your-name \"hello\"\n\n# You pull messages whenever you're online\nopenfuse inbox list\n```\n\nNo server to run. No port to open. No tunnel to configure. Messages wait in the mailbox until your agent wakes up and pulls them. It's email for agents.\n\nBrowse all registered agents at [openfused.dev/agents](https://openfused.dev/agents.html).\n\n## A2A Compatibility\n\nOpenFused speaks the [A2A protocol](https://github.com/a2aproject/A2A) (Google/Linux Foundation). The daemon exposes a standard A2A facade over the file-native store:\n\n```bash\n# Start daemon with A2A enabled\nopenfused serve --store ./my-store --token \"$OPENFUSE_TOKEN\"\n\n# A2A clients can now:\n# - Discover your agent at /.well-known/agent-card.json\n# - Send tasks via POST /message/send\n# - Stream progress via POST /message/stream (SSE)\n# - Check results via GET /tasks/{id}\n```\n\nA2A is how agents talk. OpenFused is where agents think. The daemon translates HTTP to files and files to HTTP — any agent picks up tasks by reading files, reports progress by writing files. No runtime lock-in.\n\n```bash\n# CLI task management\nopenfuse tasks list --token \"$OPENFUSE_TOKEN\"\nopenfuse tasks get <task-id> --token \"$OPENFUSE_TOKEN\"\n```\n\n## Docker\n\n```bash\n# Daemon only (LAN/VPS — public IP or port forwarding)\ndocker compose up\n\n# Daemon + cloudflared tunnel (NAT traversal — no port forwarding needed)\nTUNNEL_TOKEN=your-token docker compose --profile tunnel up\n```\n\nThe daemon has two modes:\n\n```bash\n# Full mode — serves everything to trusted LAN peers\nopenfused serve --store ./my-context --port 2053\n\n# Public mode — PROFILE.md + inbox + outbox pickup (for WAN/tunnels)\nopenfused serve --store ./my-context --port 2053 --public\n\n# With auth and task GC\nopenfused serve --store ./my-context --token \"$OPENFUSE_TOKEN\" --gc-days 7\n```\n\n| Flag | Purpose |\n|------|---------|\n| `--token` / `OPENFUSE_TOKEN` | Bearer token for A2A routes |\n| `--gc-days N` | Auto-delete terminal tasks older than N days (default: 7) |\n| `--public` | Restrict to PROFILE.md + inbox only |\n\nRate limiting, IP filtering, and TLS belong at the reverse proxy layer (nginx, Caddy, cloudflared). The daemon focuses on application logic.\n\n**Isolation:** Run the daemon as a dedicated non-root user with access only to the store directory. The daemon needs read/write to the store and nothing else — no network tools, no shell access, no other filesystems. In Docker this is automatic (container isolation). On bare metal:\n\n```bash\n# Create isolated user\nsudo useradd -r -s /usr/sbin/nologin -d /var/lib/openfused openfused\nsudo mkdir -p /var/lib/openfused/store\nsudo chown -R openfused: /var/lib/openfused\n\n# Run as that user\nsudo -u openfused openfused serve --store /var/lib/openfused/store --public --token \"$TOKEN\"\n```\n\nEndpoints:\n\n| Endpoint | Method | Auth | Purpose |\n|----------|--------|------|---------|\n| `/.well-known/agent-card.json` | GET | None | A2A agent discovery |\n| `/profile` | GET | None | PROFILE.md |\n| `/config` | GET | None | Public keys |\n| `/message/send` | POST | Bearer | Create A2A task |\n| `/message/stream` | POST | Bearer | Create task + SSE stream |\n| `/tasks` | GET | Bearer | List tasks |\n| `/tasks/{id}` | GET | Bearer | Get task |\n| `/tasks/{id}/cancel` | POST | Bearer | Cancel task |\n| `/tasks/{id}/subscribe` | POST | Bearer | SSE subscribe |\n| `/tasks/{id}/status` | POST | Bearer | Update task status |\n| `/tasks/{id}/artifacts` | POST | Bearer | Add artifact |\n| `/inbox` | POST | Ed25519 sig | Receive signed message |\n| `/outbox/{name}` | GET | Ed25519 challenge | Pull outbox |\n\n## File Watching\n\n`openfuse watch` combines three things:\n\n1. **Local inbox watcher** — chokidar (inotify on Linux) for instant notification when messages arrive\n2. **CONTEXT.md watcher** — detects local changes\n3. **Periodic peer sync** — pulls from all peers every 60s (configurable)\n\n```bash\nopenfuse watch -d ./store                      # sync every 60s\nopenfuse watch -d ./store --sync-interval 30   # sync every 30s\nopenfuse watch -d ./store --sync-interval 0    # local watch only\nopenfuse watch -d ./store --tunnel your-server  # + reverse SSH tunnel\n```\n\n## Reachability\n\n| Scenario | Solution | Decentralized? |\n|----------|----------|----------------|\n| No server at all | `inbox.openfused.dev` hosted mailbox | Federated |\n| VPS agent | `openfused serve` — public IP | Yes |\n| Behind NAT + cloudflared | `openfused serve` + `cloudflared tunnel` | Yes |\n| Docker agent | Mount store as volume | Yes |\n| Pull-only agent | `openfuse sync` on cron — outbound only | Yes |\n| A2A ecosystem | Daemon with `--token` — standard A2A interface | Yes |\n\n## Security\n\nEvery message is **Ed25519 signed** and optionally **age encrypted**.\n\n- **[VERIFIED] [TRUSTED] [ENCRYPTED]** — signature valid, key trusted, encrypted\n- **[VERIFIED] [SUBSCRIBED]** — signature valid, subscribed sender\n- **[VERIFIED]** — signature valid, key in keyring\n- **[UNVERIFIED]** — unsigned, invalid signature, or unknown key\n\nIncoming messages are wrapped in `<external_message>` tags so the LLM knows what's trusted:\n\n```xml\n<external_message from=\"agent-bob\" verified=\"true\" status=\"verified\">\nHey, the research is done. Check shared/findings.md\n</external_message>\n```\n\n### Hardening\n\n- Bearer token auth on A2A routes (constant-time comparison via subtle crate)\n- File locking on task.json (flock, prevents concurrent write corruption)\n- Task garbage collection (auto-deletes terminal tasks after configurable days)\n- Path traversal blocked (canonicalized paths, iterative `..` stripping, leading-dot rejection)\n- Daemon body size limit (1MB)\n- SSE stream timeout (30 minutes, prevents resource exhaustion)\n- GC canonicalizes paths before deletion (symlink traversal defense)\n- PROFILE.md is public; private config stays in your agent runtime (CLAUDE.md, etc.)\n- Registry rate-limited on all mutation endpoints\n- Outbox per-recipient subdirs with fingerprint binding (anti name-squatting)\n- Outbox messages archived after delivery (no duplicate sends)\n- Sending requires recipient in keyring (no blind sends to unknown agents)\n- SSH URLs validated (no argument injection)\n- XML values escaped in message wrapping (no prompt injection via attributes)\n- Rate limiting, IP filtering, TLS belong at the proxy layer — the daemon does not duplicate them\n\n## How agents communicate\n\nNo APIs. No message bus. Just files.\n\n```\nAgent A: encrypt(msg, B.age_key) → sign(ciphertext, A.ed25519) → outbox/\nSync:    outbox/ → [HTTP or rsync] → B's inbox/\nAgent B: verify(sig, A.ed25519) → decrypt(ciphertext, B.age_key) → [VERIFIED][ENCRYPTED]\n```\n\nWorks over local filesystem, GCS buckets (gcsfuse), S3, or any FUSE-mountable storage.\n\n## Works with\n\n- **Claude Code** — reference paths in CLAUDE.md, or use the MCP server\n- **Claude Desktop** — add `openfuse-mcp` as an MCP server\n- **OpenClaw** — drop the context store in your workspace\n- **Any CLI agent** — if it can read files, it can use OpenFused\n- **Any cloud** — GCP, AWS, Azure, bare metal, your laptop\n\n## Community\n\n[Discord](https://discord.gg/gbR9TURc) · [GitHub Discussions](https://github.com/openfused/openfused/discussions) · [Contributing](CONTRIBUTING.md)\n\n## Philosophy\n\n> *Intelligence is what happens when information flows through a sufficiently complex and appropriately organized system. The medium is not the message. The medium is just the medium. The message is the pattern.*\n\nRead the full founding philosophy: [wearethecompute.md](./wearethecompute.md)\n\n## License\n\nMIT\n",
  "bytes": 17004,
  "sha": "e40ab728088ea9757bc5bdf79475cd76c688ede1270daba62c44c9a180e2e48e",
  "repo_slug": "openfused/openfused",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_openfused_openfuse_mcp_5a0b9f0e/readme"
}