GitHub - TONresistor/teleton-agent: Teleton: Autonomous AI Agent for Telegram & TON Blockchain

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.

Key Highlights

Full Telegram Access Real user via MTProto, not a bot	Agentic Loop Think, act, observe, repeat until shit gets done	16 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	131 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	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.

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

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

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

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 dev
Make your changes
Verify: npm run typecheck && npm run lint && npm test
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

Name		Name	Last commit message	Last commit date
.github		.github
.husky		.husky
bin		bin
docker/rvc		docker/rvc
docs-sdk		docs-sdk
docs		docs
packages/sdk		packages/sdk
scripts		scripts
src		src
web		web
.dockerignore		.dockerignore
.gitignore		.gitignore
.jscpd.json		.jscpd.json
.madgerc		.madgerc
.npmrc		.npmrc
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
GETTING_STARTED.md		GETTING_STARTED.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
TOOLS.md		TOOLS.md
audit-ci.jsonc		audit-ci.jsonc
config.example.yaml		config.example.yaml
eslint.config.js		eslint.config.js
install.sh		install.sh
knip.json		knip.json
logo_dark.png		logo_dark.png
logo_light.png		logo_light.png
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts
vitest.sdk.config.ts		vitest.sdk.config.ts

Latest commit

History

Folders and files

Repository files navigation

Key Highlights

Features

Tool Categories

Advanced Capabilities

Prerequisites

Quick Start

1. Installation

2. Setup & Start

3. Verify

User Mode vs Bot Mode

Configuration

Supported Models

MCP Servers

Environment Variables

WebUI Dashboard

Coding Agent

Admin Commands

Plugins

Plugin SDK

Architecture

Tech Stack

Project Structure

Security

Multi-Layer Defense

Reporting Vulnerabilities

Best Practices

Development

Setup

Commands

Documentation

Contributing

Contributors

License

Credits

Built With

Support

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages