Autonomous AI agent platform for Telegram with native TON blockchain integration

Teleton is an autonomous AI agent for Telegram (user account or bot). It loops with tools, keeps hybrid RAG memory, and talks to TON from chat. It ships with 131 always-registered tools plus 5 optional system tools, 16 LLM providers, and a Plugin SDK.

_` (e.g. `mcp_filesystem_read_file`). Each server supports `scope` (always, dm-only, group-only, admin-only) and `enabled` toggle. ### Environment Variables All environment variables override the corresponding `config.yaml` value at startup - useful for Docker and CI: | Variable | Description | Default | |----------|-------------|---------| | `TELETON_HOME` | Data directory (config, DB, session) | `~/.teleton` | | `TELETON_API_KEY` | LLM API key | - | | `TELETON_BASE_URL` | Custom LLM base URL | - | | `TELETON_TG_API_ID` | Telegram API ID | - | | `TELETON_TG_API_HASH` | Telegram API Hash | - | | `TELETON_TG_PHONE` | Phone number | - | | `TELETON_TAVILY_API_KEY` | Tavily API key for web tools | - | | `TELETON_TONAPI_KEY` | TonAPI key | - | | `TELETON_TONCENTER_API_KEY` | Toncenter API key | - | | `TELETON_WEBUI_ENABLED` | Enable WebUI | `false` | | `TELETON_WEBUI_PORT` | WebUI port | `7777` | | `TELETON_WEBUI_HOST` | WebUI bind address | `127.0.0.1` | | `TELETON_API_ENABLED` | Enable Management API | `false` | | `TELETON_API_PORT` | Management API port | `7778` | | `TELETON_LOG_LEVEL` | Log level (debug, info, warn, error) | `info` | --- ## WebUI Dashboard Optional web dashboard, localhost only, token auth. Start with `teleton start --webui` or `teleton setup --ui`.

Dashboard Live agent activity, model, token usage, access policy	Tools Toggle, scope, per-module	Plugins Marketplace, install, secrets	System Prompt SOUL, SECURITY, STRATEGY, MEMORY, HEARTBEAT
Memory Search and read full Markdown files, expandable metadata	Logs Dedicated page with real-time SSE streaming	Workspace File browser + editor	MCP Servers Add, remove, configure
TON Proxy (in Config) Start/stop, auto-install	Tasks Schedule, dependencies, bulk	Setup Wizard QR code + phone auth	Config Provider switch, key validation
Hooks Plugin hook registrations	Chats Conversation history and Telegram profile photos	Wallet GRAM balance, address, transaction history

The dashboard shows daily, weekly, and 30-day token activity, alongside recent conversations with Telegram names and profile photos. The full authenticated URL is printed at startup. `teleton start --webui` also opens it in the default browser. The token is exchanged for an HttpOnly cookie valid for 7 days. For remote access: ```bash ssh -L 7777:localhost:7777 user@remote-server ``` ### Coding Agent By default, the agent has a **sandboxed workspace** at `~/.teleton/workspace/` with 6 file tools (read, write, delete, rename, list, info). Path traversal protection, symlink detection, and 500 MB quota. Core files (`SOUL.md`, `STRATEGY.md`, `SECURITY.md`) are immutable. Write operations are DM-only. **YOLO mode** unlocks full system access (off by default, Linux only): | Tool | Description | |------|-------------| | `exec_run` | Execute any bash command | | `exec_install` | Install packages (apt, pip, npm, docker) | | `exec_service` | Manage systemd services | | `exec_status` | Server health (disk, RAM, CPU, uptime) | All commands are audit-logged with user, command, output, exit code, and duration. Configurable timeout (default 120s), scope (`admin-only`, `allowlist`, `all`), and output capture limit. ```yaml capabilities: exec: mode: "yolo" # off | yolo scope: "admin-only" # admin-only | allowlist | all limits: timeout: 120 # seconds (1-3600) ``` ### Admin Commands All admin commands support `/`, `!`, or `.` prefix: | Command | Description | |---------|-------------| | `/status` | Uptime, model, sessions, wallet, policies | | `/model ` | Hot-swap LLM model at runtime | | `/policy ` | Change access policies live | | `/loop <1-50>` | Set max agentic iterations | | `/wallet` | Show wallet address + balance | | `/modules set\|info\|reset` | Per-group tool permissions | | `/plugin set\|unset\|keys` | Manage plugin secrets | | `/task ` | Assign a task to the agent | | `/boot` | Run bootstrap template | | `/pause` / `/resume` | Pause/resume agent | | `/clear [chat_id]` | Clear conversation history | | `/verbose` | Toggle debug logging | | `/rag [status\|topk ]` | Toggle Tool RAG or view status | | `/guest [on\|off]` | View or toggle bot guest mode | | `/stop` | Emergency shutdown | | `/ping` | Check responsiveness | | `/help` | Show all commands | --- ## Plugins Extend the agent with custom tools. Install from the WebUI marketplace in one click, or drop a `.js` file in `~/.teleton/plugins/`. Loaded at startup, no rebuild needed. See [official example plugins](https://github.com/TONresistor/teleton-plugins). ``` ~/.teleton/plugins/ ├── weather.js # Single-file plugin └── my-plugin/ ├── index.js # Folder plugin ├── package.json # npm deps (auto-installed via npm ci) └── package-lock.json ``` Plugins export a `tools` function (recommended) or array, plus optional lifecycle hooks: ```js // ~/.teleton/plugins/weather.js export const manifest = { name: "weather", version: "1.0.0", sdkVersion: "^2.0.0", }; // Optional: creates an isolated database at ~/.teleton/plugins/data/weather.db export function migrate(db) { db.exec(`CREATE TABLE IF NOT EXISTS weather_cache ( city TEXT PRIMARY KEY, data TEXT, cached_at INTEGER )`); } // Required: tools as a function receiving the Plugin SDK export const tools = (sdk) => [ { name: "weather_get", description: "Get current weather for a city", parameters: { type: "object", properties: { city: { type: "string", description: "City name" } }, required: ["city"], }, execute: async (params) => { sdk.log.info(`Fetching weather for ${params.city}`); const res = await fetch(`https://wttr.in/${params.city}?format=j1`); if (!res.ok) return { success: false, error: "City not found" }; const data = await res.json(); return { success: true, data: { temp: data.current_condition[0].temp_C } }; }, }, ]; ``` ### Plugin SDK The SDK provides namespaced access to core services: | Namespace | Methods | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sdk.ton` | **Wallet**: `getAddress()`, `getBalance()`, `getPrice()`, `sendTON()`, `getTransactions()`, `verifyPayment()` | | | **Jettons**: `getJettonBalances()`, `getJettonInfo()`, `sendJetton()`, `getJettonWalletAddress()` | | | **Analytics**: `getJettonPrice()`, `getJettonHolders()`, `getJettonHistory()` | | | **NFT**: `getNftItems()`, `getNftInfo()` | | | **DEX** (`sdk.ton.dex`): `quote()`, `swap()`, `quoteSTONfi()`, `quoteDeDust()`, `swapSTONfi()`, `swapDeDust()` | | | **DNS** (`sdk.ton.dns`): `check()`, `resolve()`, `getAuctions()`, `startAuction()`, `bid()`, `link()`, `unlink()`, `setSiteRecord()` | | | **Signed Transfers**: `createTransfer()`, `createJettonTransfer()`, `getPublicKey()`, `getWalletVersion()` | | | **Utils**: `toNano()`, `fromNano()`, `validateAddress()` | | `sdk.telegram` | **Messages**: `sendMessage()`, `editMessage()`, `deleteMessage()`, `forwardMessage()`, `pinMessage()`, `searchMessages()`, `scheduleMessage()`, `getScheduledMessages()`, `deleteScheduledMessage()`, `sendScheduledNow()`, `getReplies()` | | | **Media**: `sendPhoto()`, `sendVideo()`, `sendVoice()`, `sendFile()`, `sendGif()`, `sendSticker()`, `downloadMedia()` | | | **Chat & Users**: `getChatInfo()`, `getUserInfo()`, `resolveUsername()`, `getParticipants()`, `getDialogs()`, `getHistory()` | | | **Interactive**: `sendDice()`, `sendReaction()`, `createPoll()`, `createQuiz()` | | | **Moderation**: `banUser()`, `unbanUser()`, `muteUser()`, `kickUser()` | | | **Stars & Gifts**: `getStarsBalance()`, `sendGift()`, `getAvailableGifts()`, `getMyGifts()`, `getResaleGifts()`, `buyResaleGift()`, `getStarsTransactions()`, `transferCollectible()`, `setCollectiblePrice()`, `getCollectibleInfo()`, `getUniqueGift()`, `getUniqueGiftValue()`, `sendGiftOffer()` | | | **Advanced**: `getMe()`, `getMessages()`, `isAvailable()`, `setTyping()`, `sendStory()` | | `sdk.bot` | `onInlineQuery()`, `onCallback()`, `onChosenResult()`, `editInlineMessage()`, `keyboard()`, `isAvailable`, `username` | | `sdk.secrets` | `get()`, `require()`, `has()` | | `sdk.storage` | `get()`, `set()`, `delete()`, `has()`, `clear()` (KV with TTL) | | `sdk.db` | Raw `better-sqlite3` database, isolated per plugin | | `sdk.config` | Sanitized app config (no API keys) | | `sdk.pluginConfig` | Plugin-specific config from `config.yaml` | | `sdk.log` | `info()`, `warn()`, `error()`, `debug()` | | `sdk.on()` | Register hooks: `tool:before`, `tool:after`, `tool:error`, `prompt:before`, `prompt:after`, `session:start`, `session:end`, `message:receive`, `response:before`, `response:after`, `response:error`, `agent:start`, `agent:stop` | **Lifecycle hooks**: `migrate(db)`, `start(ctx)` (with `ctx.sdk`), `stop()`, `onMessage(event)`, `onCallbackQuery(event)` **Security**: all SDK objects are frozen. Plugins never see API keys or other plugins' data. --- ## Architecture ### Tech Stack | Layer | Technology | |-------|------------| | LLM | Multi-provider via [pi-ai](https://github.com/mariozechner/pi-ai) (16 providers: Anthropic, Codex, Grok Build, OpenAI, Google, xAI, Groq, OpenRouter, Moonshot, Mistral, Cerebras, ZAI, MiniMax, Hugging Face, Gocoon, Local) | | Telegram Userbot | [GramJS](https://gram.js.org/) Layer 229 fork (MTProto) | | Inline Bot | [Grammy](https://grammy.dev/) (Bot API, plugin inline cards and callbacks) | | Blockchain | [TON SDK](https://github.com/ton-org/ton) (W5R1 wallet) | | DeFi | STON.fi SDK, DeDust SDK | | Database | [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) with WAL mode | | Vector Search | [sqlite-vec](https://github.com/asg017/sqlite-vec) (cosine similarity) | | Full-Text Search | SQLite FTS5 (BM25 ranking) | | Embeddings | [@huggingface/transformers](https://www.npmjs.com/package/@huggingface/transformers) (local ONNX) or Voyage AI | | MCP Client | [@modelcontextprotocol/sdk](https://modelcontextprotocol.io/) (stdio + SSE + Streamable HTTP) | | WebUI | [Hono](https://hono.dev/) (API) + React + Vite (frontend) | | Language | TypeScript 5.9, Node.js `^22.22.2`, `^24.15.0`, or `>=26.0.0` | ### Project Structure ``` src/ ├── index.ts # Entry point, TeletonApp lifecycle, graceful shutdown ├── agent/ # Core agent runtime │ ├── runtime.ts # Budgeted agentic loop, tool calling, masking, compaction │ ├── client.ts # Multi-provider LLM client │ └── tools/ # 131 base tools plus 5 optional system tools │ ├── register-all.ts # Central tool registration (9 categories) │ ├── registry.ts # Tool registry, scope filtering, provider limits │ ├── module-loader.ts # Built-in module loading (TON Proxy + exec) │ ├── plugin-loader.ts # External plugin discovery, validation, hot-reload │ ├── mcp-loader.ts # MCP client (stdio/SSE), tool discovery, lifecycle │ ├── telegram/ # Telegram operations (85 tools) │ ├── ton/ # TON blockchain + jettons + DEX router (15 tools) │ ├── stonfi/ # STON.fi DEX (5 tools) │ ├── dedust/ # DeDust DEX (5 tools) │ ├── dns/ # TON DNS (8 tools) │ ├── exec/ # System execution — YOLO mode (4 tools) │ ├── journal/ # Business journal (3 tools) │ └── workspace/ # File operations (6 tools) ├── bot/ # Plugin inline-query and callback routing │ ├── inline-router.ts # Namespaced plugin inline handlers │ ├── callback-router.ts # Nonce-based callback dispatch │ ├── gramjs-bot.ts # Userbot-to-bot inline transport │ └── services/ # Shared inline transport ├── telegram/ # Telegram integration layer │ ├── bridge.ts # GramJS wrapper (peer cache, message parsing, keyboards) │ ├── handlers.ts # Message routing, rate limiting, ChatQueue, feed storage │ ├── admin.ts # Runtime admin commands │ ├── debounce.ts # Message batching for groups │ ├── formatting.ts # Markdown → Telegram HTML │ ├── task-executor.ts # Scheduled task runner │ ├── task-dependency-resolver.ts # DAG-based task chains │ └── callbacks/ # Inline button routing ├── memory/ # Storage and knowledge │ ├── schema.ts # 16 tables, 42 indexes/triggers, FTS5, vec0, semver migrations │ ├── database.ts # SQLite + WAL + sqlite-vec │ ├── search/ # RAG system (hybrid vector + BM25 fusion via RRF) │ ├── embeddings/ # Local ONNX + Voyage AI + caching provider │ ├── compaction.ts # Context auto-compaction with AI summarization │ ├── observation-masking.ts # Tool result compression (~90% savings) │ └── daily-logs.ts # Automatic session summaries ├── ton/ # TON blockchain │ ├── wallet-service.ts # W5R1 wallet, PBKDF2 key caching, encrypted storage │ ├── transfer.ts # TON send operations │ └── payment-verifier.ts # On-chain payment verification with replay protection ├── ton-proxy/ # TON Proxy module (Tonutils-Proxy lifecycle) │ ├── manager.ts # Binary download, start/stop, PID file, health checks │ ├── module.ts # Module lifecycle integration │ └── tools.ts # ton_proxy_status tool ├── sdk/ # Plugin SDK (v2.1.0) │ ├── index.ts # SDK factory (createPluginSDK, all objects frozen) │ ├── ton.ts # TON service for plugins │ ├── telegram.ts # Telegram service for plugins │ ├── secrets.ts # 3-tier secret resolution (env → file → config) │ └── storage.ts # KV store with TTL ├── session/ # Session management │ ├── store.ts # Session persistence (SQLite, daily reset, idle expiry) │ └── transcript.ts # JSONL conversation transcripts ├── soul/ # System prompt assembly │ └── loader.ts # 10 sections: soul + security + strategy + memory + context + ... ├── config/ # Configuration │ ├── schema.ts # Zod schemas + validation │ ├── providers.ts # Multi-provider LLM registry (16 providers) │ └── model-catalog.ts # Shared model catalog (70+ models across all providers) ├── webui/ # Optional web dashboard │ ├── server.ts # Hono server, auth middleware, static serving │ └── routes/ # 14 route groups (status, tools, logs, memory, soul, plugins, mcp, tasks, workspace, config, marketplace, hooks, ton-proxy, setup) ├── api/ # Management API (HTTPS control plane) │ ├── server.ts # Hono HTTPS server, TLS, middleware stack │ ├── bootstrap.ts # API-only mode (no config needed) │ ├── middleware/ # Auth, rate-limit, audit, request-id │ └── routes/ # Agent lifecycle, system, logs, memory, auth ├── constants/ # Centralized limits, timeouts, API endpoints ├── utils/ # Logger, sanitize, retry, fetch ├── workspace/ # Path validator (anti-traversal, anti-symlink) ├── templates/ # Workspace template files (SOUL.md, etc.) └── cli/ # CLI commands (setup, config, doctor, mcp) web/ # React + Vite frontend (11 pages) packages/sdk/ # Published @teleton-agent/sdk ``` --- ## Security ### Multi-Layer Defense | Layer | Protection | |-------|-----------| | **Prompt injection** | `sanitizeForPrompt()` strips control chars, invisible unicode, markdown injection. `sanitizeForContext()` for RAG results | | **Immutable config** | SOUL.md, STRATEGY.md, SECURITY.md cannot be modified by the agent | | **Workspace sandbox** | Agent confined to `~/.teleton/workspace/`, recursive URL decoding blocks double-encoding attacks, symlinks detected and blocked | | **Plugin isolation** | Frozen SDK objects, sanitized config (no API keys), isolated per-plugin databases, `npm ci --ignore-scripts` | | **Wallet protection** | File permissions `0o600`, KeyPair cached (single PBKDF2), mnemonic never exposed to plugins | | **Memory protection** | Memory writes blocked in group chats to prevent poisoning | | **Payment security** | Verified payment hashes are recorded with `INSERT OR IGNORE`, preventing replay of the same transaction | | **Exec audit** | All YOLO mode commands logged to `exec_audit` table with user, command, output, and timestamps | | **Pino redaction** | Structured logging with automatic redaction of apiKey, password, secret, token, mnemonic fields | | **Tool access control** | Per-tool access level (all, allow-list, admin, off), DM vs group gated by global policies, per-group module permissions, all runtime-configurable | ### Reporting Vulnerabilities Do not open public issues for security vulnerabilities. Contact maintainers (t.me/zkproof) directly or use GitHub's private security advisory feature. ### Best Practices 1. Use a dedicated Telegram account 2. Backup your 24-word mnemonic securely offline 3. Start with restrictive policies (`admin-only` or `allowlist`) 4. Set file permissions: `chmod 600 ~/.teleton/wallet.json` 5. Never commit `config.yaml` to version control 6. Review `SECURITY.md` and customize for your use case --- ## Development ### Setup ```bash git clone https://github.com/TONresistor/teleton-agent.git cd teleton-agent npm install npm run setup npm run dev # Watch mode with auto-restart ``` ### Commands ```bash npm run build # SDK → backend (tsup) → frontend (vite) npm run start # Start agent (compiled) npm run dev # Development mode (watch, tsx) npm run dev:web # Frontend dev server (port 5173, proxied to 7777) npm run setup # Run setup wizard npm run doctor # Health checks npm run typecheck # Type checking npm run lint # ESLint npm run test # Vitest npm run format # Prettier ``` --- ## Documentation Full documentation is available in the [`docs/`](docs/) directory: | Section | Description | |---------|-------------| | [Configuration Guide](docs/configuration.md) | Complete reference for every config option | | [Deployment Guide](docs/deployment.md) | Docker, systemd, docker-compose, VPS | | [Plugin Development](docs/plugins.md) | Step-by-step plugin tutorial | | [Telegram Setup](docs/telegram-setup.md) | API credentials, policies, 2FA, admin commands | | [TON Wallet](docs/ton-wallet.md) | Wallet setup, DEX trading, security | | [Management API](docs/management-api.md) | HTTPS API, bootstrap mode, authentication, endpoints | --- ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide. 1. Fork the repository 2. Create a feature branch from `dev` 3. Make your changes 4. Verify: `npm run typecheck && npm run lint && npm test` 5. Open a Pull Request against `dev` --- ## Contributors --- ## License MIT License - See [LICENSE](LICENSE) for details. --- ## Credits ### Built With - [pi-ai](https://github.com/mariozechner/pi-ai) - Multi-provider LLM SDK - [GramJS](https://gram.js.org/) - Telegram MTProto library - [Grammy](https://grammy.dev/) - Telegram Bot API framework - [TON SDK](https://github.com/ton-org/ton) - TON blockchain client - [STON.fi SDK](https://www.npmjs.com/package/@ston-fi/sdk) - DEX integration - [DeDust SDK](https://www.npmjs.com/package/@dedust/sdk) - DEX integration - [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) - Model Context Protocol client - [sqlite-vec](https://github.com/asg017/sqlite-vec) - Vector search for SQLite - [Hono](https://hono.dev/) - Lightweight web framework - [Tonutils-Proxy](https://github.com/xssnick/Tonutils-Proxy) - TON Proxy for .ton sites --- ## Support - **Issues**: [GitHub Issues](https://github.com/TONresistor/teleton-agent/issues) - **Channel**: [@teletonagents](https://t.me/teletonagents) - **Group Chat**: [@teletonagentHQ](https://t.me/teletonagentHQ) - **Contact**: [@zkproof](https://t.me/zkproof)