Channels

Channels are the interfaces through which users interact with Maestro. Write your agent logic once, deploy to multiple platforms.

Available Channels

Channel	Use Case	Session ID
CLI	Development, personal use	Fixed per terminal
Telegram	Mobile access, group chats	Chat ID
REST API	Integration, web apps	Caller-provided

Channel Comparison

Best for: Development, testing, personal assistant use

npm run cli

Features:

Interactive REPL interface
Streaming responses
Built-in commands (/help, /clear, /cost)
Colored output

Session ID is fixed to the terminal, so you get conversation continuity.

Best for: Mobile access, team use, always-on assistant

npm run dev
# or
docker compose up telegram

Features:

Works on any device with Telegram
Group chat support
Message formatting (markdown)
Inline keyboards (future)

Requires TELEGRAM_BOT_TOKEN in your .env file.

Best for: Building web apps, custom integrations

npm run api
# or
docker compose up api

Features:

Streaming (SSE) and non-streaming modes
Session management via query parameter
JSON request/response
Easy to integrate with any frontend

Default port: 3000

Running Multiple Channels

With Docker Compose, you can run all channels simultaneously:

docker compose up -d

This starts:

Telegram bot
REST API on port 3000

All channels share the same:

Agent configurations
Memory (SQLite)
Tools
Orchestrator

REST API Reference

Chat Endpoint

Streaming (SSE):

curl -X POST http://localhost:3000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "sessionId": "user-123"}'

Non-streaming:

curl -X POST http://localhost:3000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "sessionId": "user-123", "stream": false}'

Get Session History

curl http://localhost:3000/chat/user-123

List Agents

curl http://localhost:3000/agents

Building Custom Channels

Channels implement a simple interface:

interface Channel {
  // Start receiving messages
  start(): Promise<void>;

  // Stop the channel
  stop(): Promise<void>;
}

A channel:

Receives messages from its platform
Transforms to the common format
Calls the orchestrator
Returns the response in platform format

Session ID Strategy

How you generate session IDs affects conversation isolation:

Strategy	Effect
Per-user	Each user has separate conversations
Per-chat	Group members share conversation
Per-device	Same user has different conversations per device
Fixed	Everyone shares one conversation

Choose based on your use case:

Personal assistant: Per-user or per-device
Team bot: Per-chat
Demo: Fixed

Channel Security

Telegram: Uses Telegram’s authentication
CLI: Local access only
API: No built-in auth (add middleware for production)