![\"Mayros\"](\"assets/mayros-readme.png\")
\n\n \n
\n AI agent framework · Coding CLI · Personal assistant
\n One platform. Your terminal, your channels, your devices.\n
\n ![\"CI](\"https://img.shields.io/github/actions/workflow/status/ApiliumCode/mayros/ci.yml?branch=main&style=for-the-badge\")
![\"npm](\"https://img.shields.io/npm/v/@apilium/mayros?style=for-the-badge&color=cb3837\")
![\"GitHub](\"https://img.shields.io/github/v/release/ApiliumCode/mayros?include_prereleases&style=for-the-badge\")
![\"Discord\"](\"https://img.shields.io/discord/1476351587105636404?label=Discord&logo=discord&logoColor=white&color=5865F2&style=for-the-badge\")
![\"MIT](\"https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge\"){kind=icon}
\n
\n ![\"npm](\"https://img.shields.io/npm/dm/@apilium/mayros?style=for-the-badge&label=downloads&color=brightgreen\")
![\"Node.js](\"https://img.shields.io/badge/node-%3E%3D22.12.0-339933?style=for-the-badge&logo=node.js&logoColor=white\"){kind=icon}
![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-strict-3178C6?style=for-the-badge&logo=typescript&logoColor=white\"){kind=icon}
![\"55](\"https://img.shields.io/badge/extensions-55-8B5CF6?style=for-the-badge\"){kind=icon}
![\"macOS](\"https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-999?style=for-the-badge\"){kind=icon}
![\"MCP](\"https://img.shields.io/badge/MCP-Compatible-6366F1?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0wIDE4Yy00LjQyIDAtOC0zLjU4LTgtOHMzLjU4LTggOC04IDggMy41OCA4IDgtMy41OCA4LTggOHoiLz48cGF0aCBkPSJNMTIgNmMtMy4zMSAwLTYgMi42OS02IDZzMi42OSA2IDYgNiA2LTIuNjkgNi02LTIuNjktNi02LTZ6Ii8+PC9zdmc+\"){kind=icon}
![\"Works](\"https://img.shields.io/badge/Works_with-Claude-D97706?style=for-the-badge&logo=anthropic&logoColor=white\"){kind=icon}
\n Product · Download · Docs · Getting Started · Vision · Discord\n
\n\n---\n\n**Mayros** is an open-source AI agent framework that runs on your own devices. It ships with an interactive **coding CLI** (`mayros code`), connects to **17+ messaging channels** (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Teams, and more), speaks and listens on **macOS/iOS/Android**, and has a **knowledge graph** that remembers everything across sessions. **Kaneru** — the multi-agent venture system — lets you build AI companies that learn, remember, and improve over time. All backed by a local-first Gateway and a 20-layer security architecture.\n\n> **55+ extensions · 12,400+ tests · 29 hooks · MCP server & client · Multi-model · Multi-agent · Kaneru ventures**\n\n```bash\nnpm install -g @apilium/mayros@latest\nmayros onboard\nmayros code # interactive coding CLI\n```\n\n---\n\n## Why Mayros?\n\n| | Mayros | Others |\n| ---------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------- |\n| 🧠 **Knowledge Graph** | AIngle Cortex — persistent memory across sessions, projects, and agents | Flat conversation history |\n| 🤖 **Multi-Agent** | Teams, workflows, mailbox, background tasks, git worktree isolation | Single agent |\n| 📱 **Multi-Channel** | 17 channels — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Teams, Matrix, WebChat, and more | Terminal only |\n| 🔒 **Security** | 20 layers — WASM sandbox, bash scanner, interactive permissions, namespace isolation, rate limiter | Basic sandboxing |\n| 🎙️ **Voice** | Always-on Voice Wake + Talk Mode on macOS, iOS, Android | None |\n| 🖥️ **IDE** | VSCode + JetBrains plugins with chat, plan, traces, KG | VSCode only |\n| 📊 **Observability** | Full trace system, decision graph, session fork/rewind | Basic logging |\n| 🔌 **Extensions** | 55+ plugin extensions, 29 hook types, MCP server + client (4 transports) | Limited plugins |\n| 🏢 **Kaneru** | AI ventures with missions, squads, Q-learning routing, decision audit, fuel control | No organizational layer |\n| 🗺️ **Plan Mode** | Cortex-backed semantic planning: explore → assert → approve → execute | Simple plan files |\n\n---\n\n## Install\n\nRuntime: **Node ≥ 22**. Works with npm, pnpm, or bun.\n\n```bash\nnpm install -g @apilium/mayros@latest\n# or: pnpm add -g @apilium/mayros@latest\n\nmayros onboard --install-daemon\n```\n\nThe wizard sets up the Gateway, workspace, channels, and skills. It installs the Gateway as a background daemon (launchd/systemd) so it stays running.\n\nThe installer automatically downloads [AIngle Cortex](https://github.com/ApiliumCode/aingle) (the semantic memory sidecar). No separate install needed.\n\nNew install? Start here: **[Getting Started](https://apilium.com/en/doc/mayros/start/getting-started)** · Upgrading? **[Updating guide](https://apilium.com/en/doc/mayros/install/updating)** (and run `mayros doctor`)\n\n### Update\n\n```bash\nmayros update # updates Mayros + Cortex automatically\n# or: npm install -g @apilium/mayros@latest\n```\n\n### Uninstall\n\n```bash\nmayros uninstall # interactive — choose what to remove\nmayros uninstall --all # remove everything (service, state, workspace, cortex)\nmayros uninstall --dry-run # preview without deleting\n```\n\nA detailed data loss warning is always shown before deletion — listing every category of data (knowledge graph, ventures, agent memory, decision history, etc.).\n\n### Desktop Installers\n\nZero-setup installers that bundle Node.js + AIngle Cortex — no prerequisites required.\n\n| Platform | Format | Download |\n| ------------------------- | -------------------- | ---------------------------------------------------------- |\n| **Windows** | `.exe` (NSIS) | [Releases](https://github.com/ApiliumCode/mayros/releases) |\n| **macOS (Apple Silicon)** | `.dmg` | [Releases](https://github.com/ApiliumCode/mayros/releases) |\n| **macOS (Intel)** | `.dmg` | [Releases](https://github.com/ApiliumCode/mayros/releases) |\n| **Linux (x64)** | `.AppImage` / `.deb` | [Releases](https://github.com/ApiliumCode/mayros/releases) |\n| **Linux (arm64)** | `.AppImage` / `.deb` | [Releases](https://github.com/ApiliumCode/mayros/releases) |\n\nEach installer includes Node.js portable + AIngle Cortex binary, runs `npm install` at install time, creates desktop shortcuts, and adds Mayros to the system PATH.\n\n---\n\n## Local Models\n\nRun models locally with automatic GPU detection and guided setup. Mayros detects your hardware and recommends compatible models.\n\n**Supported runtimes:**\n\n| Runtime | Use case |\n| -------------- | ----------------------------------------------- |\n| **Ollama** | Easiest setup — one command install |\n| **vLLM** | High-throughput serving with tensor parallelism |\n| **NVIDIA NIM** | Optimized containers for NVIDIA GPUs |\n\n**GPU detection:** NVIDIA (nvidia-smi), AMD/Intel (PowerShell on Windows, lspci on Linux), Apple Silicon (sysctl), Intel Mac (system_profiler), Raspberry Pi (BCM2 chipset).\n\n**50+ model catalog** segmented by 8 activities (coding, chat, reasoning, creative, analysis, multilingual, vision, agents) with VRAM-aware filtering — from CPU-only models (0 VRAM) to 80GB+ enterprise models.\n\n```bash\nmayros mamoru model detect # detect GPU and recommend models\nmayros mamoru model catalog # browse full catalog by activity\nmayros mamoru model install # guided installation\n```\n\nThe onboarding wizard in the web portal also includes GPU-aware model selection with compatibility indicators.\n\n---\n\n## Coding CLI\n\n`mayros code` is an interactive terminal UI for coding, conversation, and agent-driven workflows.\n\n\n ![\"Mayros](\"docs/assets/mayros-coding-cli-terminal-interface.png\")
\n
`. Public DMs require explicit opt-in.\n\n---\n\n## Knowledge Graph (AIngle Cortex)\n\nMayros remembers. Not just conversation history — semantic knowledge stored as RDF triples in [AIngle Cortex](https://github.com/ApiliumCode/aingle).\n\n**Three-tier memory:**\n\n1. **MAYROS.md** — flat-file persona and instructions, always loaded into the system prompt\n2. **AIngle Cortex** — RDF triple store (`subject → predicate → object`) scoped by namespace. Optional: falls back to file-based memory when unavailable\n3. **Ineru STM/LTM** — short-term and long-term memory with temporal recall\n\n**Built on top:**\n\n- **Code indexer** — scans your codebase → RDF triples in Cortex (incremental, only re-indexes changed files)\n- **Project memory** — persists conventions, findings, and architecture decisions across sessions\n- **Smart compaction** — extracts key information before context pruning\n- **Cross-session recall** — injects relevant knowledge from previous sessions into new prompts\n\n**Design principles:** namespace isolation (no cross-namespace reads), graceful degradation (Cortex is a sidecar, not an FFI binding), circuit breaker with exponential backoff.\n\nCLI: `mayros kg search|explore|query|stats|triples|namespaces|export|import`\n\n---\n\n## MCP Server\n\nMayros exposes its tools, resources, and prompts via the [Model Context Protocol](https://modelcontextprotocol.io). Any MCP client — Claude Desktop, Claude Code, VSCode, Cursor, JetBrains — can discover and use Mayros capabilities.\n\n### Connect with Claude Desktop\n\n```bash\n# 1. Install Mayros\nnpm install -g @apilium/mayros@latest\n\n# 2. Register with Claude Desktop (auto-detects paths, writes config)\nmayros mcp-setup --desktop\n\n# 3. Restart Claude Desktop — done\n# The tools icon appears in the chat input\n```\n\nThen in Claude Desktop, just talk naturally:\n\n- _\"Remember that our API uses JWT tokens with 24h expiry\"_ → stores in semantic memory\n- _\"What do you know about our authentication?\"_ → recalls from memory and knowledge graph\n- _\"Store in the graph: project:api depends_on express v5\"_ → creates an RDF triple\n- _\"What's the memory status?\"_ → shows STM/LTM/graph statistics\n\n### Connect with Claude Code\n\n```bash\n# From your terminal (not inside a Claude Code session)\nmayros mcp-setup\n# or manually:\nclaude mcp add mayros -- mayros serve --stdio\n```\n\n### Connect with other MCP clients\n\n```bash\n# Start the HTTP server\nmayros serve --http\n# → MCP endpoint: http://127.0.0.1:19100/mcp\n# → Legacy SSE: http://127.0.0.1:19100/sse\n# → Health check: http://127.0.0.1:19100/health\n```\n\nPoint any MCP client to `http://127.0.0.1:19100/mcp` (Streamable HTTP) or `http://127.0.0.1:19100/sse` (legacy SSE for older clients).\n\n### Bring persistent memory to any AI coding tool\n\nAI coding CLIs have no memory between sessions. Mayros + [AIngle Cortex](https://github.com/ApiliumCode/aingle) fill that gap: semantic knowledge graph, DAG audit trail, vector search, and ZK proofs — all local-first.\n\nAny MCP-compatible client gets instant access to 45+ tools via a single command:\n\n```bash\nclaude mcp add mayros -- mayros serve --stdio # Claude Code\n# Gemini CLI, GitHub Copilot — coming soon\n```\n\nBuilt on the open [Model Context Protocol](https://modelcontextprotocol.io) standard — no vendor lock-in.\n\n### Tools\n\n| Tool | Description |\n| ------------------------- | ------------------------------------------------------ |\n| `mayros_remember` | Store information in persistent semantic memory |\n| `mayros_recall` | Search memory by text, tags, or type |\n| `mayros_search` | Vector similarity search over memory (HNSW) |\n| `mayros_forget` | Delete a memory entry |\n| `mayros_memory_stats` | STM/LTM/HNSW/graph statistics |\n| `mayros_memory_conflicts` | Scan memory for contradictions and duplicates |\n| `mayros_memory_digest` | Summary of stored memories, categories, and DAG status |\n| `mayros_cortex_query` | Query the knowledge graph by subject/predicate/object |\n| `mayros_cortex_store` | Store RDF triples in the knowledge graph |\n| `mayros_budget` | Check token usage and budget status |\n| `mayros_policy_check` | Evaluate actions against governance policies |\n| `mayros_dag_tips` | Get the current DAG tip hashes (frontier) |\n| `mayros_dag_action` | Submit a new action to the DAG |\n| `mayros_dag_history` | Query action history for a subject or triple |\n| `mayros_dag_chain` | Trace the full chain of ancestors for an action |\n| `mayros_dag_stats` | DAG statistics (action count, tip count) |\n| `mayros_dag_prune` | Prune old DAG actions by policy |\n| `mayros_dag_time_travel` | View graph state at a specific DAG action |\n| `mayros_dag_diff` | Compare graph state between two DAG actions |\n| `mayros_dag_export` | Export DAG actions as JSON |\n| `mayros_dag_verify` | Verify Ed25519 signature of a DAG action |\n\n---\n\n## Intelligent Routing\n\nAdaptive routing that learns and improves over time.\n\n- **Eruberu** (Q-Learning model routing) — learns optimal provider/model per task type, budget level, and time slot\n- **Miteru** (task-to-agent routing) — learns which agent handles each task type best via EMA scoring\n- **Hayameru** (code transforms) — deterministic WASM transforms that bypass the LLM for simple edits (var→const, remove console, sort imports). 0 tokens, sub-millisecond\n\nCLI: `mayros routing status|strategy|reset`\n\n---\n\n## Multi-Agent Mesh\n\nAgents that work together. Mayros supports coordinated multi-agent workflows with shared knowledge.\n\n- **Team manager** — Cortex-backed lifecycle: create, assign roles, merge results, disband\n- **Workflow orchestrator** — built-in workflows (code-review, research, refactor) + custom definitions\n- **Kimeru consensus** — majority vote, weighted (EMA), LLM-arbitrated, Byzantine (PBFT with HMAC), Raft leader election\n- **Agent mailbox** — persistent inter-agent messaging (send/inbox/outbox/archive)\n- **Background task tracker** — long-running tasks with status and cancellation\n- **Git worktree isolation** — each agent works in its own worktree to avoid conflicts\n- **Session fork/rewind** — checkpoint-based exploration with rewind capability\n- **Kakeru bridge** — dual-platform coordination (Claude + Codex CLI) with file lock coordination\n\nCLI: `mayros workflow run|list` · `mayros dashboard team|summary|agent` · `mayros tasks list|status|cancel|summary` · `mayros mailbox list|read|send|archive|stats`\n\n---\n\n## Kaneru — AI Venture Management\n\nKaneru turns Mayros into a full AI venture platform. Create organizations of agents that learn, coordinate, and improve over time — all stored in Cortex, all DAG-auditable.\n\n### Kaneru Quick Start\n\n```bash\n# Install a pre-built venture template (security-audit, content-pipeline, devops-squad)\nmayros kaneru dojo install --template security-audit --name \"My Security Team\"\n\n# Or use the web portal Setup Wizard: open dashboard → Ventures → New Venture\nmayros dashboard\n```\n\n### Ventures & Missions\n\n```bash\nmayros kaneru venture create --name \"Acme\" --prefix ACM --directive \"Ship fast\" --fuel-limit 10000\nmayros kaneru mission create --venture --title \"Audit auth module\" --priority critical\nmayros kaneru mission claim --mission --agent scanner --run run-001\nmayros kaneru mission transition --mission --status review --run run-001\nmayros kaneru comment add --mission --author scanner --content \"SQL injection found\"\n```\n\n### Agents That Learn\n\nAgents build expertise profiles over time. Q-learning + EMA scoring routes missions to the best agent automatically.\n\n```bash\nmayros kaneru learn profile --agent scanner # see agent expertise\nmayros kaneru learn top --domain typescript --task-type security-scan # best agents for a task\nmayros kaneru route --mission \"Fix SQL injection\" --agents scanner,reviewer,fixer # smart routing\n```\n\n### Cost Analytics & Fuel Control\n\n```bash\nmayros kaneru fuel summary --venture # spend overview\nmayros kaneru fuel analytics --venture --period weekly # time-series + provider breakdown\nmayros kaneru fuel forecast --venture # burn rate + days until exhausted\n```\n\n### Decision Audit\n\n```bash\nmayros kaneru consensus --squad --question \"Ship or block?\"\nmayros kaneru decisions list --venture \nmayros kaneru decisions explain --decision # full reasoning with votes\n```\n\n### Distributed Ventures (P2P)\n\n```bash\nmayros kaneru discover --venture # auto-discover peers via mDNS\nmayros kaneru sync --venture # DAG-sync venture state with peers\n```\n\n### Web Portal\n\nThe portal at `http://localhost:18789` includes:\n\n- **Ventures tab** — venture table, mission kanban, chain of command tree, fuel bars\n- **Kaneru tab** — squads, Q-learning router, squad builder\n- **Canvas tab** — A2UI surfaces (overview, missions, chain, fuel) — interactive, venture-aware\n- **Setup Wizard** — 4-step guided venture creation (Venture → Agent → Mission → Launch)\n- **Command Bar** (Ctrl+/) — Spotlight-style overlay with venture context and voice input\n\n### MCP Tools (24)\n\nAny MCP client (Claude, Cursor, Cline) gets access to 24 Kaneru tools:\n\n| Tool | Purpose |\n| ---------------------------------------------- | --------------------------- |\n| `kaneru_venture_create/list` | Venture CRUD |\n| `kaneru_mission_create/claim/list/transition` | Mission lifecycle |\n| `kaneru_fuel_summary/analytics/forecast` | Cost control |\n| `kaneru_dojo_list/install` | Venture templates |\n| `kaneru_learn_profile/top` | Agent expertise |\n| `kaneru_decisions_list/explain` | Decision audit |\n| `kaneru_sync/terminal_exec` | P2P sync + remote execution |\n| `kaneru_squad_create/run/status` | Multi-agent squads |\n| `kaneru_delegate/consensus/route/fuse/mailbox` | Coordination |\n\nCLI: `mayros kaneru` — 18 subcommand groups with 40+ commands total\n\n---\n\n## Mamoru — Security Layer\n\nMamoru (守る, \"to protect\") adds enterprise-grade security to Mayros:\n\n- **Sandbox** — Landlock + seccomp probing for kernel-level agent isolation (Linux)\n- **Eruberu Proxy** — All inference calls routed through the gateway with audit logging\n- **Mamoru Gate** — Deny-by-default network egress with 12 presets and real-time approval\n- **Secrets Vault** — AES-256-GCM encrypted secrets with scrypt key derivation\n- **API Keys** — SHA-256 hashed agent keys with timing-safe validation\n- **Local Models** — GPU detection + guided Ollama/vLLM setup\n\nCLI: `mayros mamoru status|egress|proxy|keys|vault|model`\n\n---\n\n## IDE Plugins\n\nMayros lives inside your editor, connected via Gateway WebSocket.\n\n**VSCode** (`tools/vscode-extension/`):\n\n- Sidebar tree views: sessions, agents, skills\n- Webview panels: chat, plan mode, trace viewer, knowledge graph\n- Context menu actions and gutter markers\n\n**JetBrains** (`tools/jetbrains-plugin/`):\n\n- Unified tabbed panel with the same feature set\n- Protocol v3 compatibility\n\nBoth connect to `ws://127.0.0.1:18789`.\n\n---\n\n## Voice & Companion Apps\n\n- **[Voice Wake](https://apilium.com/en/doc/mayros/nodes/voicewake) + [Talk Mode](https://apilium.com/en/doc/mayros/nodes/talk)** — always-on speech for macOS/iOS/Android with ElevenLabs\n- **[Live Canvas](https://apilium.com/en/doc/mayros/platforms/mac/canvas)** — agent-driven visual workspace with [A2UI](https://apilium.com/en/doc/mayros/platforms/mac/canvas#canvas-a2ui)\n- **[macOS app](https://apilium.com/en/doc/mayros/platforms/macos)** — menu bar control, Voice Wake, Talk Mode overlay, WebChat, debug tools\n- **[iOS node](https://apilium.com/en/doc/mayros/platforms/ios)** — Canvas, Voice Wake, Talk Mode, camera, screen recording, Bonjour pairing\n- **[Android node](https://apilium.com/en/doc/mayros/platforms/android)** — Canvas, Talk Mode, camera, screen recording, optional SMS\n\n---\n\n## Extensions Ecosystem\n\n55 extensions loaded as plugins at startup:\n\n| Category | Extension | Purpose |\n| ------------- | ------------------------- | ------------------------------------------------------------------------- |\n| Skills | `semantic-skills` | QuickJS WASM sandbox, 6 semantic tools, skill marketplace |\n| Agents | `agent-mesh` | Teams, workflows, consensus (majority/weighted/Byzantine/Raft), mailbox |\n| Ventures | `kaneru` | Ventures, missions, projects, fuel, learning profiles, decision history |\n| Memory | `memory-semantic` | Cortex integration, rules engine, agent memory, contextual awareness |\n| Observability | `semantic-observability` | Traces, decision graph, session fork/rewind |\n| Indexer | `code-indexer` | Codebase scanning + RDF mapping (incremental) |\n| Security | `bash-sandbox` | Command parsing, domain checker, blocklist, audit log |\n| Governance | `osameru-governance` | Policy enforcement, HMAC audit trail, trust tiers |\n| Permissions | `interactive-permissions` | Runtime permission dialogs, intent classification, policy store |\n| Routing | `eruberu` | Q-Learning model routing, budget-driven fallback, task classification |\n| Transforms | `hayameru` | Deterministic code transforms that bypass LLM (0 tokens, sub-ms) |\n| Rate Limit | `tomeru-guard` | Sliding window rate limiter, loop breaker, velocity circuit breaker |\n| Hooks | `llm-hooks` | Markdown-defined hook evaluation with safe condition parser |\n| MCP Server | `mcp-server` | 21 tools exposed via MCP (memory, graph, DAG, budget, governance) |\n| MCP Client | `mcp-client` | Model Context Protocol client (stdio, SSE, WebSocket, HTTP) |\n| Economy | `token-economy` | Budget tracking, response cache, prompt cache optimization |\n| Bridge | `kakeru-bridge` | Dual-platform coordination (Claude + Codex CLI) |\n| Hub | `skill-hub` | Apilium Hub marketplace, Ed25519 signing, dependency audit |\n| IoT | `iot-bridge` | IoT node fleet management |\n| Channels | 17 plugins | Discord, Telegram, WhatsApp, Slack, Signal, iMessage, Teams, Matrix, etc. |\n\n---\n\n## Hooks System\n\n29 hook types across the assistant lifecycle:\n\n- **Lifecycle** — `before_prompt_build`, `after_response`, `before_compaction`, `agent_end`, etc.\n- **Security** — `permission_request` (modifying: allow/deny/ask), `config_change`\n- **Coordination** — `teammate_idle`, `task_completed`, `notification`\n- **HTTP webhooks** — POST delivery with HMAC-SHA256 signatures, retry + exponential backoff\n- **Async queue** — background execution with concurrency limits and dead-letter queue\n- **Markdown hooks** — place `.md` files in `~/.mayros/hooks/` for custom logic\n\n---\n\n## Security (20 layers)\n\nMayros takes security seriously. 20 layers of defense:\n\n| Layer | Description |\n| --------------------------- | --------------------------------------------------------------- |\n| QuickJS WASM Sandbox | Skills run in isolated WASM — no fs, net, process, eval |\n| Static Scanner | 16 rules + anti-evasion preprocessing |\n| Enrichment Sanitizer | Unicode normalization, injection detection, depth limits |\n| Bash Sandbox | Command parsing, domain blocklist, audit logging |\n| Interactive Permissions | Runtime dialogs, intent classification, policy store |\n| Namespace Isolation | All queries forced to `{ns}:` prefix — no cross-namespace reads |\n| Tool Allowlist | Intersection model — ALL active skills must allow a tool |\n| Rate Limiter | Sliding window per skill (default: 60 calls/min) |\n| Query/Write Limits | Per-skill caps on graph reads and writes |\n| Enrichment Timeout | 2s timeout prevents DoS via slow enrichment |\n| Hot-Reload Validation | Atomic swap, manifest validation, downgrade blocking |\n| Path Traversal Protection | Reject `..` + `isPathInside()` double-check |\n| Verify-then-Promote | Temp extract → verify hashes → atomic promote |\n| Circuit Breaker | 3-state (closed/open/half-open) + exponential backoff |\n| DM Pairing | Unknown senders get pairing code, not access |\n| Audit Logging | Skill name + operation tagged on all sandbox writes |\n| Docker Sandboxing | Per-session Docker containers for non-main sessions |\n| Governance (Osameru) | Policy compilation, enforcement gates, HMAC audit trail |\n| Rate Limit (Tomeru) | Sliding window, token bucket, loop breaking, velocity breaker |\n| Enterprise Managed Settings | Enforced config overrides with locked keys |\n\n---\n\n## Models\n\nMayros is multi-model. Bring any provider.\n\n- Models config + CLI: **[Models](https://apilium.com/en/doc/mayros/concepts/models)**\n- Auth profile rotation (OAuth vs API keys) + fallbacks: **[Model failover](https://apilium.com/en/doc/mayros/concepts/model-failover)**\n\nMinimal config:\n\n```json5\n{\n agent: {\n model: \"anthropic/claude-opus-4-6\",\n },\n}\n```\n\nFull reference: **[Configuration](https://apilium.com/en/doc/mayros/gateway/configuration)**\n\n---\n\n## Plan Mode\n\nCortex-backed semantic planning for complex multi-step tasks.\n\n- **Explore** — gather context from the codebase and Cortex graph\n- **Assert** — declare facts and constraints the plan must satisfy\n- **Approve** — review the plan before execution\n- **Execute** — run the approved plan with progress tracking\n\nCLI: `mayros plan start|explore|assert|show|approve|execute|done|list|status` · TUI: `/plan`\n\n---\n\n## Remote Gateway\n\nRun the Gateway on a small Linux instance. Clients connect over **Tailscale Serve/Funnel** or **SSH tunnels**, and device nodes (macOS/iOS/Android) handle local actions via `node.invoke`.\n\nTailscale modes: `off` (default) · `serve` (tailnet-only HTTPS) · `funnel` (public HTTPS, requires password auth).\n\nDetails: **[Remote access](https://apilium.com/en/doc/mayros/gateway/remote)** · **[Tailscale guide](https://apilium.com/en/doc/mayros/gateway/tailscale)** · **[Docker](https://apilium.com/en/doc/mayros/install/docker)**\n\n---\n\n## Chat Commands (Channels)\n\nSend these in WhatsApp/Telegram/Slack/Discord/Google Chat/Microsoft Teams/WebChat:\n\n| Command | Description |\n| ----------------------------- | ------------------------------------------------------ |\n| `/status` | Session status (model, tokens, cost) |\n| `/new`, `/reset` | Reset the session |\n| `/compact` | Compact session context |\n| `/think ` | Set thinking level (off/minimal/low/medium/high/xhigh) |\n| `/verbose on\\|off` | Toggle verbose mode |\n| `/usage off\\|tokens\\|full` | Per-response usage footer |\n| `/restart` | Restart the gateway (owner-only) |\n| `/activation mention\\|always` | Group activation (groups only) |\n\n---\n\n## From Source\n\n```bash\ngit clone https://github.com/ApiliumCode/mayros.git\ncd mayros\n\npnpm install\npnpm ui:build # auto-installs UI deps on first run\npnpm build\n\npnpm mayros onboard --install-daemon\n\n# Dev loop (auto-reload)\npnpm gateway:watch\n```\n\n`pnpm mayros ...` runs TypeScript directly (via `tsx`). `pnpm build` produces `dist/`.\n\n**Development channels:**\n\n- **stable** — tagged releases, npm dist-tag `latest`\n- **beta** — prerelease tags, npm dist-tag `beta`\n- **dev** — moving head of `main`, npm dist-tag `dev`\n\nSwitch: `mayros update --channel stable|beta|dev`. Details: **[Development channels](https://apilium.com/en/doc/mayros/install/development-channels)**\n\n---\n\n## Skills Hub\n\n[Skills Hub](https://hub.apilium.com) is a skill marketplace. With it enabled, the agent can search for skills automatically and pull in new ones.\n\n- Workspace root: `~/.mayros/workspace`\n- Skills: `~/.mayros/workspace/skills//SKILL.md`\n- Injected prompt files: `AGENTS.md`, `SOUL.md`, `TOOLS.md`\n\n---\n\n## Channel Setup\n\n\nWhatsApp
\n\n- Link the device: `pnpm mayros channels login` (stores creds in `~/.mayros/credentials`)\n- Allowlist: `channels.whatsapp.allowFrom`\n- Groups: `channels.whatsapp.groups` (include `\"*\"` to allow all)\n\n[Full guide →](https://apilium.com/en/doc/mayros/channels/whatsapp)\n\n\n\n\nTelegram
\n\nSet `TELEGRAM_BOT_TOKEN` or `channels.telegram.botToken`:\n\n```json5\n{ channels: { telegram: { botToken: \"123456:ABCDEF\" } } }\n```\n\n[Full guide →](https://apilium.com/en/doc/mayros/channels/telegram)\n\n\n\n\nSlack
\n\nSet `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` (or config equivalents).\n\n[Full guide →](https://apilium.com/en/doc/mayros/channels/slack)\n\n\n\n\nDiscord
\n\nSet `DISCORD_BOT_TOKEN` or `channels.discord.token`:\n\n```json5\n{ channels: { discord: { token: \"1234abcd\" } } }\n```\n\n[Full guide →](https://apilium.com/en/doc/mayros/channels/discord)\n\n\n\n\nSignal · BlueBubbles · iMessage · Teams · Matrix · Zalo · WebChat
\n\n- **Signal** — requires `signal-cli` + config section\n- **BlueBubbles** (recommended iMessage) — `channels.bluebubbles.serverUrl` + `password` + webhook\n- **iMessage** (legacy) — macOS-only via `imsg`\n- **Microsoft Teams** — Bot Framework app + `msteams` config\n- **Matrix** — `matrix-js-sdk` extension\n- **Zalo / Zalo Personal** — extension channels\n- **WebChat** — uses Gateway WebSocket directly\n\n[Channel docs →](https://apilium.com/en/doc/mayros/channels)\n\n\n\n---\n\n## Documentation\n\n**Start here:**\n\n- [Getting started](https://apilium.com/en/doc/mayros/start/getting-started) — first-time setup\n- [Architecture](https://apilium.com/en/doc/mayros/concepts/architecture) — gateway + protocol model\n- [Configuration](https://apilium.com/en/doc/mayros/gateway/configuration) — every key + examples\n- [Security](https://apilium.com/en/doc/mayros/gateway/security) — security model and guidance\n\n**Platform guides:**\n\n[macOS](https://apilium.com/en/doc/mayros/platforms/macos) · [iOS](https://apilium.com/en/doc/mayros/platforms/ios) · [Android](https://apilium.com/en/doc/mayros/platforms/android) · [Linux](https://apilium.com/en/doc/mayros/platforms/linux) · [Windows (WSL2)](https://apilium.com/en/doc/mayros/platforms/windows)\n\n**Operations:**\n\n[Gateway runbook](https://apilium.com/en/doc/mayros/gateway) · [Docker](https://apilium.com/en/doc/mayros/install/docker) · [Health checks](https://apilium.com/en/doc/mayros/gateway/health) · [Doctor](https://apilium.com/en/doc/mayros/gateway/doctor) · [Logging](https://apilium.com/en/doc/mayros/logging) · [Troubleshooting](https://apilium.com/en/doc/mayros/channels/troubleshooting)\n\n**Deep dives:**\n\n[Agent loop](https://apilium.com/en/doc/mayros/concepts/agent-loop) · [Sessions](https://apilium.com/en/doc/mayros/concepts/session) · [Models](https://apilium.com/en/doc/mayros/concepts/models) · [Presence](https://apilium.com/en/doc/mayros/concepts/presence) · [Streaming](https://apilium.com/en/doc/mayros/concepts/streaming) · [Skills](https://apilium.com/en/doc/mayros/tools/skills) · [Browser](https://apilium.com/en/doc/mayros/tools/browser) · [Canvas](https://apilium.com/en/doc/mayros/platforms/mac/canvas) · [Nodes](https://apilium.com/en/doc/mayros/nodes) · [Cron](https://apilium.com/en/doc/mayros/automation/cron-jobs) · [Webhooks](https://apilium.com/en/doc/mayros/automation/webhook) · [Gmail Pub/Sub](https://apilium.com/en/doc/mayros/automation/gmail-pubsub)\n\n**Advanced:**\n\n[Discovery + transports](https://apilium.com/en/doc/mayros/gateway/discovery) · [Bonjour/mDNS](https://apilium.com/en/doc/mayros/gateway/bonjour) · [Gateway pairing](https://apilium.com/en/doc/mayros/gateway/pairing) · [Tailscale](https://apilium.com/en/doc/mayros/gateway/tailscale) · [Remote gateway](https://apilium.com/en/doc/mayros/gateway/remote) · [Control UI](https://apilium.com/en/doc/mayros/web/control-ui) · [RPC adapters](https://apilium.com/en/doc/mayros/reference/rpc) · [TypeBox schemas](https://apilium.com/en/doc/mayros/concepts/typebox)\n\n**Templates:**\n\n[AGENTS](https://apilium.com/en/doc/mayros/reference/templates/AGENTS) · [BOOTSTRAP](https://apilium.com/en/doc/mayros/reference/templates/BOOTSTRAP) · [IDENTITY](https://apilium.com/en/doc/mayros/reference/templates/IDENTITY) · [TOOLS](https://apilium.com/en/doc/mayros/reference/templates/TOOLS) · [USER](https://apilium.com/en/doc/mayros/reference/templates/USER) · [Default AGENTS](https://apilium.com/en/doc/mayros/reference/AGENTS.default) · [Skills config](https://apilium.com/en/doc/mayros/tools/skills-config)\n\n---\n\n## Community\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, maintainers, and how to submit PRs.\nAI/vibe-coded PRs welcome! 🤖\n\nSpecial thanks to [Mario Zechner](https://mariozechner.at/) for his support and for\n[pi-mono](https://github.com/badlogic/pi-mono).\n","readmeFilename":"README.md"}