teleton-agent

Home > AI Agents > teleton-agent

Teleton: Autonomous AI Agent for Telegram & TON Blockchain

ai-agent autonomous-agent gramjs llm nodejs open-source plugin-sdk rag typescript

Why this rank:Strong adoptionRelease freshnessHealthy release cadence

Description

Teleton: Autonomous AI Agent for Telegram & TON Blockchain

README

Autonomous AI agent platform for Telegram with native TON blockchain integration

Teleton is an autonomous AI agent platform that operates as a real Telegram user account or a Telegram Bot. It thinks through an agentic loop with tool calling, remembers conversations across sessions with hybrid RAG, and natively integrates the TON blockchain: send crypto, swap on DEXs, bid on domains, verify payments - all from a chat message. It can schedule tasks to run autonomously at any time. It ships with 135+ built-in tools, supports 15 LLM providers, and exposes a Plugin SDK so you can build your own tools on top of the platform.

Key Highlights

Full Telegram Access Real user via MTProto, not a bot	Agentic Loop Think, act, observe, repeat until shit gets done	15 LLM Providers Anthropic, OpenAI, Google, xAI, Groq, and more
TON Blockchain Wallet, jettons, DEX swaps, DNS, NFTs	Persistent Memory Hybrid RAG, vector + keyword, auto-compaction	135+ Built-in Tools Messaging, media, crypto, DEX, DNS, files
Plugin SDK Custom tools, isolated DBs, secrets, hooks	MCP Client Connect any MCP tool server	Secure by Design Sandbox, plugin isolation, prompt defense

Features

Tool Categories

Category	Tools	Description
Telegram	80	Messages, media, chats, polls, stickers, gifts, stars, stories
TON & Jettons	15	Wallet, send/receive, balances, prices, NFTs, DEX router
STON.fi DEX	5	Swap, quote, search, trending, pools
DeDust DEX	5	Swap, quote, pools, prices, token analytics
TON DNS	8	Auctions, bidding, linking, TON Sites, resolution
Deals	5	P2P escrow, on-chain verification, anti double-spend
Journal	3	Trade logging, P&L tracking, natural language queries
Web	2	Search and page extraction via Tavily
Workspace	6	Sandboxed file operations, path traversal protection
Exec	4	Shell, files, processes (off by default, admin-only)
Bot	1	Inline bot message sending for plugin interactions

Advanced Capabilities

Capability	Description
Multi-Provider LLM	15 providers, hot-swap from dashboard or CLI
RAG + Hybrid Search	Vector (sqlite-vec) + keyword (FTS5) fused search
Auto-Compaction	AI summarizes old context, saves to `memory/*.md`
Observation Masking	Compresses old tool results, saves ~90% context
Plugin SDK	Frozen SDK, isolated DBs, secrets, lifecycle hooks
Smart DEX Router	Compares STON.fi vs DeDust, picks best rate
Vision Analysis	Image understanding via utility model
Scheduled Tasks	Cron-like tasks with dependency chains
Message Debouncing	Batches rapid group messages, DMs stay instant
Daily Logs	Auto session summaries, persisted across resets
Multi-Policy Access	DM/group policies (open, allowlist, admin-only, disabled), per-group
Tool RAG	Sends only top-K relevant tools per message
MCP Client	stdio, SSE, Streamable HTTP, auto-discovery, CLI or WebUI
System Execution	YOLO mode: shell, files, processes (off by default, admin-only)
TON Proxy	Browse .ton domains via HTTP proxy, auto-installed
Management API	HTTPS control plane for remote admin, bootstrap mode, lifecycle control
Sandboxed Workspace	Path traversal protection, symlink detection, immutable configs
Heartbeat	Autonomous periodic wake-up, HEARTBEAT.md task checklist, configurable intervals

Prerequisites

