ESC
Start typing to search...
Docs / Quick Start

Quick Start

Get your Teleton Agent running in 5 minutes with this step-by-step guide.

Prerequisites

Before starting, make sure you have:

  • Node.js 20+ installed (node --version)
  • A Telegram account with a phone number
  • An API key from Anthropic, OpenAI, or another supported provider
  • Telegram API credentials from my.telegram.org

Step 1: Install Teleton

Terminal 
npm install -g teleton@latest

Step 2: Run the Setup Wizard

The setup wizard will guide you through configuration:

Terminal 
teleton setup

The wizard will ask for:

  1. Telegram API ID and Hash - Get from my.telegram.org
  2. Phone number - Your Telegram account's phone
  3. Verification code - Sent to your Telegram
  4. LLM provider - Choose Anthropic, OpenAI, etc.
  5. API key - Your provider's API key
Telegram API credentials

Visit my.telegram.org, log in, go to "API development tools", and create an application to get your API ID and Hash.

Step 3: Start the Agent

Terminal 
teleton start

# Or with WebUI dashboard:
teleton start --webui

You should see:

Output 
✓ Connected to Telegram as @YourUsername
✓ Loaded 114 tools
✓ Memory system initialized
✓ Agent is ready and listening...

Step 4: Test Your Agent

Send a message to your Telegram account from another device or user. Try:

Telegram Message 
Hello! What can you do?

Your agent should respond with its capabilities. You can also test admin commands:

Command What it does
/status Show agent status and memory usage
/wallet Display your TON wallet address
/model Show current LLM model
/pause Pause the agent
/resume Resume the agent

Optional: Enable WebUI

Access the dashboard at http://localhost:3000 when running with --webui:

Terminal 
teleton start --webui

# Dashboard available at http://localhost:3000

The WebUI provides:

  • Real-time message monitoring
  • Memory and conversation history
  • Tool usage statistics
  • Configuration management

Common Issues

Authentication Failed

If Telegram authentication fails:

  • Ensure your phone number includes country code (+1, +44, etc.)
  • Check that your API ID/Hash are correct
  • Delete ~/.teleton/session.json and try again

LLM API Errors

If you see API errors:

  • Verify your API key is valid and has credits
  • Check your network connection
  • Try a different model with /model command

Memory/Database Issues

If memory system fails to initialize:

  • Ensure ~/.teleton directory is writable
  • Check disk space
  • Try teleton reset --memory to rebuild the database