Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
411 lines (315 loc) · 14.2 KB

GETTING_STARTED.md

File metadata and controls

411 lines (315 loc) · 14.2 KB

Getting Started with Teleton

Complete guide to installing, configuring, and running your Teleton AI agent.

Prerequisites

Requirement Details
Node.js 20+ Download - check with node --version
LLM API Key Anthropic (recommended), OpenAI, Google, xAI, Groq, OpenRouter, or any of 15 supported providers
Telegram Account Dedicated account recommended (agent has full control)
Telegram API Credentials api_id + api_hash from my.telegram.org/apps
Telegram User ID Message @userinfobot to get yours
Bot Token (optional) From @BotFather - required for the deals system
TonAPI Key (optional) From @AntTonTechBot mini app - higher rate limits

Installation

npm (recommended):

npm install -g teleton@latest

One-liner:

curl -fsSL https://raw.githubusercontent.com/TONresistor/teleton-agent/main/install.sh | bash

Docker:

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

From source:

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

Setup

teleton setup

The interactive wizard configures everything:

  1. LLM Provider - Choose between 15 providers (Anthropic, OpenAI, Google, xAI, Groq, OpenRouter, Moonshot, Mistral, Cerebras, ZAI, MiniMax, Hugging Face, and more)
  2. Telegram Auth - API credentials, phone number, login code, 2FA password
  3. Access Policies - DM policy (open/allowlist/pairing/disabled), group policy, mention rules
  4. Admin - Your Telegram User ID, owner name/username
  5. TON Wallet - Generates a W5R1 wallet with 24-word mnemonic
  6. Deals (optional) - Bot token for the deals system, trading thresholds
  7. Workspace - Creates template files (SOUL.md, IDENTITY.md, STRATEGY.md, etc.)

Files created:

~/.teleton/
├── config.yaml            # Main configuration
├── wallet.json            # TON wallet (chmod 600 - backup mnemonic!)
├── memory.db              # SQLite database
├── telegram_session.txt   # Telegram session
├── plugins/               # Custom plugins (auto-loaded at startup)
└── workspace/             # Sandboxed agent workspace
    ├── SOUL.md            # Personality and behavior
    ├── IDENTITY.md        # Agent identity
    ├── BOOTSTRAP.md       # First-run instructions
    ├── MEMORY.md          # Persistent memory (RAG-indexed)
    ├── STRATEGY.md        # Trading rules and thresholds
    ├── USER.md            # User information
    ├── SECURITY.md        # Security rules
    ├── memory/            # Daily logs
    ├── downloads/         # Downloaded files
    ├── uploads/           # Uploaded files
    └── temp/              # Temporary files

Start

teleton start

You should see:

🤖 Starting Teleton AI Agent...
✅ Config loaded from ~/.teleton/config.yaml
✅ SOUL.md loaded
✅ Knowledge indexed
✅ Telegram: @your_agent connected
✅ TON Blockchain: connected
✅ Agent is ready! (124 tools)

Verify: Send /ping to your agent on Telegram.

Configuration

Configuration is in ~/.teleton/config.yaml. The setup wizard generates everything, only edit manually to change settings.

Key Settings

agent:
  provider: "anthropic"              # anthropic | openai | google | xai | groq | openrouter | moonshot | mistral | cerebras | zai | minimax | huggingface | cocoon | local
  model: "claude-opus-4-5-20251101"
  max_tokens: 4096
  temperature: 0.7

telegram:
  dm_policy: "open"        # open | allowlist | pairing | disabled
  group_policy: "open"     # open | allowlist | disabled
  require_mention: true    # Require @mention in groups
  admin_ids: [123456789]   # Your Telegram User ID
  debounce_ms: 1500        # Group message batching delay

deals:
  enabled: true
  buy_max_floor_percent: 100   # Buy at or below floor price
  sell_min_floor_percent: 105  # Sell at floor + 5% minimum

Switching LLM Provider

Change provider and api_key in config.yaml:

agent:
  provider: "openai"
  api_key: "sk-..."
  model: "gpt-4o"

Supported: anthropic, openai, google, xai, groq, openrouter, moonshot, mistral, cerebras, zai, minimax, huggingface, cocoon, local

Free Tier Usage (OpenRouter)

OpenRouter provides free models that require no payment — only a free API key from openrouter.ai/keys.

