⚡🛡️ Mayros

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. All backed by a local-first Gateway and an 18-layer security architecture.

55 extensions · 9,200+ tests · 29 hooks · MCP support · Multi-model · Multi-agent

npm install -g @apilium/mayros@latest
mayros onboard
mayros code   # interactive coding CLI

Why Mayros?

| | Mayros | Others | | ---------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------- | | 🧠 Knowledge Graph | AIngle Cortex — persistent memory across sessions, projects, and agents | Flat conversation history | | 🤖 Multi-Agent | Teams, workflows, mailbox, background tasks, git worktree isolation | Single agent | | 📱 Multi-Channel | 17 channels — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Teams, Matrix, WebChat, and more | Terminal only | | 🔒 Security | 18 layers — WASM sandbox, bash scanner, interactive permissions, namespace isolation, rate limiter | Basic sandboxing | | 🎙️ Voice | Always-on Voice Wake + Talk Mode on macOS, iOS, Android | None | | 🖥️ IDE | VSCode + JetBrains plugins with chat, plan, traces, KG | VSCode only | | 📊 Observability | Full trace system, decision graph, session fork/rewind | Basic logging | | 🔌 Extensions | 55 plugin extensions, 29 hook types, MCP client (4 transports) | Limited plugins | | 🗺️ Plan Mode | Cortex-backed semantic planning: explore → assert → approve → execute | Simple plan files |

Install

Runtime: Node ≥ 22. Works with npm, pnpm, or bun.

npm install -g @apilium/mayros@latest
# or: pnpm add -g @apilium/mayros@latest

mayros onboard --install-daemon

The wizard sets up the Gateway, workspace, channels, and skills. It installs the Gateway as a background daemon (launchd/systemd) so it stays running.

New install? Start here: Getting Started · Upgrading? Updating guide (and run mayros doctor)

Coding CLI

mayros code is an interactive terminal UI for coding, conversation, and agent-driven workflows.

mayros code                    # interactive TUI session
mayros tui                     # alias
mayros -p "refactor auth flow" # headless mode (non-interactive)

Features:

• 🎨 3 themes (dark, light, high-contrast) — /theme
• 📝 3 output styles (standard, explanatory, learning) — /style
• ⌨️ Vim mode with motions, operators, undo — /vim
• 📋 Ctrl+V image paste from clipboard
• 📊 /diff inline diff viewer · /context token usage chart
• 🗺️ /plan semantic plan mode (Cortex-backed)
• 📎 /copy to clipboard · /export [file] to disk
• 🔀 /model switch models · /think set thinking level · /fast toggle fast mode

Slash commands (30+):

| Command | Description | Command | Description | | ---------------- | ----------------- | ---------------- | -------------------- | | /help | List all commands | /plan | Semantic plan mode | | /new | Reset session | /diff | Show pending changes | | /compact | Compact context | /context | Token usage chart | | /think <level> | Set thinking | /theme | Cycle themes | | /model <name> | Switch model | /vim | Toggle vim mode | | /permission | Permission mode | /copy | Copy last response | | /fast | Fast mode | /export [file] | Export session |

Markdown-driven extensibility:

• Custom agents: ~/.mayros/agents/*.md — define persona, tools, and behavior in markdown
• Custom commands: ~/.mayros/commands/*.md — define slash commands as markdown templates

Quick Start

# 1. Install and onboard
mayros onboard --install-daemon

# 2. Start the Gateway
mayros gateway --port 18789 --verbose

# 3. Code interactively
mayros code

# 4. Or use the agent directly
mayros agent --message "Ship checklist" --thinking high

# 5. Or send a message to any channel
mayros message send --to +1234567890 --message "Hello from Mayros"

Full beginner guide: Getting started

Architecture

  WhatsApp · Telegram · Slack · Discord · Signal · iMessage · Teams · Matrix · WebChat
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │          ⚡ Gateway             │
                    │     (local control plane)      │
                    │     ws://127.0.0.1:18789       │
                    └──────────────┬────────────────┘
                                   │
          ┌────────────┬───────────┼───────────┬────────────┐
          │            │           │           │            │
     mayros code   VSCode /   Pi Agent    macOS App    iOS/Android
      (TUI)       JetBrains   (RPC)      (menu bar)     Nodes

The Gateway is the single control plane — every client, channel, tool, and event connects through it.

Multi-Channel Inbox

Mayros connects to the channels you already use. One assistant, everywhere.

| Channel | Transport | Channel | Transport | | -------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | WhatsApp | Baileys | Microsoft Teams | Bot Framework | | Telegram | grammY | Matrix | matrix-js-sdk | | Slack | Bolt | BlueBubbles | iMessage (recommended) | | Discord | discord.js | iMessage | Legacy macOS | | Google Chat | Chat API | Zalo / Personal | Extension | | Signal | signal-cli | WebChat | Gateway WS |

Security defaults: DM pairing — unknown senders get a pairing code. You approve with mayros pairing approve <channel> <code>. Public DMs require explicit opt-in.

Knowledge Graph (AIngle Cortex)

Mayros remembers. Not just conversation history — semantic knowledge stored as RDF triples in AIngle Cortex.

Three-tier memory:

1. MAYROS.md — flat-file persona and instructions, always loaded into the system prompt
2. AIngle Cortex — RDF triple store (subject → predicate → object) scoped by namespace. Optional: falls back to file-based memory when unavailable
3. Ineru STM/LTM — short-term and long-term memory with temporal recall

Built on top:

• Code indexer — scans your codebase → RDF triples in Cortex (incremental, only re-indexes changed files)
• Project memory — persists conventions, findings, and architecture decisions across sessions
• Smart compaction — extracts key information before context pruning
• Cross-session recall — injects relevant knowledge from previous sessions into new prompts

Design principles: namespace isolation (no cross-namespace reads), graceful degradation (Cortex is a sidecar, not an FFI binding), circuit breaker with exponential backoff.

CLI: mayros kg search|explore|query|stats|triples|namespaces|export|import

Multi-Agent Mesh

Agents that work together. Mayros supports coordinated multi-agent workflows with shared knowledge.

• Team manager — Cortex-backed lifecycle: create, assign roles, merge results, disband
• Workflow orchestrator — built-in workflows (code-review, research, refactor) + custom definitions
• Agent mailbox — persistent inter-agent messaging (send/inbox/outbox/archive)
• Background task tracker — long-running tasks with status and cancellation
• Git worktree isolation — each agent works in its own worktree to avoid conflicts
• Session fork/rewind — checkpoint-based exploration with rewind capability

CLI: mayros workflow run|list · mayros dashboard team|summary|agent · mayros tasks list|status|cancel|summary · mayros mailbox list|read|send|archive|stats

IDE Plugins

Mayros lives inside your editor, connected via Gateway WebSocket.

VSCode (tools/vscode-extension/):

• Sidebar tree views: sessions, agents, skills
• Webview panels: chat, plan mode, trace viewer, knowledge graph
• Context menu actions and gutter markers

JetBrains (tools/jetbrains-plugin/):

• Unified tabbed panel with the same feature set
• Protocol v3 compatibility

Both connect to ws://127.0.0.1:18789.

Voice & Companion Apps

• Voice Wake + Talk Mode — always-on speech for macOS/iOS/Android with ElevenLabs
• Live Canvas — agent-driven visual workspace with A2UI
• macOS app — menu bar control, Voice Wake, Talk Mode overlay, WebChat, debug tools
• iOS node — Canvas, Voice Wake, Talk Mode, camera, screen recording, Bonjour pairing
• Android node — Canvas, Talk Mode, camera, screen recording, optional SMS

Extensions Ecosystem

55 extensions loaded as plugins at startup:

| Category | Extension | Purpose | | ------------- | ------------------------- | ------------------------------------------------------------------------- | | Skills | semantic-skills | QuickJS WASM sandbox, 6 semantic tools, skill marketplace | | Agents | agent-mesh | Teams, workflows, delegation, mailbox, background tasks | | Memory | memory-semantic | Cortex integration, rules engine, agent memory, contextual awareness | | Observability | semantic-observability | Traces, decision graph, session fork/rewind | | Indexer | code-indexer | Codebase scanning + RDF mapping (incremental) | | Security | bash-sandbox | Command parsing, domain checker, blocklist, audit log | | Permissions | interactive-permissions | Runtime permission dialogs, intent classification, policy store | | Hooks | llm-hooks | Markdown-defined hook evaluation with safe condition parser | | MCP | mcp-client | Model Context Protocol client (stdio, SSE, WebSocket, HTTP) | | Economy | token-economy | Budget tracking, prompt cache optimization | | Hub | skill-hub | Apilium Hub marketplace, Ed25519 signing, dependency audit | | IoT | iot-bridge | IoT node fleet management | | Channels | 17 plugins | Discord, Telegram, WhatsApp, Slack, Signal, iMessage, Teams, Matrix, etc. |

Hooks System

29 hook types across the assistant lifecycle:

• Lifecycle — before_prompt_build, after_response, before_compaction, agent_end, etc.
• Security — permission_request (modifying: allow/deny/ask), config_change
• Coordination — teammate_idle, task_completed, notification
• HTTP webhooks — POST delivery with HMAC-SHA256 signatures, retry + exponential backoff
• Async queue — background execution with concurrency limits and dead-letter queue
• Markdown hooks — place .md files in ~/.mayros/hooks/ for custom logic

Security (18 layers)

Mayros takes security seriously. 18 layers of defense:

| Layer | Description | | --------------------------- | --------------------------------------------------------------- | | QuickJS WASM Sandbox | Skills run in isolated WASM — no fs, net, process, eval | | Static Scanner | 16 rules + anti-evasion preprocessing | | Enrichment Sanitizer | Unicode normalization, injection detection, depth limits | | Bash Sandbox | Command parsing, domain blocklist, audit logging | | Interactive Permissions | Runtime dialogs, intent classification, policy store | | Namespace Isolation | All queries forced to {ns}: prefix — no cross-namespace reads | | Tool Allowlist | Intersection model — ALL active skills must allow a tool | | Rate Limiter | Sliding window per skill (default: 60 calls/min) | | Query/Write Limits | Per-skill caps on graph reads and writes | | Enrichment Timeout | 2s timeout prevents DoS via slow enrichment | | Hot-Reload Validation | Atomic swap, manifest validation, downgrade blocking | | Path Traversal Protection | Reject .. + isPathInside() double-check | | Verify-then-Promote | Temp extract → verify hashes → atomic promote | | Circuit Breaker | 3-state (closed/open/half-open) + exponential backoff | | DM Pairing | Unknown senders get pairing code, not access | | Audit Logging | Skill name + operation tagged on all sandbox writes | | Docker Sandboxing | Per-session Docker containers for non-main sessions | | Enterprise Managed Settings | Enforced config overrides with locked keys |

Models

Mayros is multi-model. Bring any provider.

• Models config + CLI: Models
• Auth profile rotation (OAuth vs API keys) + fallbacks: Model failover

Minimal config:

{
  agent: {
    model: "anthropic/claude-opus-4-6",
  },
}

Full reference: Configuration

Plan Mode

Cortex-backed semantic planning for complex multi-step tasks.

• Explore — gather context from the codebase and Cortex graph
• Assert — declare facts and constraints the plan must satisfy
• Approve — review the plan before execution
• Execute — run the approved plan with progress tracking

CLI: mayros plan start|explore|assert|show|approve|execute|done|list|status · TUI: /plan

Remote Gateway

Run 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.

Tailscale modes: off (default) · serve (tailnet-only HTTPS) · funnel (public HTTPS, requires password auth).

Details: Remote access · Tailscale guide · Docker

Chat Commands (Channels)

Send these in WhatsApp/Telegram/Slack/Discord/Google Chat/Microsoft Teams/WebChat:

| Command | Description | | ----------------------------- | ------------------------------------------------------ | | /status | Session status (model, tokens, cost) | | /new, /reset | Reset the session | | /compact | Compact session context | | /think <level> | Set thinking level (off/minimal/low/medium/high/xhigh) | | /verbose on\|off | Toggle verbose mode | | /usage off\|tokens\|full | Per-response usage footer | | /restart | Restart the gateway (owner-only) | | /activation mention\|always | Group activation (groups only) |

From Source

git clone https://github.com/ApiliumCode/mayros.git
cd mayros

pnpm install
pnpm ui:build   # auto-installs UI deps on first run
pnpm build

pnpm mayros onboard --install-daemon

# Dev loop (auto-reload)
pnpm gateway:watch

pnpm mayros ... runs TypeScript directly (via tsx). pnpm build produces dist/.

Development channels:

• stable — tagged releases, npm dist-tag latest
• beta — prerelease tags, npm dist-tag beta
• dev — moving head of main, npm dist-tag dev

Switch: mayros update --channel stable|beta|dev. Details: Development channels

Skills Hub

Skills Hub is a skill marketplace. With it enabled, the agent can search for skills automatically and pull in new ones.

• Workspace root: ~/.mayros/workspace
• Skills: ~/.mayros/workspace/skills/<skill>/SKILL.md
• Injected prompt files: AGENTS.md, SOUL.md, TOOLS.md

Channel Setup

• Link the device: pnpm mayros channels login (stores creds in ~/.mayros/credentials)
• Allowlist: channels.whatsapp.allowFrom
• Groups: channels.whatsapp.groups (include "*" to allow all)

Full guide →

Set TELEGRAM_BOT_TOKEN or channels.telegram.botToken:

{ channels: { telegram: { botToken: "123456:ABCDEF" } } }

Full guide →

Set SLACK_BOT_TOKEN + SLACK_APP_TOKEN (or config equivalents).

Full guide →

Set DISCORD_BOT_TOKEN or channels.discord.token:

{ channels: { discord: { token: "1234abcd" } } }

Full guide →

• Signal — requires signal-cli + config section
• BlueBubbles (recommended iMessage) — channels.bluebubbles.serverUrl + password + webhook
• iMessage (legacy) — macOS-only via imsg
• Microsoft Teams — Bot Framework app + msteams config
• Matrix — matrix-js-sdk extension
• Zalo / Zalo Personal — extension channels
• WebChat — uses Gateway WebSocket directly

Channel docs →

Documentation

Start here:

• Getting started — first-time setup
• Architecture — gateway + protocol model
• Configuration — every key + examples
• Security — security model and guidance

Platform guides:

macOS · iOS · Android · Linux · Windows (WSL2)

Operations:

Gateway runbook · Docker · Health checks · Doctor · Logging · Troubleshooting

Deep dives:

Agent loop · Sessions · Models · Presence · Streaming · Skills · Browser · Canvas · Nodes · Cron · Webhooks · Gmail Pub/Sub

Advanced:

Discovery + transports · Bonjour/mDNS · Gateway pairing · Tailscale · Remote gateway · Control UI · RPC adapters · TypeBox schemas

Templates:

AGENTS · BOOTSTRAP · IDENTITY · TOOLS · USER · Default AGENTS · Skills config

Community

See CONTRIBUTING.md for guidelines, maintainers, and how to submit PRs. AI/vibe-coded PRs welcome! 🤖

Special thanks to Mario Zechner for his support and for pi-mono.