Teleton Agent

---

Key Highlights

---

Features

Tool Categories

Category	Tools	Description
Telegram	85	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
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
Tool Search	2	Semantic retrieval plus reading stored tool results
System	5	Exec (4) and TON Proxy status (1), both optional

Advanced Capabilities

Capability	Description
Multi-Provider LLM	16 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 ^22.22.2, ^24.15.0, or >=26.0.0 - Download
• LLM API Key - One of: Anthropic (recommended), OpenAI, Google, xAI, Groq, OpenRouter, Moonshot, Mistral, Cerebras, ZAI, MiniMax, Hugging Face — or keyless: Codex and Grok Build (CLI auto-detect), Gocoon (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 in user mode) - From @BotFather for plugin inline cards and callbacks; required in bot mode

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	129 base, up to 134 with optional system modules	Registry filtered automatically by bot-compatible capabilities
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 | codex | grok-build | openai | google | xai | groq | openrouter | moonshot | mistral | cerebras | zai | minimax | huggingface | gocoon | 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 in user mode: plugin inline cards and callbacks
  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 16 providers. Defined in src/config/model-catalog.ts, shared across CLI, WebUI, and Dashboard.

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.

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:

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

~/.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: "^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 (16 providers: Anthropic, Codex, Grok Build, OpenAI, Google, xAI, Groq, OpenRouter, Moonshot, Mistral, Cerebras, ZAI, MiniMax, Hugging Face, Gocoon, Local)
Telegram Userbot	GramJS Layer 229 fork (MTProto)
Inline Bot	Grammy (Bot API, plugin inline cards and callbacks)
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.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

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.

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 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