Node.js 20.0.0+ - Download
LLM API Key - One of: Anthropic (recommended), OpenAI, Google, xAI, Groq, OpenRouter, Moonshot, Mistral, Cerebras, ZAI, MiniMax, Hugging Face — or keyless: Claude Code (auto-detect), Cocoon (TON), Local (Ollama/vLLM)
Telegram Account - Dedicated account recommended for security
Telegram API Credentials - From my.telegram.org/apps
Your Telegram User ID - Message @userinfobot
Bot Token (optional) - From @BotFather for inline bot features (deals)

Security Warning: The agent will have full control over the Telegram account. Use a dedicated account, not your main one.

Quick Start

1. Installation

npm (recommended):

npm install -g teleton@latest

Docker:

docker run -it -v ~/.teleton:/data ghcr.io/tonresistor/teleton-agent:latest setup

From source (development):

git clone https://github.com/TONresistor/teleton-agent.git
cd teleton-agent
npm install && npm run build

2. Setup & Start

teleton setup --ui

The WebUI wizard walks you through everything: LLM provider, Telegram auth (QR code or phone), access policies, admin ID, TON wallet, and workspace files. Once done, the agent starts automatically.

To restart later with the dashboard:

teleton start --webui

3. Verify

Send a message to your agent on Telegram:

You: /ping
Agent: Pong! I'm alive.

You: /status
Agent: [Displays uptime, model, tool count, wallet balance]

Need more details? See GETTING_STARTED.md for the full guide - admin commands, troubleshooting, workspace templates, plugins, and more.

User Mode vs Bot Mode

Teleton can run as a user account (MTProto) or a Telegram bot (Bot API). Set telegram.mode in your config:

	User Mode (default)	Bot Mode
Auth	Phone + api_id + api_hash	Bot token from @BotFather
Protocol	MTProto (GramJS)	Bot API (Grammy)
Tools	135+	67 (11 Telegram + 56 non-Telegram)
Risk	Account ban possible	No ban risk
Dialogs/History	Full access	Not available
Media sending	All types	Photos only (v1)
Inline keyboards	Via bot_token	Native
Stars/Gifts	Full access	Not available
Profile editing	Yes	No
Scheduled tasks	Yes	Not available
Setup	`telegram.mode: "user"`	`telegram.mode: "bot"`

Configuration

The teleton setup wizard generates a fully configured ~/.teleton/config.yaml file. Manual editing is only necessary if you want to adjust settings after the initial setup.

agent:
  provider: "anthropic"              # anthropic | claude-code | openai | google | xai | groq | openrouter | moonshot | mistral | cerebras | zai | minimax | huggingface | cocoon | local
  api_key: "sk-ant-api03-..."
  model: "claude-haiku-4-5-20251001"
  utility_model: "claude-haiku-4-5-20251001"  # for summarization, compaction, vision
  max_agentic_iterations: 5
  session_reset_policy:
    daily_reset_enabled: true
    daily_reset_hour: 4
    idle_expiry_minutes: 1440  # 24h idle → new session

telegram:
  dm_policy: "admin-only"   # open | allowlist | admin-only | disabled
  group_policy: "open"      # open | allowlist | admin-only | disabled
  require_mention: true
  admin_ids: [123456789]
  owner_name: "Your Name"
  owner_username: "your_username"
  debounce_ms: 1500         # group message batching delay

  # Optional: inline bot for interactive features (deals)
  bot_token: "123456:ABC-DEF..."
  bot_username: "your_bot"

webui:                       # Optional: Web dashboard
  enabled: false             # Enable WebUI server
  port: 7777                 # HTTP server port
  host: "127.0.0.1"          # Localhost only (security)
  # auth_token: "..."        # Auto-generated if omitted

ton_proxy:                   # Optional: .ton domain proxy
  enabled: false             # Enable Tonutils-Proxy
  port: 8080                 # HTTP proxy port
  # binary_path: "..."       # Custom binary path (auto-downloaded if omitted)

# capabilities:                # System execution (YOLO mode, off by default)
#   exec:
#     mode: "off"              # off | yolo
#     scope: "admin-only"      # admin-only | allowlist | all

Supported Models

70+ models across 15 providers. Defined in src/config/model-catalog.ts, shared across CLI, WebUI, and Dashboard.

Anthropic Claude Opus 4.6	Claude Code Auto-detected	OpenAI GPT-5	Google Gemini 3 Pro	xAI Grok 4.1
Groq Llama 4 Maverick	OpenRouter Multi-provider	Moonshot Kimi K2.5	Mistral Devstral	Cerebras Qwen 3 235B
ZAI GLM-5	MiniMax M2.5	Hugging Face DeepSeek V3.2	Cocoon Decentralized (TON)	Local Ollama, vLLM, LM Studio

MCP Servers

Connect external tool servers via the Model Context Protocol. No code needed - tools are auto-discovered and registered at startup.

Via CLI (recommended):

teleton mcp add @modelcontextprotocol/server-filesystem /tmp
teleton mcp add @openbnb/mcp-server-airbnb
teleton mcp list
teleton mcp remove filesystem

Via config.yaml:

mcp:
  servers:
    filesystem:
      command: npx -y @modelcontextprotocol/server-filesystem /tmp
    brave:
      command: npx -y @modelcontextprotocol/server-brave-search
      env:
        BRAVE_API_KEY: "sk-xxx"
    remote:
      url: http://localhost:3001/mcp
      scope: admin-only

Via WebUI:

When the WebUI is enabled, the MCP Servers page lets you add/remove servers, configure environment variables (API keys), and view connection status and tool lists - all from the browser.

