Architecture

Hub-and-spoke. One persistent gateway process, many channels and tools attached. Everything runs on your machine; no OpenVesper servers exist.

Top-level layout

     ┌──────────────────────────────────────────────────────────┐
     │                  ⚙ Gateway (127.0.0.1:18789)             │
     │                                                          │
     │  agent-loop  session-lane  command-queue  context-engine │
     │  router      delegate      compaction     memory-engine  │
     │  oauth       audit         approvals      tasks          │
     │  standing    commitments   heartbeat      streaming      │
     │  channel-routing  access-groups  workspaces  remote      │
     │                                                          │
     └──┬─────────────┬─────────────┬─────────────┬─────────────┘
        │             │             │             │
   ┌────▼────┐  ┌─────▼────┐  ┌─────▼────┐  ┌─────▼────┐
   │   CLI   │  │ Telegram │  │  Slack   │  │ Discord  │
   └─────────┘  └──────────┘  └──────────┘  └──────────┘

Why a persistent gateway

• One session shared across channels (channel docking)
• Scheduled heartbeats can run when no channel is open
• Background tasks survive between requests
• OAuth flows + WebSocket streams need a long-lived process
• Compaction, audit, memory engine all need shared state

What runs in-process

The gateway holds all runtime state. Files on disk are the source of truth, but during operation everything lives in one Node process:

• Session cache (LRU, 100 active, 200 messages each)
• Per-session lanes + global concurrency limit
• Command queue with per-session mode
• Run registry (in-flight + 30min completed history)
• Hook listeners (plugin extensibility)
• WS clients tracking + broadcast
• Tool loop detector state

What's persisted

See file layout. Briefly:

• Sessions — ~/.openvesper/workspace/sessions/
• Memory entries — per-agent dir
• OAuth tokens, tasks, standing orders, commitments, approvals — ~/.openvesper/ root
• Audit logs — daily JSONL files

Channels are plugins

Telegram, Slack, Discord, etc. are just plugins. They open a transport (long-poll, WebSocket) and send messages to the gateway. No special treatment.

Plugins are sandboxed

See sandboxing. Tools declare permissions; mutation/filesystem/shell tools route through approvals.

Multiple gateways possible

See workspaces. Each gateway gets its own port + isolated state.

Source

Implementation: apps/gateway/src/ (28 files).