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 platform that operates as a real Telegram user account (not a 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.

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-opus-4-6"
  utility_model: "claude-haiku-4-5-20251001"  # for summarization, compaction, vision
  max_agentic_iterations: 5

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"

  session_reset_policy:
    daily_reset_enabled: true
    daily_reset_hour: 4
    idle_expiry_minutes: 1440  # 24h idle → new session

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

Name		Name	Last commit message	Last commit date
Latest commit History 216 Commits
.github		.github
.husky		.husky
bin		bin
docker/rvc		docker/rvc
docs		docs
packages/sdk		packages/sdk
src		src
web		web
.dockerignore		.dockerignore
.gitignore		.gitignore
.jscpd.json		.jscpd.json
.madgerc		.madgerc
.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
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

Folders and files

Latest commit

History

Repository files navigation

Key Highlights

Features

Tool Categories

Advanced Capabilities

Prerequisites

Quick Start

1. Installation

2. Setup & Start

3. Verify

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

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 38

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages