<div align="center">

# Symi

### A Multi-Channel AI Agent Gateway with Autonomous Behavioral Intelligence

[![CI](https://img.shields.io/github/actions/workflow/status/symi/symi/ci.yml?branch=main)]()
[![Node](https://img.shields.io/badge/node-22%2B-blue)]()
[![License](https://img.shields.io/badge/license-MIT-green)]()
[![Channels](https://img.shields.io/badge/channels-16%2B%20supported-success)]()

_The architecture behind truly autonomous AI agents — decoded, rebuilt, and deployed at scale_

**Created By: Jerome Naidoo**

[Overview](#overview) • [Architecture](#architecture) • [Key Features](#key-features) • [Installation](#installation) • [Usage](#usage) • [Documentation](#documentation)

</div>

---

## 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 / 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  │  │
│   │ Signal     │  │ Pruning    │  │
│   │ iMessage   │  │ Compaction │  │
│   │ 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

- **15+ channels**: WhatsApp, Telegram, Slack, 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

<table>
<tr>
<th>Capability</th>
<th>Typical AI Agent Frameworks</th>
<th>Symi</th>
</tr>
<tr>
<td><b>Persistence</b></td>
<td>Script-level; dies on exit</td>
<td>Daemon with managed sessions</td>
</tr>
<tr>
<td><b>Channels</b></td>
<td>Single (web/CLI)</td>
<td>16+ with unified identity</td>
</tr>
<tr>
<td><b>Control Plane</b></td>
<td>None</td>
<td>WebSocket gateway with health, config, presence</td>
</tr>
<tr>
<td><b>Model Support</b></td>
<td>1-3 providers</td>
<td>50+ with failover chains</td>
</tr>
<tr>
<td><b>Security</b></td>
<td>Trust all input</td>
<td>DM pairing, sandbox, allowlists</td>
</tr>
<tr>
<td><b>Device Integration</b></td>
<td>None</td>
<td>macOS/iOS/Android nodes (camera, screen, voice)</td>
</tr>
<tr>
<td><b>Deployment</b></td>
<td>Manual process management</td>
<td>One-command daemon install with doctor</td>
</tr>
</table>

---

## Installation

### One-Line Install (Recommended)

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

```powershell
# 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

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

### From Source

```bash
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

```bash
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

```bash
# 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)

```bash
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/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`:

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

Full reference: [Configuration docs](https://docs.symi.ai/gateway/configuration)

---

## Development

```bash
# 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](https://docs.symi.ai/start/getting-started)    | First install to first message         |
| [Architecture](https://docs.symi.ai/concepts/architecture)       | Gateway + protocol model               |
| [Configuration](https://docs.symi.ai/gateway/configuration)      | Every config key with examples         |
| [Channels](https://docs.symi.ai/channels)                        | Channel setup guides                   |
| [Security](https://docs.symi.ai/gateway/security)                | DM pairing, sandboxing, trust model    |
| [Tools](https://docs.symi.ai/tools)                              | Browser, canvas, nodes, cron           |
| [Skills](https://docs.symi.ai/tools/skills)                      | Bundled, managed, and workspace skills |
| [Onboarding Wizard](https://docs.symi.ai/start/wizard)           | Step-by-step guided setup              |
| [Troubleshooting](https://docs.symi.ai/channels/troubleshooting) | Common failure debugging               |
| [Installer Internals](https://docs.symi.ai/install/installer)    | 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](CONTRIBUTING.md) for guidelines and how to submit PRs.

---

## License

MIT License — See [LICENSE](LICENSE) for details.

---

<div align="center">

**Symi** — _The secrets of agent behavior, decoded and deployed_

**Jerome Naidoo**

Building autonomous AI agents that actually behave like agents.

</div>