agent:
  provider: "openrouter"
  api_key: "sk-or-v1-..."
  model: "openrouter/free"   # Auto-selects an available free model

Available free models (suffix :free, rate-limited to ~20 RPM):

Model Context Notes
openrouter/free 200K Router — auto-picks an available free model
qwen/qwen3.6-plus:free 1M MoE, SWE-bench 78.8
minimax/minimax-m2.5:free 197K SWE-Bench Verified 80.2%
openai/gpt-oss-120b:free 131K MoE 117B/5.1B, Apache 2.0
qwen/qwen3-coder-480b-a35b:free 262K Coding specialist
nousresearch/hermes-3-405b-instruct:free 131K Frontier-level 405B
meta-llama/llama-3.3-70b-instruct:free 66K Multilingual
google/gemma-3-27b:free 131K Multimodal, 140+ languages
google/gemma-3-12b:free 33K Balanced quality/speed
nvidia/nemotron-3-super-120b-a12b:free 262K Mamba-Transformer hybrid
stepfun/step-3.5-flash:free 256K MoE 196B/11B, high-speed
google/gemma-3n-2b:free 8K Ultra-lightweight edge model

Tips for free tier:

  • If you hit rate limits (429), wait a minute or switch to a different :free model
  • openrouter/free automatically falls back to another free model when one is unavailable
  • Free model availability can change; check openrouter.ai/models?q=free for the current list

Admin Commands

Admin commands are only available to users listed in admin_ids. All commands work with /, !, or . prefix.

Command Description
/ping Check if agent is alive
/status Uptime, model, tool count, memory stats
/task <description> Give agent a task to execute
/clear Clear current chat history
/clear <chat_id> Clear specific chat history
/model <name> Switch LLM model at runtime
/strategy View or change trading thresholds
/strategy buy 95 Set buy threshold to 95% of floor
/strategy sell 110 Set sell threshold to 110% of floor
/wallet Show wallet address and balance
/policy dm open Change DM policy at runtime
/pause / /resume Pause/resume agent responses
/loop <iterations> Set max agentic iterations
/stop Emergency shutdown
/help List all commands

Tool Categories

Teleton has ~124 tools across these categories:

Category Count Highlights
Telegram 77 Messaging, media, chats, groups, polls, stickers, gifts, stars, stories, contacts, folders, profile, memory, tasks
TON & Jettons 15 W5R1 wallet, send/receive TON & jettons, balances, prices, holders, history, charts, NFTs, DEX quotes
STON.fi DEX 5 Swap, quote, search, trending tokens, liquidity pools
DeDust DEX 5 Swap, quote, pools, prices, token info
TON DNS 7 Domain check, auctions, bidding, resolution
Deals 5 Secure gift/TON trading with strategy enforcement and inline bot confirmations
Journal 3 Log trades/operations with reasoning and P&L
Workspace 6 Sandboxed file operations

TON Wallet

During setup, a W5R1 wallet is generated with a 24-word mnemonic stored in ~/.teleton/wallet.json.

CRITICAL: Backup your mnemonic immediately. It's the only way to recover your wallet.

Fund Your Wallet

  1. Ask the agent: "What's my wallet address?"
  2. Send TON from an exchange or another wallet
  3. Minimum ~0.5 TON for gas fees, 10+ TON recommended for trading

Import Existing Wallet

During setup, you can import a wallet instead of generating a new one.

Deals System

The deals system enables secure gift/TON trading with strategy enforcement.

Requirements: Bot token configured, deals enabled in config.

How it works:

  1. Agent proposes a deal (buy/sell gift)
  2. Strategy rules are enforced automatically (buy below floor, sell above floor +5%)
  3. Inline bot shows deal card with Accept/Decline buttons
  4. User sends TON first, agent verifies on-chain
  5. Gift is transferred after payment verification

Customize thresholds:

/strategy buy 90    # Only buy at 90% of floor or less
/strategy sell 115  # Only sell at 115% of floor or more

Memory & RAG

The agent uses a hybrid search system for context-aware responses:

  • MEMORY.md - Persistent memory the agent writes to (RAG-indexed)
  • Daily Logs - Auto-generated session summaries in workspace/memory/
  • Telegram Feed - Past messages across all chats
  • Knowledge Base - All .md files in workspace

