Config Schema
Complete reference for the config.yaml configuration file. All fields are validated using Zod schemas at startup.
Minimal Example
meta
Internal metadata. Usually auto-managed.
| Field | Type | Default | Description |
|---|---|---|---|
meta.version | string | "1.0.0" | Config schema version |
meta.created_at | string? | - | Timestamp when config was created |
meta.last_modified_at | string? | - | Timestamp of last modification |
meta.onboard_command | string | "teleton setup" | CLI command shown during onboarding |
agent
LLM provider and model configuration.
| Field | Type | Default | Description |
|---|---|---|---|
agent.provider | enum | "anthropic" | LLM provider. One of: anthropic, claude-code, openai, google, xai, groq, openrouter, moonshot, mistral, cerebras, zai, minimax, huggingface, cocoon, local |
agent.api_key | string | "" | API key for the selected provider |
agent.model | string | "claude-opus-4-6" | Model identifier (provider-specific) |
agent.utility_model | string? | - | Cheap model for summarization (auto-detected if omitted) |
agent.max_tokens | number | 4096 | Maximum output tokens per LLM call |
agent.temperature | number | 0.7 | Sampling temperature |
agent.system_prompt | string | null | null | Custom system prompt override (null = use built-in) |
agent.max_agentic_iterations | number | 5 | Maximum number of agentic loop iterations (tool call cycles) |
agent.base_url | string? | - | Base URL for local LLM providers (e.g. Ollama, vLLM). Used when agent.provider is local. |
agent.session_reset_policy
Controls automatic conversation session resets.
| Field | Type | Default | Description |
|---|---|---|---|
daily_reset_enabled | boolean | true | Enable daily session reset |
daily_reset_hour | number (0-23) | 4 | Hour of day to reset sessions |
idle_expiry_enabled | boolean | true | Enable session reset after idle period |
idle_expiry_minutes | number | 1440 | Minutes of inactivity before session reset (default: 24h) |
telegram
Telegram client and access control settings.
| Field | Type | Default | Description |
|---|---|---|---|
telegram.api_id | number | required | Telegram API ID (from my.telegram.org) |
telegram.api_hash | string | required | Telegram API Hash |
telegram.phone | string | required | Phone number in international format |
telegram.session_name | string | "teleton_session" | Session file name |
telegram.session_path | string | "~/.teleton" | Directory for session storage |
telegram.dm_policy | enum | "allowlist" | DM access policy: allowlist, admin-only, open, disabled |
telegram.allow_from | number[] | [] | Allowed user IDs for DM allowlist mode |
telegram.group_policy | enum | "open" | Group access policy: open, allowlist, admin-only, disabled |
telegram.group_allow_from | number[] | [] | Allowed group IDs for group allowlist mode |
telegram.require_mention | boolean | true | Require @mention in groups to trigger the agent |
telegram.max_message_length | number | 4096 | Maximum Telegram message length |
telegram.typing_simulation | boolean | true | Simulate typing indicator while processing |
telegram.rate_limit_messages_per_second | number | 1.0 | Rate limit for outgoing messages |
telegram.rate_limit_groups_per_minute | number | 20 | Rate limit for group messages per minute |
telegram.admin_ids | number[] | [] | Telegram user IDs with admin privileges |
telegram.agent_channel | string | null | null | Channel for agent status broadcasts |
telegram.owner_name | string? | - | Owner's first name (e.g., "Alex") |
telegram.owner_username | string? | - | Owner's Telegram username (without @) |
telegram.owner_id | number? | - | Owner's Telegram user ID |
telegram.debounce_ms | number | 1500 | Debounce delay in ms for group messages (0 = disabled) |
telegram.bot_token | string? | - | Telegram Bot token from @BotFather for inline deal buttons |
telegram.bot_username | string? | - | Bot username without @ (e.g., "teleton_deals_bot") |
storage
File paths and limits for persistent storage.
| Field | Type | Default | Description |
|---|---|---|---|
storage.sessions_file | string | "~/.teleton/sessions.json" | Path to sessions file |
storage.memory_file | string | "~/.teleton/memory.json" | Path to memory store file |
storage.history_limit | number | 100 | Max conversation history entries kept |
embedding
Vector embedding configuration for memory search.
| Field | Type | Default | Description |
|---|---|---|---|
embedding.provider | enum | "local" | Embedding provider: local (ONNX), anthropic (API), or none (FTS5-only) |
embedding.model | string? | - | Model override (default: Xenova/all-MiniLM-L6-v2 for local) |
deals
P2P deal/escrow system configuration.
| Field | Type | Default | Description |
|---|---|---|---|
deals.enabled | boolean | true | Enable the deals system |
deals.expiry_seconds | number | 120 | Deal expiration time in seconds |
deals.buy_max_floor_percent | number | 95 | Max buy price as percent of floor |
deals.sell_min_floor_percent | number | 105 | Min sell price as percent of floor |
deals.poll_interval_ms | number | 5000 | Blockchain polling interval in ms |
deals.max_verification_retries | number | 12 | Max retries for transaction verification |
deals.expiry_check_interval_ms | number | 60000 | Interval for checking expired deals in ms |
capabilities
Feature capability flags. Currently controls the exec tool category (Linux only).
| Field | Type | Default | Description |
|---|---|---|---|
capabilities.exec.enabled | boolean | false | Enable the exec tool category (exec_run, exec_install, exec_service, exec_status) |
capabilities.exec.scope | enum | "admin-only" | Default scope for all exec tools: admin-only, dm-only, always |
capabilities.exec.allowlist | string[] | [] | Glob patterns of allowed commands. Empty = all commands allowed (within scope). |
capabilities.exec.limits.max_output_bytes | number | 65536 | Maximum stdout/stderr size per command execution |
capabilities.exec.limits.timeout_ms | number | 30000 | Command execution timeout in milliseconds |
capabilities.exec.audit | boolean | true | Log all exec invocations to the exec_audit table in memory.db |
config.yaml
capabilities:
exec:
enabled: true
scope: admin-only
allowlist: [] # empty = all commands allowed
limits:
max_output_bytes: 65536
timeout_ms: 30000
audit: truewebui
Built-in web dashboard configuration.
| Field | Type | Default | Description |
|---|---|---|---|
webui.enabled | boolean | false | Enable WebUI server |
webui.port | number | 7777 | HTTP server port |
webui.host | string | "127.0.0.1" | Bind address (localhost only for security) |
webui.auth_token | string? | - | Bearer token for API auth (auto-generated if omitted) |
webui.cors_origins | string[] | ["http://localhost:5173", "http://localhost:7777"] | Allowed CORS origins for development |
webui.log_requests | boolean | false | Log all HTTP requests |
logging
Logging output configuration.
| Field | Type | Default | Description |
|---|---|---|---|
logging.level | enum | "info" | Log level: trace, debug, info, warn, error, fatal |
logging.pretty | boolean | true | Enable pino-pretty formatting (human-readable, colored output) |
dev
Development settings.
| Field | Type | Default | Description |
|---|---|---|---|
dev.hot_reload | boolean | false | Enable plugin hot-reload (watches ~/.teleton/plugins/ for changes) |
tool_rag
Semantic tool retrieval to reduce token usage with large tool sets.
| Field | Type | Default | Description |
|---|---|---|---|
tool_rag.enabled | boolean | true | Enable semantic tool retrieval (Tool RAG) |
tool_rag.top_k | number | 25 | Max tools to retrieve per LLM call |
tool_rag.always_include | string[] | ["telegram_send_message", "telegram_reply_message", "telegram_send_photo", "telegram_send_document", "journal_*", "workspace_*", "web_*"] | Tool name patterns always included (supports glob with *) |
tool_rag.skip_unlimited_providers | boolean | false | Skip Tool RAG for providers with no tool limit (e.g. Anthropic) |
mcp
Model Context Protocol server connections.
| Field | Type | Default | Description |
|---|---|---|---|
mcp.servers | Record<string, McpServer> | {} | Named map of MCP server configurations |
Each MCP server entry
| Field | Type | Default | Description |
|---|---|---|---|
command | string? | - | Stdio command (e.g. "npx @modelcontextprotocol/server-filesystem /tmp") |
args | string[]? | - | Explicit args array (overrides command splitting) |
env | Record<string, string>? | - | Environment variables for stdio server |
url | string? | - | SSE/HTTP endpoint URL (alternative to command) |
scope | enum | "always" | Tool scope: always, dm-only, group-only, admin-only |
enabled | boolean | true | Enable/disable this server |
MCP server requirement
Each MCP server needs either command (stdio) or url (SSE/HTTP). At least one must be provided.
plugins
Per-plugin configuration. Keys are plugin names (with underscores).
| Field | Type | Default | Description |
|---|---|---|---|
plugins | Record<string, unknown> | {} | Arbitrary per-plugin config keyed by plugin name |
Top-Level Fields
| Field | Type | Default | Description |
|---|---|---|---|
cocoon.port | number (1-65535) | 10000 | HTTP port of the cocoon-cli proxy (Cocoon Network integration) |
tonapi_key | string? | - | TonAPI key for higher rate limits (from @tonapi_bot) |
toncenter_api_key | string? | - | TonCenter API key for TON blockchain RPC calls (from toncenter.com). Increases rate limits on the public endpoint. |
tavily_api_key | string? | - | Tavily API key for web search & extract |
Environment Variables
Secrets should be provided via environment variables or an .env file:
| Variable | Config Field | Required |
|---|---|---|
TG_API_ID | telegram.api_id | Yes |
TG_API_HASH | telegram.api_hash | Yes |
ANTHROPIC_API_KEY | agent.api_key | If using Anthropic |
OPENAI_API_KEY | agent.api_key | If using OpenAI |
GROQ_API_KEY | agent.api_key | If using Groq |
GOOGLE_API_KEY | agent.api_key | If using Google |
XAI_API_KEY | agent.api_key | If using xAI |
TONAPI_KEY | tonapi_key | No (higher rate limits) |
TAVILY_API_KEY | tavily_api_key | No (web search) |