The Gateway is the core orchestration engine that powers all AeonSage operations. It handles message routing, session management, AI provider integration, and channel coordination.
Overview
The AeonSage Gateway is a single binary that serves as the central nervous system of your AI infrastructure. It is designed to be:
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ AeonSage Gateway │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ API Layer │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ REST API │ │ WebSocket │ │ Webhook │ │ │
│ │ │ /api/* │ │ /ws │ │ /webhook/* │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────▼───────────────────────────────┐ │
│ │ Core Services │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Router │ │ Session │ │ Plugin │ │ Skill │ │ │
│ │ │ Engine │ │ Manager │ │ Loader │ │ Runner │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────▼───────────────────────────────┐ │
│ │ Data Layer │ │
│ │ ┌─────────────────┐ ┌─────────────────────────┐ │ │
│ │ │ Session Store │ │ Configuration Store │ │ │
│ │ │ (SQLite/PG) │ │ (JSON/KV) │ │ │
│ │ └─────────────────┘ └─────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Core Components
Router Engine
The Router Engine handles all incoming and outgoing message routing.
Session Manager
The Session Manager maintains conversation state across all interactions.
Plugin Loader
The Plugin Loader manages dynamic extension loading.
Configuration
Environment Variables
CLI Configuration
# Start with custom port
aeonsage gateway start --port 8080
# Start in SaaS mode
aeonsage gateway start --mode saas --db postgresql://localhost/aeonsage
# Start with specific config file
aeonsage gateway start --config /path/to/config.json
Health and Monitoring
Health Check Endpoints
Metrics Available
Security
Authentication Methods
Security Best Practices
Scaling
Vertical Scaling
For single-instance deployments, increase resources as needed:
Horizontal Scaling
For high-availability deployments:
Use PostgreSQL
Switch from SQLite to PostgreSQL for shared state.
Add Load Balancer
Place a load balancer in front of multiple gateway instances.
Configure Sticky Sessions
Use session affinity for WebSocket connections.
Scale Out
Add more gateway instances as traffic increases.
Troubleshooting
Common Issues
Log Analysis
# View recent logs
aeonsage logs --tail 100
# Filter by level
aeonsage logs --level error
# Filter by component
aeonsage logs --component router
Next Steps
