teleton-agent

<p align="center">
  <img src="./logo_dark.png" alt="Teleton Agent" width="700" />
</p>

<p align="center"><b>Autonomous AI agent platform for Telegram with native TON blockchain integration</b></p>

<p align="center">
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen" alt="Node.js"></a>
  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.7-blue" alt="TypeScript"></a>
  <a href="https://teletonagent.dev"><img src="https://img.shields.io/badge/Website-teletonagent.dev-ff6600" alt="Website"></a>
  <a href="https://docs.teletonagent.dev"><img src="https://img.shields.io/badge/docs-Teleton%20Agents-blue" alt="Documentation"></a>
  <a href="https://ton.org"><img src="https://img.shields.io/badge/Built_on-TON-0098EA?logo=ton&logoColor=white" alt="Built on TON"></a>
</p>

---

<p align="center">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.</p>

### Key Highlights

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

---

## 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](https://nodejs.org/)
- **LLM API Key** - One of: [Anthropic](https://console.anthropic.com/) (recommended), [OpenAI](https://platform.openai.com/), [Google](https://aistudio.google.com/), [xAI](https://console.x.ai/), [Groq](https://console.groq.com/), [OpenRouter](https://openrouter.ai/), [Moonshot](https://platform.moonshot.ai/), [Mistral](https://console.mistral.ai/), [Cerebras](https://cloud.cerebras.ai/), [ZAI](https://open.bigmodel.cn/), [MiniMax](https://platform.minimaxi.com/), [Hugging Face](https://huggingface.co/settings/tokens) — 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](https://my.telegram.org/apps)
- **Your Telegram User ID** - Message [@userinfobot](https://t.me/userinfobot)
- **Bot Token** *(optional)* - From [@BotFather](https://t.me/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):**
```bash
npm install -g teleton@latest
```

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

**From source (development):**
```bash
git clone https://github.com/TONresistor/teleton-agent.git
cd teleton-agent
npm install && npm run build
```

### 2. Setup & Start

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

```bash
teleton start --webui
```

### 3. Verify

Send a message to your agent on Telegram:

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

You: /status
Agent: [Disp

[truncated…]