Getting Started

Getting Started

Prerequisites

• Docker and Docker Compose
• A Telegram bot token (create one with @BotFather)
• A Claude authentication method: Anthropic API key or Claude Code OAuth token (claude setup-token)

Note on OAuth tokens: Using Claude Code OAuth tokens with third-party applications must comply with Anthropic's authentication and credential use policy. Review the policy before using this method. OAuth token support is deprecated and will be removed in a future version.

1. Clone and Configure

git clone https://github.com/mtzanidakis/praktor.git
cd praktor
cp config/praktor.example.yaml config/praktor.yaml
cp .env.example .env && chmod 0600 .env

Edit .env and fill in your credentials (see comments in the file for details). Set DOCKER_GID to the group ID of the docker group on your host so the non-root container user can access the Docker socket:

grep docker /etc/group    # look for the docker group GID

Edit config/praktor.yaml to define your agents:

telegram:
  allow_from: []            # Telegram user IDs (empty = allow all)
  main_chat_id: 0           # Chat ID for scheduled task / swarm results

defaults:
  model: "claude-sonnet-5"
  max_running: 5
  idle_timeout: 10m

agents:
  general:
    description: "General-purpose assistant for everyday tasks"
    nix_enabled: true
  coder:
    description: "Software engineering specialist"
    model: "claude-opus-4-8"
    nix_enabled: true
    env:
      GITHUB_TOKEN: "secret:github-token"    # Resolved from vault
  researcher:
    description: "Web research and analysis"
    allowed_tools: [WebSearch, WebFetch, Read, Write]

router:
  default_agent: general

2. Build and Run

docker compose build agent    # Build the agent image locally
docker compose up -d          # Start the stack (pulls gateway from GHCR)
docker compose logs -f        # Watch logs

The agent image must be built locally because it bundles proprietary third-party software that cannot be redistributed. See Third-Party Notice for details.

Mission Control is available at http://localhost:8080.

3. Start Chatting

Open Telegram and send a message to your bot. Praktor routes it to the right agent, spins up a container, and responds. Use @agent_name to target a specific agent:

Hello!                              → routed to default agent
@coder fix the login bug            → routed to coder
@researcher find papers on RAG      → routed to researcher

For a secure setup without exposed ports, see Production Deployment.