Symi

A Multi-Channel AI Agent Gateway with Autonomous Behavioral Intelligence

The architecture behind truly autonomous AI agents — decoded, rebuilt, and deployed at scale

Created By: Jerome Naidoo

Overview • Architecture • Key Features • Installation • Usage • Documentation

Overview

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

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:

• Persistent identity across channels — the agent doesn't restart when you switch from WhatsApp to Slack
• Session-aware reasoning — context isn't just a sliding window; it's a managed, routed, multi-tenant state machine
• Gateway-first control — the agent is a service, not a script; it runs as a daemon with a real control plane

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

The Problem with Current Approaches

Most "AI agent" frameworks are glorified chat loops:

| Problem | Description | | --------------------- | ------------------------------------------------------------------------------ | | No Persistence | Agent state dies when the script exits — no memory, no continuity | | Single Channel | Locked to one interface (web chat, CLI, or API) with no cross-channel identity | | No Session Model | Every conversation is isolated; the agent can't reason across interactions | | No Control Plane | No way to monitor, route, configure, or manage the agent as a running service | | No Security Model | Inbound messages from messaging platforms are treated as trusted input |

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

Architecture

Symi operates as a local-first Gateway that bridges messaging channels to AI model providers through a managed agent runtime:

Channels (WhatsApp / Telegram / Slack / Discord / Signal / iMessage / Teams / Matrix / WebChat / ...)
                │
                ▼
┌───────────────────────────────────┐
│           Gateway                 │
│      (WebSocket Control Plane)    │
│       ws://127.0.0.1:18789       │
├───────────────────────────────────┤
│                                   │
│   ┌───────────┐  ┌───────────┐   │
│   │  Channel   │  │  Session   │  │
│   │  Adapters  │  │  Router    │  │
│   │            │  │            │  │
│   │ WhatsApp   │  │ DM → main  │  │
│   │ Telegram   │  │ Group → N  │  │
│   │ Slack      │  │ Isolation  │  │
│   │ Discord    │  │ Pruning    │  │
│   │ Signal     │  │ Compaction │  │
│   │ iMessage   │  │            │  │
│   │ Teams      │  │            │  │
│   │ Matrix     │  │            │  │
│   │ WebChat    │  │            │  │
│   └───────────┘  └───────────┘   │
│                                   │
│   ┌───────────┐  ┌───────────┐   │
│   │   Agent    │  │   Tools    │  │
│   │  Runtime   │  │  + Skills  │  │
│   │            │  │            │  │
│   │ Multi-model│  │ Browser    │  │
│   │ Failover   │  │ Canvas     │  │
│   │ Streaming  │  │ Cron       │  │
│   │ Thinking   │  │ Nodes      │  │
│   │ Memory     │  │ Webhooks   │  │
│   └───────────┘  └───────────┘   │
│                                   │
├───────────────────────────────────┤
│   Companion Apps                  │
│   macOS • iOS • Android • CLI     │
└───────────────────────────────────┘

Key Features

Multi-Channel Agent Inbox

• 16+ channels: WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage (BlueBubbles), Microsoft Teams, Matrix, Zalo, WebChat, macOS, iOS, Android
• Unified identity: Same agent, same memory, same personality across all channels
• Per-channel routing: DM pairing, group isolation, allowlists, activation modes

Session-Aware Intelligence

• Multi-tenant sessions: Each conversation gets its own managed session with isolated context
• Session pruning and compaction: Automatic context management that prevents token exhaustion
• Agent-to-agent coordination: Sessions can message each other via sessions_send
• Thinking levels: Configurable reasoning depth (off through xhigh)

50+ Model Providers

• First-class support: OpenAI, Anthropic, Google Gemini, xAI/Grok, Z.AI, and more
• Model failover: Automatic fallback chains across providers
• OAuth + API key auth: Encrypted credential profiles with rotation
• Custom endpoints: Any OpenAI-compatible or Anthropic-compatible API

Gateway Control Plane

• WebSocket protocol: Real-time control for all clients, tools, and events
• Daemon mode: Runs as a system service (launchd/systemd) — survives reboots
• Health monitoring: symi doctor validates config, auth, connectivity, sandbox, and daemon state
• Tailscale integration: Serve (tailnet-only) or Funnel (public) with zero port forwarding

First-Class Tool System