Auto-Compaction: When context approaches the provider's limit, the agent summarizes the conversation, archives the transcript, and continues with a fresh context. Nothing is lost.

Security

Wallet

  • Mnemonic stored locally in ~/.teleton/wallet.json (chmod 600)
  • Use a dedicated wallet with limited funds
  • The agent can send transactions - only fund what you're willing to risk

Workspace Sandbox

  • All file operations restricted to ~/.teleton/workspace/
  • Path traversal, URL encoding, null byte, and unicode attacks are blocked
  • Protected files (config.yaml, wallet.json) are inaccessible to the agent

Access Control

  • Admin commands require your User ID in admin_ids
  • DM/group policies control who can interact
  • Non-admins cannot clear history, view status, or execute tasks

Best Practices

  • Use a dedicated Telegram account (not your main)
  • Enable 2FA on the Telegram account
  • Start with restrictive policies, open gradually
  • Monitor the journal and daily logs

Troubleshooting

Telegram Login Fails

  • Use international phone format: +1234567890
  • If 2FA is enabled, enter the password when prompted
  • Session expired: rm ~/.teleton/telegram_session.txt then teleton setup
  • API credentials: api_id is a number, api_hash is a string

Agent Not Responding

  • Check dm_policy / group_policy in config
  • In groups with require_mention: true, you must @mention the agent
  • Verify your User ID is in admin_ids
  • Check if agent is paused (/resume)

API Errors

  • 401: Invalid API key - check provider and key format
  • 429: Rate limited - wait and retry, or switch to a different model
  • Context overflow: Reduce max_tokens or max_agentic_iterations

Health Check

teleton doctor

Verifies config, Telegram session, wallet, and database.

Development

From Source

git clone https://github.com/TONresistor/teleton-agent.git
cd teleton-agent
npm install
npm run build
npm run dev    # Watch mode with auto-restart

Plugins

Add custom tools without touching the source code. Drop a .js file in ~/.teleton/plugins/:

// ~/.teleton/plugins/hello.js
export const tools = [
  {
    name: "hello_world",
    description: "Say hello to someone",
    parameters: {
      type: "object",
      properties: {
        name: { type: "string", description: "Name to greet" }
      },
      required: ["name"]
    },
    execute: async (params, context) => {
      return { success: true, data: { message: `Hello, ${params.name}!` } };
    }
  }
];

Restart the agent — the plugin is auto-loaded:

🔌 Plugin "hello.js": 1 tool registered
✅ 122 tools loaded (1 from plugins)

Plugins receive a full SDK with 108 methods across 9 namespaces: sdk.ton, sdk.telegram, sdk.bot, sdk.secrets, sdk.storage, sdk.log, and more. This includes TON wallet operations like createTransfer, createJettonTransfer, getPublicKey, and getWalletVersion for signing transactions without broadcasting.

Adding Tools (from source)

For contributors, create a TypeScript tool in src/agent/tools/ and register it in src/agent/tools/register-all.ts.

Project Structure

src/
├── index.ts        # Main application entry point (TeletonApp)
├── agent/          # LLM runtime, tool registry, ~124 tool implementations
│   └── tools/      # telegram/, ton/, stonfi/, dedust/, dns/, journal/, workspace/
├── telegram/       # GramJS bridge, message handlers, admin commands, debouncing
├── memory/         # SQLite database, RAG search (FTS5 + vector), compaction
├── ton/            # Wallet operations, payment verification, TON blockchain
├── deals/          # Deal proposals, strategy checker, config
├── bot/            # Grammy + GramJS bot for styled inline deal buttons
├── sdk/            # Plugin SDK (v1.0.0) — TON, Telegram services for plugins
├── ton-proxy/      # TON Proxy module (Tonutils-Proxy integration)
├── session/        # Session persistence, transcripts
├── soul/           # System prompt assembly (SOUL + STRATEGY + SECURITY)
├── config/         # Zod schema, YAML loader, provider registry
├── constants/      # Centralized limits, timeouts, API endpoints
├── services/       # Shared services (TTS voice synthesis)
├── utils/          # Logger, sanitization, retry, fetch
├── workspace/      # Sandboxed file system with security validation
├── templates/      # Workspace template files (SOUL.md, IDENTITY.md, etc.)
└── cli/            # Setup wizard, doctor command

Support

License

MIT - See LICENSE for details.