Tools are namespaced as mcp_<server>_<tool> (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 Status, model, tokens, config	Tools Toggle, scope, per-module	Plugins Marketplace, install, secrets	Soul Editor SOUL, SECURITY, STRATEGY, MEMORY
Memory Search Vector + keyword hybrid	Live Logs (in Dashboard) 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

Auth token is printed at startup. Stored as HttpOnly cookie for 7 days. For remote access:

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.

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 <name>`	Hot-swap LLM model at runtime
`/policy <dm\|group> <value>`	Change access policies live
`/loop <1-50>`	Set max agentic iterations
`/strategy [buy\|sell <pct>]`	View/change trading thresholds
`/wallet`	Show wallet address + balance
`/modules set\|info\|reset`	Per-group tool permissions
`/plugin set\|unset\|keys`	Manage plugin secrets
`/task <description>`	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 <n>]`	Toggle Tool RAG or view status
`/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.

~/.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:

// ~/.teleton/plugins/weather.js

export const manifest = {
  name: "weather",
  version: "1.0.0",
  sdkVersion: "^1.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()`, `getRawClient()`, `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), 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 (15 providers: Anthropic, Claude Code, OpenAI, Google, xAI, Groq, OpenRouter, Moonshot, Mistral, Cerebras, ZAI, MiniMax, Hugging Face, Cocoon, Local)
Telegram Userbot	GramJS Layer 223 fork (MTProto)
Inline Bot	Grammy (Bot API, for deals)
Blockchain	TON SDK (W5R1 wallet)
DeFi	STON.fi SDK, DeDust SDK
Database	better-sqlite3 with WAL mode
Vector Search	sqlite-vec (cosine similarity)
Full-Text Search	SQLite FTS5 (BM25 ranking)
Embeddings	@huggingface/transformers (local ONNX) or Voyage AI
MCP Client	@modelcontextprotocol/sdk (stdio + SSE + Streamable HTTP)
WebUI	Hono (API) + React + Vite (frontend)
Language	TypeScript 5.7, Node.js 20+

Project Structure

src/
├── index.ts                # Entry point, TeletonApp lifecycle, graceful shutdown
├── agent/                  # Core agent runtime
│   ├── runtime.ts          # Agentic loop (5 iterations, tool calling, masking, compaction)
│   ├── client.ts           # Multi-provider LLM client
│   └── tools/              # 135+ built-in tools
│       ├── register-all.ts # Central tool registration (9 categories)
│       ├── registry.ts     # Tool registry, scope filtering, provider limits
│       ├── module-loader.ts    # Built-in module loading (deals + exec)
│       ├── plugin-loader.ts    # External plugin discovery, validation, hot-reload
│       ├── mcp-loader.ts       # MCP client (stdio/SSE), tool discovery, lifecycle
│       ├── telegram/       # Telegram operations (80 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)
├── deals/                  # Deals module (5 tools, loaded via module-loader)
│   ├── module.ts           # Module definition + lifecycle
│   ├── executor.ts         # Deal execution logic
│   └── strategy-checker.ts # Trading strategy enforcement
├── bot/                    # Deals inline bot (Grammy + GramJS)
│   ├── index.ts            # DealBot (Grammy Bot API)
│   ├── gramjs-bot.ts       # GramJS MTProto for styled buttons
│   └── services/           # Message builder, styled keyboard, verification
├── telegram/               # Telegram integration layer
│   ├── bridge.ts           # GramJS wrapper (peer cache, message parsing, keyboards)
│   ├── handlers.ts         # Message routing, rate limiting, ChatQueue, feed storage
│   ├── admin.ts            # 17 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 (v1.0.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 (15 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	`INSERT OR IGNORE` on tx hashes prevents double-spend, atomic status transitions prevent race conditions
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 scoping	Financial tools DM-only, moderation group-only, admin-only policies, per-chat permissions configurable at runtime

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

Use a dedicated Telegram account
Backup your 24-word mnemonic securely offline
Start with restrictive policies (admin-only or allowlist)
Set file permissions: chmod 600 ~/.teleton/wallet.json
Never commit config.yaml to version control
Review SECURITY.md and customize for your use case

Development

Setup

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

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/ directory:

Section	Description
Configuration Guide	Complete reference for every config option
Deployment Guide	Docker, systemd, docker-compose, VPS
Plugin Development	Step-by-step plugin tutorial
Telegram Setup	API credentials, policies, 2FA, admin commands
TON Wallet	Wallet setup, DEX trading, security
Management API	HTTPS API, bootstrap mode, authentication, endpoints

Contributing

See CONTRIBUTING.md for the full guide.

Fork the repository
Create a feature branch from main
Make your changes
Verify: npm run typecheck && npm run lint && npm test
Open a Pull Request against main

Contributors

License

MIT License - See LICENSE for details.

Credits

Built With

pi-ai - Multi-provider LLM SDK
GramJS - Telegram MTProto library
Grammy - Telegram Bot API framework
TON SDK - TON blockchain client
STON.fi SDK - DEX integration
DeDust SDK - DEX integration
MCP SDK - Model Context Protocol client
sqlite-vec - Vector search for SQLite
Hono - Lightweight web framework
Tonutils-Proxy - TON Proxy for .ton sites

Support

Issues: GitHub Issues
Channel: @teletonagents
Group Chat: @teletonagentHQ
Contact: @zkproof

Release History

Version	Changes	Urgency	Date
v0.8.6	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 8ae4f88 v0.8.6 a71608d fix: clean up stale docs 79cd574 fix: lint eslint-disable on correct line dd7105f ui: dashboard, mode switch, infotips b45ed79 tools: extended scopes, dead UI cleanup, CSS variables 797bf09 fix: update loader tests for restructured prompt d68697e agent: memory, prompts, tools overhaul ef1000a ui: togg	Medium	3/25/2026
v0.8.5	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 3fd5732 v0.8.5 6b574af fix(lint): use const for non-reassigned variables in SDK tests 55cffe2 feat: SDK low-level TON APIs, compaction fix, minor improvements bdc68bd fix(test): update SignedTransfer test expectations for v2 fields 423b70f feat(sdk): enrich SignedTransfer with seqno, validUntil, walletAddress fe28f4f docs:	Low	3/16/2026
v0.8.4	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 3ae3017 v0.8.4 d858f8c fix(setup): persist telegram credentials to config.yaml after auth f1e1556 docs(api): add Management API documentation a4dc9ad docs(readme): underline Key Highlights card titles 222f786 docs(readme): modernize layout and update content Full Changelog: https://github.com/TONresistor/teleton-agent	Low	3/13/2026
v0.8.3	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 6948f6d v0.8.3 60029e2 fix(ci): harden Telegram notify against special chars in commit messages 2d4049a feat(api): add bootstrap mode for remote setup without config Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.8.2...v0.8.3	Low	3/13/2026
v0.8.2	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes f3687c6 v0.8.2 7e6ac26 fix(deps): patch 4 Dependabot vulnerabilities ac67afd fix(ci): remove unused @hono/zod-openapi, add src/api/ to knip entries f6255b8 feat(api): add HTTPS management API for remote agent control 1b36ac3 fix(embeddings): validate cached model files and use atomic writes 25728b2 feat(memory): smarter RAG	Low	3/13/2026
v0.8.1	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 0229b3a v0.8.1 ebb1580 docs: update changelog for v0.8.0 and v0.8.1 fd4c1a9 fix(ci): lower coverage thresholds for Node 20 CI variance 1eb7bad docs: update for 15 providers, TON Proxy, SDK signed transfers 44305d4 feat(sdk): signed transfers without broadcast for x402 payments 871f661 perf: parallelize RAG searches and cach	Low	3/5/2026
v0.8.0	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes b8b1560 v0.8.0 2d3ecae feat(gramjs): upgrade to Layer 223 e6ec0ce feat(sdk): add Bot SDK + complete documentation to 100% coverage 2cce211 feat(providers): add Cerebras, ZAI, MiniMax, HuggingFace + refactor Moonshot a46f7fc feat(sdk): add dns.setSiteRecord() for TON Site ADNL records 7032e9b feat(sdk): expand plugin API wit	Low	3/3/2026
v0.7.5	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 0d7de25 v0.7.5 d5981b4 fix(formatting): remove underscore and italic markdown rules 1aae92a docs: update CHANGELOG and README for v0.7.4+ 3f00892 feat: exec tools, admin-only policy, token tracking, WebUI updates 495a216 feat(dns): add dns_set_site for decentralized TON Site hosting d58922d refactor(tools): enrich 35+ tool	Low	2/28/2026
v0.7.4	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 922ab5f v0.7.4 1ecd53e style(webui): use accent blue for toggle switches 8c0a523 fix: pass session path to DealBot + Soul editor layout 0ca00e0 feat(webui): expand configurable keys + new dashboard features a5c78db refactor(webui): reorganize Dashboard & Config pages 4a3f51e refactor(setup): reorder wizard flow + clean up w	Low	2/25/2026
v0.7.3	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 95bc8cb chore: bump to v0.7.3 d0d6ee0 feat(context): inject reply-to message context into LLM prompt c526571 fix: replace deprecated claude-3-5-haiku with claude-haiku-4-5 + fix seed phrase display in CLI setup c9c0f2b feat(auth): support Telegram anonymous numbers (+888) via Fragment b9b27cc feat(provider): add claude-code	Low	2/24/2026
v0.7.2	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 6f4fa10 chore: bump to v0.7.2 8a71e2a fix(webui): plugins route now reflects runtime-loaded plugins Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.7.1...v0.7.2	Low	2/23/2026
v0.7.1	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 442d3a5 chore: bump to v0.7.1 77fb97f docs: replace DeepWiki badge with official docs + update provider/tool counts 516a620 docs: add TON badge c268ab2 docs: add logo as banner above title in README 51e7381 docs: update changelog [Unreleased] 187747d fix(webui): neutralize btn-danger and alert colors cc02d47 fix(sdk): sendJ	Low	2/23/2026
v0.7.0	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 5cd2794 v0.7.0 b4c5bf8 docs: update changelog for v0.7.0 release dd16df6 feat(cli): add ASCII banner to setup --ui + update changelog 6b925ea docs: update changelog — unreleased + v0.6.0 + git history rewrite note 539c59b feat(local-llm): add local LLM provider with audit hardening 8adfbb9 feat(webui): setup wizard with gui	Low	2/21/2026
v0.6.0	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 98675ec v0.6.0 6006aca feat(webui): accordion UI, dashboard settings, marketplace download fix 0254290 feat(webui): add Plugin Marketplace with secrets management c6e0107 feat(webui): add Config + MCP pages, custom Select, centralize CSS b92b7a9 feat(tools): add Tool RAG, web tools, and admin enhancements 41d26ec feat(mcp):	Low	2/17/2026
v0.5.2	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 777cd2c v0.5.2 161fd13 feat(plugins): auto-install npm deps + remove dead dependencies 703d57b fix: robust local embedding model loading 3907ab3 chore: remove TGAPI.md Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.5.1...v0.5.2	Low	2/16/2026
v0.5.1	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 7cada8c chore: bump to v0.5.1, CI/CD for SDK + WebUI + Docker 1e01195 Merge dev into main for v0.5.0 51baf14 feat: data-bearing tool categories, strict DB row types, RAG rebalancing 2e347c3 feat(plugins): add onMessage and onCallbackQuery event hooks a9a9a1b feat(webui): inline dropdown task details with overflow fix 519409	Low	2/16/2026
v0.4.0	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes d5f0647 chore: bump version to 0.4.0 efcb466 fix: remove sqlite-vec startup logs that printed before ASCII banner 4e17daf fix: harden error handling, improve perf, and use crypto-safe randomId across codebase 53cbf94 fix: validate chatId to prevent entity resolution crashes on display names 00be723 chore: remove obsolete bu	Low	2/14/2026
v0.3.0	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes dca3fa8 feat: local embeddings + hybrid vector search + new tools 33ce0ea fix: correct Docker image name in README 99535e7 fix: guard against undefined model from pi-ai getModel() 825e841 fix: ignore bot messages in DMs to prevent bot-to-bot loops Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0	Low	2/13/2026
v0.2.5	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 2e356d1 chore: remove unused @tonkite/highload-wallet-v3 dependency 892b6a0 fix: /clear command crashing on missing vec0 table 11ce687 fix: post-audit hardening — timeouts, seqno race, cached endpoints, cleanup 03fe20b allow swap tools in groups + show module level in /modules info d2fe39c feat: per-group module permissions	Low	2/12/2026
v0.2.4	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 74bc4c8 v0.2.4: close memory.db on shutdown + atomic deal state guards Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.2.3...v0.2.4	Low	2/10/2026
v0.2.3	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes ee562a9 v0.2.3: fix MarketPriceService crash on fresh installs Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.2.2...v0.2.3	Low	2/10/2026
v0.2.2	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 45183ea v0.2.2: use peer cache in bridge.getMessages for reliable entity resolution 88542c9 v0.2.1 5d0ae65 fix: use cached peer entity in get-history for reliable channel resolution 58384c4 refactor: decentralize tool registration into co-located ToolEntry arrays 3b46dbf fix: mention detection fallback + duplicate message g	Low	2/10/2026
v0.2.0	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 87656dc chore: sync package-lock.json to v0.2.0 bb22d9c v0.2.0 fcc557a v0.1.22: extract deals/market modules + Gemini schema sanitizer 2f050c9 refactor: extract casino into self-contained plugin module 1347cf2 chore: remove dead casino files (game-executor, validators) Full Changelog: https://github.com/TONresistor/te	Low	2/10/2026
v0.1.21	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes bbfb03d v0.1.21 9474aa1 feat: prompt injection defense + tool context scoping a409ae9 fix: audit corrections - clearHistory order, cached endpoint, tasks index 86334a2 feat: remove jackpot system entirely 5218a58 fix: install.sh read from /dev/tty and lowercase Docker image name ## What's Changed * Errors in install scrip	Low	2/9/2026
v0.1.20	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes fa51415 v0.1.20 d005b4a fix: return shallow copy from getTonPrice cache f7509ae feat: cache getTonPrice() with 30s TTL f10a88f feat: log completed deals to business journal c648bd3 feat: cleanup transcript files older than 30 days at startup Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.1.19.	Low	2/9/2026
v0.1.19	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 91797a7 v0.1.19 447a297 fix: start folder IDs at 2 (IDs 0-1 are reserved by Telegram) 0b3439c fix: handle GetDialogFilters returning object instead of array aac6d5b fix: wrap DialogFilter title in TextWithEntities for GramJS layer 222+ 86cff4d fix: add atomic status preconditions to deal verify-payment 62cf944 docs: add web	Low	2/8/2026
v0.1.18	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes e3b39a1 v0.1.18 72b6835 feat: optimize runtime logs + TonAPI rate limiting 06eae91 fix: move TonAPI log after TON Blockchain connected Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.1.17...v0.1.18	Low	2/8/2026
v0.1.17	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 87e1378 v0.1.17 6ee8c04 fix: add /boot instruction to setup wizard next steps c0bc183 feat: implement /boot admin command for agent bootstrap f13b3a4 fix: rename Deals option to Gifts (Deals & Market Data) ea8e81f fix: merge Deals and Market into single module option 74e8ad2 fix: remove imperative placeholders from MEMORY.m	Low	2/8/2026
v0.1.16	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 9291a82 v0.1.16 a60efe9 fix: agent empty response when memory_write is only tool call Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.1.15...v0.1.16	Low	2/8/2026
v0.1.15	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes b42b152 fix: bundle @ston-fi with all transitive deps via external blacklist Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.1.14...v0.1.15	Low	2/8/2026
v0.1.14	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 594bc82 fix: remove postinstall to avoid preinstall blocker Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.1.13...v0.1.14	Low	2/8/2026
v0.1.13	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.1.12...v0.1.13	Low	2/8/2026
v0.1.12	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 5964899 fix: bundle ofetch and big-integer transitive deps Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.1.11...v0.1.12	Low	2/8/2026
v0.1.11	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 3399c1a fix: move @ston-fi packages to devDependencies for typecheck Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.1.10...v0.1.11	Low	2/8/2026
v0.1.9	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes ba7da67 fix: bundle @ston-fi/api to avoid pnpm-only install blocker Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.1.8...v0.1.9	Low	2/8/2026
v0.1.8	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 925373a fix: copy scripts/ in Dockerfile build stage Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.1.7...v0.1.8	Low	2/8/2026
v0.1.7	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 97b0921 fix: Docker build and bump to v0.1.7 Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.1.6...v0.1.7	Low	2/8/2026
v0.1.6	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/TONresistor/teleton-agent:latest setup ``` ## Changes 2e1fe33 Initial release v0.1.6 Full Changelog: https://github.com/TONresistor/teleton-agent/commits/v0.1.6	Low	2/8/2026
v0.1.4	## Install npm: ```bash npm install -g teleton ``` Docker: ```bash docker run -it -v ~/.teleton:/data ghcr.io/tonresistor/teleton-agent:latest setup ``` ## Changes 761a5cf fix: Docker build failing due to husky in production install Full Changelog: https://github.com/TONresistor/teleton-agent/compare/v0.1.3...v0.1.4	Low	2/8/2026

Dependencies & License Audit

Loading dependencies...

Similar Packages

opencode-telegram-botOpenCode mobile client via Telegram: run and monitor AI coding tasks from your phone while everything runs locally on your machine. Scheduled tasks support. Can be used as lightweight OpenClaw alternav0.21.1

serverlessclawOfficial ServerlessClaw: The authoritative autonomous AI agent swarm for AWS. Zero idle cost, self-evolving, and infinite scale. Powered by OpenClaw.main@2026-06-03

openclaw-soulSoul — Give Your AI Assistant Its Own Inner Life. Autonomous thinking, memory, and self-improvement plugin for OpenClawv2.5.0

MiniSearchMinimalist web-searching platform with an AI assistant that runs directly from your browser. Uses WebLLM, Wllama and SearXNG. Demo: https://felladrin-minisearch.hf.spacemain@2026-06-05

piclawI'm going to build my own OpenClaw, with blackjack... and bun!v2.6.1

More in AI Agents

hermes-agentThe agent that grows with you

awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.

CopilotKitThe Frontend Stack for Agents & Generative UI. React + Angular. Makers of the AG-UI Protocol

e2bE2B SDK that give agents cloud environments