Frequently Asked Questions

Teleton is an autonomous AI agent that operates as a real Telegram user account (not a bot). It reasons through an agentic loop with tool calling, remembers conversations across sessions, and natively integrates the TON blockchain. It ships with 125+ built-in tools, supports 15 LLM providers (70+ models), and exposes a Plugin SDK to build your own tools.

Regular bots use the Bot API, which is limited in scope — they can't read chat history, manage contacts, or perform advanced actions. Teleton operates as a real user via MTProto (GramJS), giving it full access to the same capabilities a human has: reading conversations, sending media, managing groups, folders, stickers, gifts, stars, and more.

Yes. Teleton is open source under the MIT license. You only pay for the LLM provider you choose (Anthropic, OpenAI, etc.) based on your own usage. TON transaction fees are minimal (0.005–0.01 TON per transfer).

Teleton supports 6 providers: Anthropic (Claude), OpenAI (GPT), Google (Gemini), xAI (Grok), Groq (Llama), and OpenRouter (multi-model gateway). You can switch providers with a single config change or at runtime via the /model command.

Not to use it. The setup wizard guides you through configuration and the agent operates through natural language. Programming knowledge is only needed if you want to build custom plugins.

Node.js 20 or higher, a Telegram account (dedicated account recommended), Telegram API credentials from my.telegram.org, and an API key from at least one LLM provider. Works on Linux, macOS, and Windows.

Four methods: npm install -g teleton (recommended), a one-liner install script, Docker (ghcr.io/tonresistor/teleton-agent), or from source. After installation, run teleton setup to configure everything interactively.

LLM provider and API key, Telegram authentication (API credentials, phone, login code, optional 2FA), access policies (DM and group rules), admin user ID, TON wallet generation (W5R1 with 24-word mnemonic), and workspace initialization with template personality files.

Go to my.telegram.org/apps, log in, navigate to "API development tools", and create an application. You'll receive an api_id and api_hash. These credentials are permanent.

Yes. Teleton is designed to run headless. Use Docker or run directly with Node.js. It persists memory and state across restarts, so it can run 24/7 unattended. A systemd unit file template is included for production deployments.

Four policies control who can DM the agent: pairing (default — users must mutually pair first), allowlist (only specific user IDs), open (anyone can interact), and disabled (all DMs ignored). Change at runtime with /policy dm.

Three group policies: open (default — responds in any group), allowlist (only approved groups), and disabled. When require_mention is enabled (default), the agent only responds when mentioned by name or when someone replies to its messages.

Yes. Environment variables always take precedence over config.yaml. Key overrides include TELETON_API_KEY, TELETON_TG_API_ID, TELETON_WEBUI_ENABLED, and provider-specific keys like ANTHROPIC_API_KEY. Useful for CI/CD and Docker deployments.

Tool RAG uses semantic search to select only the most relevant tools per message (default: top 25 out of 100+). This reduces token usage for all providers and is essential for providers with tool count limits. Toggle it with the /rag admin command.

A W5R1 (Wallet V5 Revision 1) contract — the most modern TON wallet version with gas-optimized transfers. Generated during setup with a 24-word BIP39 mnemonic stored locally with restricted file permissions.

Yes, during setup you can import using a 24-word mnemonic. Since Teleton derives a W5R1 wallet, the address may differ from your original if it used a different contract version. Transfer your funds to the new address if needed.

About 0.05 TON to activate the wallet. For practical use: ~0.1 TON covers dozens of transfers, 1+ TON for DEX trading (swap gas is ~0.25–0.5 TON), and 0.5+ TON for NFT operations.

STON.fi and DeDust, with 5 tools each (swap, quote, search, pools, analytics). A smart dex_quote tool compares quotes from both exchanges in parallel and recommends the best rate.

All transaction signing happens locally — keys never leave your machine. The agent can send/receive TON, swap jettons, bid on DNS auctions, and manage NFTs. Financial tools are restricted to DM-only scope for safety.

Drop a JavaScript (ESM) file in the plugins folder and restart. Plugins export tool definitions and optionally lifecycle hooks, event handlers, and database migrations. Dependencies in a package.json are auto-installed.

A frozen SDK with namespaced services: sdk.ton (wallet, payments, NFT), sdk.telegram (53 messaging methods), sdk.secrets (3-tier secret resolution), sdk.storage (key-value with TTL), sdk.db (isolated SQLite), sdk.log (prefixed logger), and sdk.config.

Yes. Enable dev.hot_reload: true in config. The platform watches the plugins directory for changes and automatically reloads modified plugins without restarting the agent.

MCP (Model Context Protocol) connects external tool servers with no code. Add servers via CLI, config, or the WebUI. Tools are auto-discovered and registered. Both stdio and SSE transports are supported, with configurable scope per server.

Hybrid retrieval combining vector search (384-dimensional local ONNX embeddings) with full-text search (SQLite FTS5, BM25 ranking), fused via Reciprocal Rank Fusion. It indexes persistent memory, daily session logs, Telegram messages, and all workspace markdown files.

When conversation context approaches the token limit, the agent automatically summarizes using a utility model, archives the full transcript, and continues with fresh context. Observation masking also compresses old tool results, saving ~90% of context space.

Yes, with two built-in tools powered by Tavily (free tier available): web_search (returns results with relevance scores and topic filters) and web_fetch (extracts readable text from URLs).

Teleton uses the official MTProto protocol, the same one used by all Telegram clients. A dedicated account is recommended. As long as you don't spam or abuse the platform, your account remains safe.

The mnemonic is stored with 0600 file permissions (owner-only). Plugins access the wallet through a frozen SDK and cannot access private keys. Financial tools are restricted to DM scope. All addresses are validated before sending.

Multiple layers: input sanitization strips control characters and invisible Unicode, user messages are wrapped in tagged envelopes, personality files (SOUL.md, SECURITY.md) are immutable at runtime, and memory writes are blocked in group chats to prevent poisoning.

SDK objects are frozen. Plugins receive sanitized config with no API keys. Each plugin gets an isolated SQLite database. Dependencies are installed with npm ci --ignore-scripts to prevent install-time code execution.

Yes. Published on GitHub Container Registry at ghcr.io/tonresistor/teleton-agent. Multi-stage build on Node.js 20-slim, runs as non-root, stores data at /data, exposes port 7777 for the WebUI.

Back up the entire ~/.teleton/ directory. Critical files: config.yaml, wallet.json (sensitive), telegram_session/, memory.db, and workspace/. For Docker, stop the container first for consistency.

npm: npm update -g teleton. Docker: docker pull ghcr.io/tonresistor/teleton-agent:latest then recreate the container. From source: git pull && npm install && npm run build.

An optional web dashboard for monitoring and management: system status, tools management, plugin marketplace, soul editor, memory search, live log streaming, workspace file browser, MCP server management, and scheduled tasks. Enable with webui.enabled: true.

Binds to localhost only by default, uses bearer token authentication with timing-safe comparison, stores the token as an HttpOnly SameSite=Strict cookie, and supports CORS restrictions. For remote access, use SSH tunneling or a reverse proxy with HTTPS.