Configuration - Teleton Agent Documentation

Overview

The config file lives at ~/.teleton/config.yaml by default. You can override the path with the TELETON_HOME environment variable or the --config CLI flag.

Any scalar value in the config can be overridden via an environment variable. The naming convention is TELETON_<SECTION>_<KEY> in uppercase, e.g. TELETON_AGENT_API_KEY overrides agent.api_key. Nested keys use double underscores: TELETON_AGENT_SESSION_RESET_POLICY__DAILY_RESET_HOUR=6.

The full schema is validated with Zod on startup. Invalid values produce a clear error message listing every failing field.

agent

LLM provider settings and agentic loop behaviour.

Key	Type	Default	Description
`provider`	`string`	`anthropic`	LLM provider. One of `anthropic`, `claude-code`, `openai`, `google`, `xai`, `groq`, `openrouter`, `moonshot`, `mistral`, `cerebras`, `zai`, `minimax`, `huggingface`, `cocoon`, `local`.
`api_key`	`string`	`""`	API key for the chosen provider. Not required for `claude-code` (uses local credentials) or `local`.
`base_url`	`string`	—	Base URL for a local or self-hosted LLM server, e.g. `http://localhost:11434/v1`. Required when `provider: local`.
`model`	`string`	`claude-opus-4-6`	Model name as expected by the provider API.
`utility_model`	`string`	auto	Cheaper model used for memory summarisation and compaction. Auto-detected from the provider if omitted.
`max_tokens`	`number`	`4096`	Maximum tokens in the model's response.
`temperature`	`number`	`0.7`	Sampling temperature (0–2).
`system_prompt`	`string \| null`	`null`	Override the default system prompt entirely. Set to `null` to use the built-in soul assembly.
`max_agentic_iterations`	`number`	`5`	Maximum tool-call/result cycles per message before the agent gives up.

agent.session_reset_policy

Controls when conversation context is cleared to free memory.

Key	Type	Default	Description
`daily_reset_enabled`	`boolean`	`true`	Clear all sessions once per day at the configured hour.
`daily_reset_hour`	`number`	`4`	Hour of day (0–23, UTC) at which the daily reset fires.
`idle_expiry_enabled`	`boolean`	`true`	Expire a session after a period of inactivity.
`idle_expiry_minutes`	`number`	`1440`	Minutes of inactivity before session expiry (default: 24 h).

agent section example

agent:
  provider: anthropic
  api_key: sk-ant-api03-...
  model: claude-opus-4-6
  max_tokens: 4096
  temperature: 0.7
  max_agentic_iterations: 5
  session_reset_policy:
    daily_reset_enabled: true
    daily_reset_hour: 4
    idle_expiry_enabled: true
    idle_expiry_minutes: 1440

telegram

MTProto client credentials and messaging policies. api_id, api_hash, and phone are required. Obtain your API credentials at my.telegram.org/apps.

Key	Type	Default	Description
`api_id`	`number`	required	Telegram application API ID from my.telegram.org.
`api_hash`	`string`	required	Telegram application API hash from my.telegram.org.
`phone`	`string`	required	Phone number in international format, e.g. `+14155552671`.
`session_name`	`string`	`teleton_session`	GramJS session file name (no extension).
`session_path`	`string`	`~/.teleton`	Directory where the session file is stored.
`dm_policy`	`string`	`allowlist`	Who may send DMs to the agent. One of `allowlist`, `open`, `admin-only`, `disabled`.
`allow_from`	`number[]`	`[]`	Telegram user IDs allowed to DM the agent when `dm_policy: allowlist`.
`group_policy`	`string`	`open`	Which groups the agent responds in. One of `open`, `allowlist`, `admin-only`, `disabled`.
`group_allow_from`	`number[]`	`[]`	Group/channel IDs the agent is allowed in when `group_policy: allowlist`.
`require_mention`	`boolean`	`true`	In groups, only respond when the agent is directly mentioned.
`max_message_length`	`number`	`4096`	Maximum characters in a single outgoing Telegram message. Long responses are split automatically.
`typing_simulation`	`boolean`	`true`	Send "typing…" indicator while the agent is working.
`rate_limit_messages_per_second`	`number`	`1.0`	Maximum outgoing messages per second (Telegram flood-wait avoidance).
`rate_limit_groups_per_minute`	`number`	`20`	Maximum messages per minute across all group chats.
`admin_ids`	`number[]`	`[]`	Telegram user IDs with admin privileges (can use admin-only tools and commands).
`agent_channel`	`string \| null`	`null`	Username or ID of a channel the agent uses as its "feed" (e.g. `@my_agent_feed`).
`owner_name`	`string`	—	Owner's first name, injected into the system prompt so the agent knows who it belongs to.
`owner_username`	`string`	—	Owner's Telegram username without the `@`.
`owner_id`	`number`	—	Owner's Telegram user ID.
`debounce_ms`	`number`	`1500`	Milliseconds to wait for additional messages before processing in groups. Set to `0` to disable debouncing.
`bot_token`	`string`	—	Telegram Bot token from @BotFather. Required for inline deal buttons.
`bot_username`	`string`	—	Bot username without `@`, e.g. `teleton_deals_bot`. Required alongside `bot_token`.

telegram section example

telegram:
  api_id: 12345678
  api_hash: "abcdef1234567890abcdef1234567890"
  phone: "+14155552671"
  session_name: teleton_session
  session_path: ~/.teleton
  dm_policy: allowlist
  allow_from: [123456789]
  group_policy: open
  group_allow_from: []
  require_mention: true
  max_message_length: 4096
  typing_simulation: true
  rate_limit_messages_per_second: 1.0
  rate_limit_groups_per_minute: 20
  admin_ids: [123456789]
  agent_channel: null
  owner_name: "Alex"
  owner_username: "alexdev"
  owner_id: 123456789
  debounce_ms: 1500
  # bot_token: "7123456789:AAF..."
  # bot_username: "teleton_deals_bot"

storage

Paths for persistent data files.

Key	Type	Default	Description
`sessions_file`	`string`	`~/.teleton/sessions.json`	JSON file storing in-memory conversation sessions.
`memory_file`	`string`	`~/.teleton/memory.json`	Legacy memory file path (SQLite DB takes precedence for RAG).
`history_limit`	`number`	`100`	Maximum number of messages kept in a session's in-memory history.

embedding

Controls how memory entries are vectorised for semantic search (RAG).

Key	Type	Default	Description
`provider`	`string`	`local`	Embedding backend. `local` uses the bundled ONNX model (no API key required). `anthropic` calls the Anthropic embeddings API. `none` disables vector search and falls back to FTS5 only.
`model`	`string`	auto	Model override. Default for `local`: `Xenova/all-MiniLM-L6-v2`.

logging

Structured logging via Pino.

Key	Type	Default	Description
`level`	`string`	`info`	Minimum log level to emit. One of `trace`, `debug`, `info`, `warn`, `error`, `fatal`.
`pretty`	`boolean`	`true`	Enable pino-pretty for human-readable, coloured terminal output. Disable in production for JSON lines.

tool_rag

Tool RAG limits how many tools are exposed per LLM call via semantic retrieval. This is critical for providers with a fixed tool-count limit.

Key	Type	Default	Description
`enabled`	`boolean`	`true`	Enable semantic tool retrieval. When enabled, only the most relevant tools are injected into each LLM call.
`top_k`	`number`	`25`	Maximum number of tools to retrieve per LLM call.
`always_include`	`string[]`	see below	Tool name patterns that are always included regardless of relevance. Supports prefix glob with `*`.
`skip_unlimited_providers`	`boolean`	`false`	When `true`, skips Tool RAG entirely for providers with no tool count limit (e.g. Anthropic).

Default always_include patterns:

tool_rag defaults

tool_rag:
  enabled: true
  top_k: 25
  always_include:
    - telegram_send_message
    - telegram_reply_message
    - telegram_send_photo
    - telegram_send_document
    - "journal_*"
    - "workspace_*"
    - "web_*"
  skip_unlimited_providers: false

deals

Escrow / deal engine settings for TON and Star Gift trades.

Key	Type	Default	Description
`enabled`	`boolean`	`true`	Enable the deal/escrow subsystem.
`expiry_seconds`	`number`	`120`	Seconds before an unpaid deal expires.
`buy_max_floor_percent`	`number`	`95`	Maximum buy price as a percentage of floor. Deals priced above this threshold are rejected.
`sell_min_floor_percent`	`number`	`105`	Minimum sell price as a percentage of floor. Deals priced below this threshold are rejected.
`poll_interval_ms`	`number`	`5000`	Milliseconds between payment verification polls.
`max_verification_retries`	`number`	`12`	Maximum number of payment verification attempts before marking a deal as failed.
`expiry_check_interval_ms`	`number`	`60000`	How often (ms) the expiry sweep runs to clean up stale deals.

webui

Optional HTTP dashboard. Disabled by default.

Key	Type	Default	Description
`enabled`	`boolean`	`false`	Start the WebUI HTTP server on launch.
`port`	`number`	`7777`	HTTP port to listen on.
`host`	`string`	`127.0.0.1`	Bind address. Keep as localhost unless you have a reverse proxy in front.
`auth_token`	`string`	auto	Bearer token for API authentication. Auto-generated on first launch if omitted.
`cors_origins`	`string[]`	`["http://localhost:5173", "http://localhost:7777"]`	Allowed CORS origins (for development).
`log_requests`	`boolean`	`false`	Log every HTTP request to the Pino logger.

capabilities

Controls powerful system-level capabilities. The exec sub-section governs shell command execution.

capabilities.exec

Key	Type	Default	Description
`mode`	`string`	`off`	Exec mode. `off` disables shell access entirely. `yolo` grants the agent full system access via `exec_shell` and `exec_script` tools.
`scope`	`string`	`admin-only`	Who can trigger exec tools. One of `admin-only`, `allowlist`, `all`.
`allowlist`	`number[]`	`[]`	Telegram user IDs allowed to use exec when `scope: allowlist`.
`limits.timeout`	`number`	`120`	Maximum seconds a single command may run (1–3600).
`limits.max_output`	`number`	`50000`	Maximum characters of stdout/stderr captured per command (1000–500000).
`audit.log_commands`	`boolean`	`true`	Log every executed command to the SQLite `exec_audit` table.

capabilities section example

capabilities:
  exec:
    mode: off       # change to "yolo" to enable shell access
    scope: admin-only
    allowlist: []
    limits:
      timeout: 120
      max_output: 50000
    audit:
      log_commands: true

mcp

Connect external Model Context Protocol servers to extend the agent with additional tools. Supports both stdio (subprocess) and SSE/HTTP transports.

Key	Type	Default	Description
`servers`	`Record<string, McpServer>`	`{}`	Map of server name to server config. The name is used as a tool namespace prefix.

mcp.servers.<name>

Key	Type	Default	Description
`command`	`string`	—	Stdio launch command, e.g. `npx @modelcontextprotocol/server-filesystem /tmp`. Either `command` or `url` is required.
`args`	`string[]`	—	Explicit argument array (overrides splitting of `command`).
`env`	`Record<string, string>`	—	Extra environment variables passed to the stdio subprocess.
`url`	`string`	—	SSE or HTTP endpoint URL for remote servers (alternative to `command`).
`scope`	`string`	`always`	When to include the server's tools. One of `always`, `dm-only`, `group-only`, `admin-only`.
`enabled`	`boolean`	`true`	Enable or disable this server without removing it from config.

mcp section example

mcp:
  servers:
    filesystem:
      command: "npx @modelcontextprotocol/server-filesystem /home/user/data"
      scope: admin-only
    my_remote_server:
      url: "https://mcp.example.com/sse"
      scope: always
      enabled: true

plugins

Per-plugin configuration. The top-level key is the plugin's name with hyphens replaced by underscores. Each plugin defines its own accepted keys.

plugins section example

plugins:
  my_plugin:
    some_option: true
    api_key: "abc123"

Access from within a plugin via sdk.config. See the Plugin SDK reference for details.

Top-level keys

These keys sit at the root of the config file alongside the sections above.

Key	Type	Default	Description
`tonapi_key`	`string`	—	TonAPI key for higher rate limits. Obtain from @tonapi_bot.
`toncenter_api_key`	`string`	—	TonCenter API key for a dedicated RPC endpoint. Free at toncenter.com.
`tavily_api_key`	`string`	—	Tavily API key for web search and extract tools. Free tier at tavily.com.
`cocoon.port`	`number`	`10000`	HTTP port of an externally running `cocoon-cli` proxy. Only required when `agent.provider: cocoon`.

