Gateway

The Gateway is the persistent process that keeps OpenVesper running. Hub-and-spoke architecture: every channel routes through one place, with shared sessions, proactive heartbeats, command queue, compaction, routing, and delegation.

Why a persistent process?

• One session shared across CLI, Telegram, VSCode (channel docking)
• Heartbeats run on schedule — agents message you proactively
• Steer in-flight runs by sending follow-up messages
• Compact long conversations automatically
• Async API for long-running tasks (runId + wait/abort)
• WebSocket transport for real-time streaming
• OAuth flows handled locally with PKCE

Starting the gateway

Foreground (logs to your terminal):

vesper gateway start

Detached background:

vesper gateway start --detach
vesper gateway status
vesper gateway logs --lines 100
vesper gateway stop

Channel commands

Any message starting with / is intercepted before reaching the LLM:

Queue modes (handling mid-run messages)

What happens when you send a new message while the agent is busy? Three modes:

• steer (default) — inject into the active run after current tool calls, before the next LLM call. Use this for "wait, actually do X instead".
• followup — queue the message, deliver as a new turn after current ends. Debounce 1s by default.
• collect — batch multiple queued messages and deliver as one structured prompt.

Async API

For long-running tasks, fire-and-forget then check back:

# Returns immediately with { runId, acceptedAt }
curl -X POST http://127.0.0.1:18789/agent/async \
  -d '{"sessionKey":"u1", "message":"analyze 100 tokens"}'

# Later — block until done (timeout 5 min default)
curl -X POST http://127.0.0.1:18789/agent/run/r_xyz/wait

# Or cancel
curl -X POST http://127.0.0.1:18789/agent/run/r_xyz/abort

Compaction

When the context window fills up, OpenVesper compacts the conversation: older messages are summarized into a single system message, recent messages kept verbatim. Trigger manually with /compact or via API:

# Check token usage
curl http://127.0.0.1:18789/sessions/u1/tokens

# Compact (keep last 10 messages verbatim)
curl -X POST http://127.0.0.1:18789/sessions/u1/compact \
  -d '{"keepRecent": 10}'

Multi-agent routing

The router examines a message and picks the best specialist agent:

curl -X POST http://127.0.0.1:18789/agent/route \
  -d '{"message":"check this Solana token for rugs"}'
# → { "mode": "bags-hunter", "score": 12, "reason": "matched: solana, token, rug" }

Delegation

One agent can sub-query another without changing your active agent:

curl -X POST http://127.0.0.1:18789/agent/delegate \
  -d '{
    "parentSessionKey": "u1",
    "delegateAgent": "code-reviewer",
    "query": "review this snippet for security issues"
  }'

Or hand off the entire session:

curl -X POST http://127.0.0.1:18789/agent/handoff \
  -d '{"sessionKey":"u1", "newAgent":"defi-strategist"}'

OAuth (local PKCE flow)

Plugins that need Gmail, Calendar, GitHub access can authorize via OAuth. The entire flow runs on your machine — tokens never leave it.

# Authorize Google (Gmail + Calendar)
vesper oauth login google \
  --client-id YOUR_GOOGLE_CLIENT_ID \
  --client-secret YOUR_SECRET

# A URL prints — open it, authorize, browser redirects to localhost:53174,
# tokens save to ~/.openvesper/tokens/google.json (mode 0600).

# List authorized providers
vesper oauth list

# Revoke
vesper oauth logout google

Built-in provider templates: google, github, slack. You bring your own Client ID — register an OAuth app with the provider.

Heartbeat daemon

Scans .agents/ for HEARTBEAT.md files with enabled: true. On schedule, the gateway wakes each agent with its checklist. If the agent has work, it runs tools and returns a reply (delivered via the configured channel). If not, it returns HEARTBEAT_OK — gateway silently suppresses.

Endpoints

Bound to 127.0.0.1:18789 by default. Never exposed publicly.

Agent

Sessions

OAuth & Heartbeat

Security

• Loopback bind default. Gateway listens on 127.0.0.1 only.
• No remote access without explicit setup. Use Tailscale, SSH tunnel, or Cloudflare Tunnel.
• Session files mode 0600. Only your user can read them.
• OAuth tokens mode 0600. Stored at ~/.openvesper/tokens/.
• Tool permissions still enforced. Mutating tools audit or prompt.
• Zero data retention. No OpenVesper servers. Nothing leaves your machine.

Hooks (extensibility)

8 lifecycle events: agent:bootstrap, agent:tool-call, agent:tool-result, agent:complete, agent:error, agent:queued, command:new, command:reset.

import { hooks } from "@openvesper/gateway/hooks";

hooks.register("agent:bootstrap", async (ctx) => {
  ctx.systemPrompt += "\n## Local time\n" + new Date().toISOString();
  return ctx;
});

What's next?

• Cron jobs
• Channels
• Security policy