\n\n# Symi\n\n### A Multi-Channel AI Agent Gateway with Autonomous Behavioral Intelligence\n\n[]()\n[]()\n[]()\n[]()\n\n_The architecture behind truly autonomous AI agents — decoded, rebuilt, and deployed at scale_\n\n**Created By: Jerome Naidoo**\n\n[Overview](#overview) • [Architecture](#architecture) • [Key Features](#key-features) • [Installation](#installation) • [Usage](#usage) • [Documentation](#documentation)\n\n
\n\n---\n\n## Overview\n\nThe AI agent landscape is flooded with wrappers, prompt chains, and thin orchestration layers that call themselves \"agents.\" They respond to messages. They don't _behave_. They don't persist. They don't reason across channels, sessions, and time.\n\n**Symi** is the result of reverse-engineering what makes an AI agent _actually autonomous_ — not in the marketing sense, but in the architectural sense. The secrets of agent behavior come down to three things most projects get wrong:\n\n- **Persistent identity across channels** — the agent doesn't restart when you switch from WhatsApp to Slack\n- **Session-aware reasoning** — context isn't just a sliding window; it's a managed, routed, multi-tenant state machine\n- **Gateway-first control** — the agent is a service, not a script; it runs as a daemon with a real control plane\n\nThis is the system that turns a language model into something that actually _behaves_ like an assistant — always on, always reachable, across every channel you use.\n\n---\n\n## The Problem with Current Approaches\n\nMost \"AI agent\" frameworks are glorified chat loops:\n\n| Problem | Description |\n| --------------------- | ------------------------------------------------------------------------------ |\n| **No Persistence** | Agent state dies when the script exits — no memory, no continuity |\n| **Single Channel** | Locked to one interface (web chat, CLI, or API) with no cross-channel identity |\n| **No Session Model** | Every conversation is isolated; the agent can't reason across interactions |\n| **No Control Plane** | No way to monitor, route, configure, or manage the agent as a running service |\n| **No Security Model** | Inbound messages from messaging platforms are treated as trusted input |\n\nSymi eliminates these by treating the AI agent as a **production service** with a WebSocket control plane, multi-tenant session routing, and first-class channel adapters.\n\n---\n\n## Architecture\n\nSymi operates as a **local-first Gateway** that bridges messaging channels to AI model providers through a managed agent runtime:\n\n```\nChannels (WhatsApp / Telegram / Slack / Signal / iMessage / Teams / Matrix / WebChat / ...)\n │\n ▼\n┌───────────────────────────────────┐\n│ Gateway │\n│ (WebSocket Control Plane) │\n│ ws://127.0.0.1:18789 │\n├───────────────────────────────────┤\n│ │\n│ ┌───────────┐ ┌───────────┐ │\n│ │ Channel │ │ Session │ │\n│ │ Adapters │ │ Router │ │\n│ │ │ │ │ │\n│ │ WhatsApp │ │ DM → main │ │\n│ │ Telegram │ │ Group → N │ │\n│ │ Slack │ │ Isolation │ │\n│ │ Signal │ │ Pruning │ │\n│ │ iMessage │ │ Compaction │ │\n│ │ Teams │ │ │ │\n│ │ Matrix │ │ │ │\n│ │ WebChat │ │ │ │\n│ └───────────┘ └───────────┘ │\n│ │\n│ ┌───────────┐ ┌───────────┐ │\n│ │ Agent │ │ Tools │ │\n│ │ Runtime │ │ + Skills │ │\n│ │ │ │ │ │\n│ │ Multi-model│ │ Browser │ │\n│ │ Failover │ │ Canvas │ │\n│ │ Streaming │ │ Cron │ │\n│ │ Thinking │ │ Nodes │ │\n│ │ Memory │ │ Webhooks │ │\n│ └───────────┘ └───────────┘ │\n│ │\n├───────────────────────────────────┤\n│ Companion Apps │\n│ macOS • iOS • Android • CLI │\n└───────────────────────────────────┘\n```\n\n---\n\n## Key Features\n\n### Multi-Channel Agent Inbox\n\n- **15+ channels**: WhatsApp, Telegram, Slack, Google Chat, Signal, iMessage (BlueBubbles), Microsoft Teams, Matrix, Zalo, WebChat, macOS, iOS, Android\n- **Unified identity**: Same agent, same memory, same personality across all channels\n- **Per-channel routing**: DM pairing, group isolation, allowlists, activation modes\n\n### Session-Aware Intelligence\n\n- **Multi-tenant sessions**: Each conversation gets its own managed session with isolated context\n- **Session pruning and compaction**: Automatic context management that prevents token exhaustion\n- **Agent-to-agent coordination**: Sessions can message each other via `sessions_send`\n- **Thinking levels**: Configurable reasoning depth (off through xhigh)\n\n### 50+ Model Providers\n\n- **First-class support**: OpenAI, Anthropic, Google Gemini, xAI/Grok, Z.AI, and more\n- **Model failover**: Automatic fallback chains across providers\n- **OAuth + API key auth**: Encrypted credential profiles with rotation\n- **Custom endpoints**: Any OpenAI-compatible or Anthropic-compatible API\n\n### Gateway Control Plane\n\n- **WebSocket protocol**: Real-time control for all clients, tools, and events\n- **Daemon mode**: Runs as a system service (launchd/systemd) — survives reboots\n- **Health monitoring**: `symi doctor` validates config, auth, connectivity, sandbox, and daemon state\n- **Tailscale integration**: Serve (tailnet-only) or Funnel (public) with zero port forwarding\n\n### First-Class Tool System\n\n- **Browser control**: Dedicated Chrome/Chromium with CDP, snapshots, and actions\n- **Live Canvas**: Agent-driven visual workspace with A2UI protocol\n- **Device nodes**: Camera, screen recording, location, notifications via iOS/Android/macOS\n- **Cron + webhooks + Gmail Pub/Sub**: Event-driven automation\n\n### Autonomous Managed Tasks (Layer 2)\n\n- **Detached execution**: Large builds run in a supervised worker with an isolated workspace — the chat stays usable and tasks survive gateway restarts\n- **Verified before done**: Acceptance criteria are derived and scored; viewable builds must serve a real page; weak evidence is labeled, never over-claimed\n- **Honest failure**: Real-world gates (signups, CAPTCHAs) stop in seconds with manual steps; unverified results park for your accept/revise/reject decision — never a silent timeout\n- **Grounded code reviews**: Review tasks read the real source they are pointed at (`--target`) and deliver a credited review document\n- **Full control from every surface**: status, steer, answer, rerun, force-clear from chat, CLI, and the Glass UI — with a durable, replayable event log per task\n\n### Security by Default\n\n- **DM pairing**: Unknown senders get a pairing code; the agent ignores them until approved\n- **Sandbox mode**: Non-main sessions run in per-session Docker containers\n- **Tool allowlists/denylists**: Fine-grained control over what the agent can execute\n- **Prompt injection awareness**: Inbound DMs are treated as untrusted input\n\n---\n\n## What Makes This Different\n\n\n\n| Capability | \nTypical AI Agent Frameworks | \nSymi | \n
\n\n| Persistence | \nScript-level; dies on exit | \nDaemon with managed sessions | \n
\n\n| Channels | \nSingle (web/CLI) | \n16+ with unified identity | \n
\n\n| Control Plane | \nNone | \nWebSocket gateway with health, config, presence | \n
\n\n| Model Support | \n1-3 providers | \n50+ with failover chains | \n
\n\n| Security | \nTrust all input | \nDM pairing, sandbox, allowlists | \n
\n\n| Device Integration | \nNone | \nmacOS/iOS/Android nodes (camera, screen, voice) | \n
\n\n| Deployment | \nManual process management | \nOne-command daemon install with doctor | \n
\n
\n\n---\n\n## Installation\n\n### One-Line Install (Recommended)\n\n```bash\n# macOS / Linux / WSL\ncurl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash\n```\n\n```powershell\n# Windows (PowerShell)\niwr -useb https://jaysteelmind.github.io/getsymi/install.ps1 | iex\n```\n\nThe installer handles Node.js 22+, Git, and symi installation, then launches the onboarding wizard.\n\n### Manual Install\n\n```bash\nnpm install -g @symerian/symi@latest\nsymi onboard --install-daemon\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/symi/symi.git\ncd symi\npnpm install\npnpm ui:build\npnpm build\npnpm symi onboard --install-daemon\n```\n\n### Requirements\n\n- Node.js 22+\n- macOS, Linux, or Windows (WSL2 recommended)\n- pnpm only needed for building from source\n\n---\n\n## Usage\n\n### Onboarding Wizard\n\n```bash\nsymi onboard --install-daemon\n```\n\nThe wizard walks you through:\n\n1. Security acknowledgement\n2. AI model provider + API key\n3. Channel connections (WhatsApp, Telegram, Slack, etc.)\n4. Skills installation\n5. Daemon setup (auto-start on boot)\n\n### Quick Start\n\n```bash\n# Start the gateway\nsymi gateway --port 18789 --verbose\n\n# Send a message\nsymi message send --to +1234567890 --message \"Hello from Symi\"\n\n# Talk to the agent\nsymi agent --message \"What's on my calendar today?\" --thinking high\n\n# Check health\nsymi doctor\n```\n\n### Non-Interactive (CI/Automation)\n\n```bash\nsymi onboard --non-interactive --accept-risk \\\n --auth-choice openai-api-key \\\n --openai-api-key \"$OPENAI_API_KEY\" \\\n --install-daemon\n```\n\n### Chat Commands\n\nSend in WhatsApp/Telegram/Slack/Teams/WebChat:\n\n| Command | Description |\n| ---------------------------------------- | --------------------------------------------------------------------- |\n| `/status` | Session status (model, tokens, cost) |\n| `/new` | Reset the session |\n| `/compact` | Compact session context |\n| `/think