dev

Developer-mode options.

Key	Type	Default	Description
`hot_reload`	`boolean`	`false`	Watch `~/.teleton/plugins/` for file changes and automatically reload plugins without restarting.

Environment Variables

The following environment variables are recognised. Most map directly to config keys and take precedence over the YAML file.

Variable	Description
`TELETON_HOME`	Override the default config directory (`~/.teleton`).
`TELETON_CONFIG`	Explicit path to the config YAML file.
`TELETON_AGENT_API_KEY`	Override `agent.api_key`.
`TELETON_AGENT_MODEL`	Override `agent.model`.
`TELETON_AGENT_PROVIDER`	Override `agent.provider`.
`ANTHROPIC_API_KEY`	API key for the `anthropic` provider (standard Anthropic env var).
`OPENAI_API_KEY`	API key for the `openai` provider.
`GOOGLE_API_KEY`	API key for the `google` provider (Gemini).
`XAI_API_KEY`	API key for the `xai` provider (Grok).
`GROQ_API_KEY`	API key for the `groq` provider.
`OPENROUTER_API_KEY`	API key for the `openrouter` provider.
`MOONSHOT_API_KEY`	API key for the `moonshot` provider (Kimi).
`MISTRAL_API_KEY`	API key for the `mistral` provider.
`CEREBRAS_API_KEY`	API key for the `cerebras` provider.
`ZAI_API_KEY`	API key for the `zai` provider.
`MINIMAX_API_KEY`	API key for the `minimax` provider.
`HUGGINGFACE_API_KEY`	API key for the `huggingface` provider.
`TAVILY_API_KEY`	Tavily web search API key (overrides `tavily_api_key`).
`TONAPI_KEY`	TonAPI key (overrides `tonapi_key`).
`TONCENTER_API_KEY`	TonCenter API key (overrides `toncenter_api_key`).

Full Example config.yaml

A complete configuration file with all sections. Copy this as a starting point and remove what you don't need.

~/.teleton/config.yaml

meta:
  version: "1.0.0"

agent:
  provider: anthropic
  api_key: "sk-ant-api03-..."
  model: claude-opus-4-6
  max_tokens: 4096
  temperature: 0.7
  max_agentic_iterations: 5
  session_reset_policy:
    daily_reset_enabled: true
    daily_reset_hour: 4
    idle_expiry_enabled: true
    idle_expiry_minutes: 1440

telegram:
  api_id: 12345678
  api_hash: "abcdef1234567890abcdef1234567890"
  phone: "+14155552671"
  session_name: teleton_session
  session_path: ~/.teleton
  dm_policy: allowlist
  allow_from: [123456789]
  group_policy: open
  group_allow_from: []
  require_mention: true
  max_message_length: 4096
  typing_simulation: true
  rate_limit_messages_per_second: 1.0
  rate_limit_groups_per_minute: 20
  admin_ids: [123456789]
  agent_channel: null
  owner_name: "Alex"
  owner_username: "alexdev"
  owner_id: 123456789
  debounce_ms: 1500

storage:
  sessions_file: ~/.teleton/sessions.json
  memory_file: ~/.teleton/memory.json
  history_limit: 100

embedding:
  provider: local

logging:
  level: info
  pretty: true

tool_rag:
  enabled: true
  top_k: 25
  always_include:
    - telegram_send_message
    - telegram_reply_message
    - telegram_send_photo
    - telegram_send_document
    - "journal_*"
    - "workspace_*"
    - "web_*"
  skip_unlimited_providers: false

deals:
  enabled: true
  expiry_seconds: 120
  buy_max_floor_percent: 95
  sell_min_floor_percent: 105
  poll_interval_ms: 5000
  max_verification_retries: 12
  expiry_check_interval_ms: 60000

webui:
  enabled: false
  port: 7777
  host: 127.0.0.1
  log_requests: false

capabilities:
  exec:
    mode: off
    scope: admin-only
    allowlist: []
    limits:
      timeout: 120
      max_output: 50000
    audit:
      log_commands: true

mcp:
  servers: {}

dev:
  hot_reload: false

plugins: {}

tonapi_key: ""
toncenter_api_key: ""
tavily_api_key: ""