• Browser control: Dedicated Chrome/Chromium with CDP, snapshots, and actions
• Live Canvas: Agent-driven visual workspace with A2UI protocol
• Device nodes: Camera, screen recording, location, notifications via iOS/Android/macOS
• Cron + webhooks + Gmail Pub/Sub: Event-driven automation

Security by Default

• DM pairing: Unknown senders get a pairing code; the agent ignores them until approved
• Sandbox mode: Non-main sessions run in per-session Docker containers
• Tool allowlists/denylists: Fine-grained control over what the agent can execute
• Prompt injection awareness: Inbound DMs are treated as untrusted input

What Makes This Different

Installation

One-Line Install (Recommended)

# macOS / Linux / WSL
curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash

# Windows (PowerShell)
iwr -useb https://jaysteelmind.github.io/getsymi/install.ps1 | iex

The installer handles Node.js 22+, Git, and symi installation, then launches the onboarding wizard.

Manual Install

npm install -g @symerian/symi@latest
symi onboard --install-daemon

From Source

git clone https://github.com/symi/symi.git
cd symi
pnpm install
pnpm ui:build
pnpm build
pnpm symi onboard --install-daemon

Requirements

• Node.js 22+
• macOS, Linux, or Windows (WSL2 recommended)
• pnpm only needed for building from source

Usage

Onboarding Wizard

symi onboard --install-daemon

The wizard walks you through:

1. Security acknowledgement
2. AI model provider + API key
3. Channel connections (WhatsApp, Telegram, Slack, etc.)
4. Skills installation
5. Daemon setup (auto-start on boot)

Quick Start

# Start the gateway
symi gateway --port 18789 --verbose

# Send a message
symi message send --to +1234567890 --message "Hello from Symi"

# Talk to the agent
symi agent --message "What's on my calendar today?" --thinking high

# Check health
symi doctor

Non-Interactive (CI/Automation)

symi onboard --non-interactive --accept-risk \
  --auth-choice openai-api-key \
  --openai-api-key "$OPENAI_API_KEY" \
  --install-daemon

Chat Commands

Send in WhatsApp/Telegram/Slack/Discord/Teams/WebChat:

| Command | Description | | ------------------ | ------------------------------------ | | /status | Session status (model, tokens, cost) | | /new | Reset the session | | /compact | Compact session context | | /think <level> | Set reasoning depth | | /verbose on\|off | Toggle verbose output |

Configuration

Minimal ~/.symi/symi.json:

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

Full reference: Configuration docs

Development

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

# Run tests
pnpm test

# Lint + format
pnpm check

# Build
pnpm build

Project Structure

symi/
├── src/                  # Core source (TypeScript ESM)
│   ├── cli/              # CLI wiring
│   ├── commands/         # Command implementations
│   ├── channels/         # Channel routing
│   ├── provider-web.ts   # Web provider
│   ├── infra/            # Infrastructure
│   └── media/            # Media pipeline
├── docs/                 # Documentation (Mintlify)
├── extensions/           # Plugin extensions
├── apps/                 # Companion apps (macOS/iOS/Android)
├── scripts/              # Build and test scripts
└── dist/                 # Build output

Documentation

| Document | Description | | ---------------------------------------------------------------- | -------------------------------------- | | Getting Started | First install to first message | | Architecture | Gateway + protocol model | | Configuration | Every config key with examples | | Channels | Channel setup guides | | Security | DM pairing, sandboxing, trust model | | Tools | Browser, canvas, nodes, cron | | Skills | Bundled, managed, and workspace skills | | Onboarding Wizard | Step-by-step guided setup | | Troubleshooting | Common failure debugging | | Installer Internals | How install scripts work |

Design Principles

This system draws from principles in:

• Service-Oriented Architecture — The agent is a daemon with a control plane, not a script
• Multi-Tenant Session Design — Isolation, routing, and lifecycle management borrowed from production messaging systems
• Defense-in-Depth Security — Pairing codes, sandboxing, allowlists, and untrusted input handling
• Provider Abstraction — Model failover, auth rotation, and compatibility layers across 50+ providers
• Channel-Agnostic Identity — One agent, one personality, every surface

Contributing

See CONTRIBUTING.md for guidelines and how to submit PRs.

License

MIT License — See LICENSE for details.

Symi — The secrets of agent behavior, decoded and deployed

Jerome Naidoo

Building autonomous AI agents that actually behave like agents.