Skip to content

Gateway Overview

Scope: standalone Python Runtime. For Desktop operations, see the Desktop guide.

Echo Agent Gateway is an aiohttp-based HTTP/WebSocket server responsible for ingesting external messages, managing session lifecycles, enforcing authentication and rate limiting, and routing messages to platform-specific delivery channels.

Core Features

Feature Description
External message ingestion Receive messages from third-party systems via HTTP POST and WebSocket
Session lifecycle management Create, resume, reset, and destroy sessions
Authentication & rate limiting Multi-mode auth + token-bucket rate limiting
Cross-platform delivery routing Automatically select delivery channel based on target platform
Progressive message editing Real-time message updates during streaming output
Health monitoring {api_prefix}/health (default /api/v1/health) for health probes

Architecture

GatewayServer acts as the main orchestrator, coordinating the following subsystems:

GatewayServer
├── Auth              # Authentication module (multi-mode)
├── RateLimiter       # Token-bucket rate limiter
├── DeliveryRouter    # Cross-platform delivery routing
├── ProgressiveEditor # Progressive message editing
├── MediaCache        # Media file cache
├── SessionResetPolicy # Session reset policy
└── HookRegistry      # Hook registry

Subsystem Files

File Responsibility
auth.py Authentication logic (open / allowlist / pairing modes)
router.py Message delivery routing
rate_limiter.py Token-bucket rate limiting
server.py aiohttp app initialization and route registration
health.py Health check endpoint
ws_session.py Platform and session-key normalization for the session WebSocket
ws_dashboard.py Dashboard WebSocket (for monitoring panels)

API Modules

Gateway exposes the following REST API modules under gateway/api/:

  • analytics — Statistics and analytics
  • channels — Channel management
  • config — Read-only runtime configuration query
  • cron_api — Scheduled task management
  • knowledge — Knowledge base operations
  • logs — Log queries
  • memory — Memory storage
  • sessions — Session CRUD
  • skills — Skill management
  • tasks — Async task queue

WebSocket Endpoints

Endpoint Purpose Protocol
/ws (configurable) Real-time communication for CLI and external integrations JSON over WebSocket
/ws/dashboard Real-time data push for monitoring dashboards JSON over WebSocket

Health Check

GET /api/v1/health

Returns JSON with HTTP 200 unless the status is unhealthy, in which case it returns 503. Configure probe policy for the deployment environment.

Rate Limiting

Gateway uses a token-bucket algorithm for rate limiting, isolated by platform + chat_id granularity:

  • Default limit: 30 RPM (30 requests per minute)
  • Configurable via the configuration file
  • Returns 429 Too Many Requests when exceeded

Rate Limit Granularity

Rate limiting uses platform:chat_id as the key, counting separately for the same user across different platforms. This means a single user has independent rate quotas on Telegram and Web respectively.

Configuration Example

gateway:
  enabled: true
  host: "0.0.0.0"
  port: 8090
  auth:
    mode: "allowlist"  # open | allowlist | pairing
    allowed_users: ["user1", "telegram:123456"]
    api_tokens: ["token-xxx"]
    admin_tokens: ["admin-xxx"]
    allowed_origins: ["https://my-dashboard.example.com"]
    allowed_hosts: ["my-dashboard.example.com"]

Production Notice

In production, always set auth.mode to allowlist or pairing — never use open mode. Use sufficiently long random strings for api_tokens and admin_tokens.

Default listen address

The Gateway listens on 127.0.0.1:58123 by default. The port comes from gateway.port and the host from gateway.host; both can also be overridden with ECHO_AGENT_GATEWAY__PORT and ECHO_AGENT_GATEWAY__HOST (double underscores separate config path segments).

Setting gateway.port to 0 lets the system assign a port; the one actually bound is written to workspace/.echo-agent/gateway.json.

Quick Start

Run the Gateway in the foreground or register it as a system service:

echo-agent gateway              # run in the foreground
echo-agent gateway install      # register as a resident background service

echo-agent run runs the full agent and also starts the Gateway when gateway.enabled: true. echo-agent gateway enables the Gateway in its own process even if gateway.enabled is absent from the configuration. Once running, echo-agent cli can attach as a thin client.

With the default listen address and API prefix, visit http://127.0.0.1:58123/api/v1/health to check its status.