# SwarmAI

> Your personal, self-hosted multi-channel AI assistant. Install once, pair it to your channels (WhatsApp, Telegram, email, browser), and your **Main Agent** runs as a CEO Agent — fielding messages, spawning specialist peer agents, driving long-running plans, and learning over time.

`@northpeak/swarmai` is the packaged distribution: a `swarmai` CLI plus a bundled gateway (server + web dashboard). You own the workspace, the keys, and the data — everything runs on your machine.

## Requirements

- **Node ≥ 22**
- **Docker** *(recommended)* — runs Qdrant + Redis for long-term memory / RAG. The gateway boots without them for basic use; vector memory and some features need them.
- An LLM provider — a cloud key (Anthropic, OpenAI, OpenRouter, Gemini) **or** a local runtime (Ollama). You pick during setup.

## Install

```bash
npm install -g @northpeak/swarmai
swarmai --help
```

This puts a `swarmai` command on your PATH.

## First run

```bash
swarmai setup     # guided onboarding — workspace, master passphrase, encrypted vault, provider, channels
swarmai start     # launch the gateway (server + dashboard)
```

Defaults once running:

- **Server:** http://localhost:7910
- **Dashboard:** http://localhost:18789

Pair your browser to open the dashboard:

```bash
swarmai pair dashboard            # prints a 6-digit code
# open the dashboard URL and enter the code
```

## Everyday commands

```bash
swarmai start                     # bring it up (idempotent)
swarmai status                    # health snapshot
swarmai doctor                    # config + network + provider probes
swarmai logs --tail 100           # stream the event bus
swarmai stop                      # bring it down

swarmai daemon install            # run as an OS service (systemd / launchd / Windows Service)
swarmai whatsapp pair             # pair the WhatsApp personal channel
swarmai telegram-client pair      # pair the Telegram (MTProto) channel
swarmai hub search <query>        # browse the SwarmAI Hub and install plugins
swarmai spawn <peerId>            # spawn a specialist peer agent
```

Run `swarmai <command> --help` for any subcommand. `swarmai` with no arguments drops into an interactive REPL.

## What you get

- **One Main Agent** with persistent identity, memory, and a self-improvement (Playtime) loop.
- **Multi-agent**: spawn Ops / Tech / HR-style peer agents that collaborate over an internal peer-bus.
- **Channels**: WhatsApp, Telegram, email, webhooks, and a paired browser extension.
- **Dashboard**: a desktop-style web UI — chat, agents, meetings, approvals, sources, triggers, logs, replay, and a plugin Hub.
- **Meetings**: multi-party rooms; external guests can join via share links when the Meeting Bridge Hub plugin is installed.
- **Extensible**: install tools, channels, personas, and integrations from the SwarmAI Hub — no rebuild.

## Workspace & data

Your workspace (config, encrypted vault, memory, logs) lives under your home directory by default; override with `SWARMAI_WORKSPACE`. Secrets are held in an AES-256-GCM vault unlocked by your master passphrase. Nothing leaves your machine except the LLM/channel API calls you configure.

## Updating

```bash
npm install -g @northpeak/swarmai@latest
swarmai stop && swarmai start
```

## License

Ships under **PolyForm Noncommercial 1.0.0** — free for personal and other non-commercial use. See [`LICENSE`](./LICENSE) for terms; contact the vendor for a commercial license.
