Skip to main content

Documentation Index

Fetch the complete documentation index at: https://superturtle.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

All bot configuration is done through environment variables in .superturtle/.env (created by superturtle init, gitignored). Never commit credentials.

​
Required Variables

​
TELEGRAM_BOT_TOKEN

Your Telegram bot token from @BotFather. 
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
Get this from @BotFather with /newbot.

​
TELEGRAM_ALLOWED_USERS

Comma-separated Telegram user IDs allowed to use the bot. 
# Single user
TELEGRAM_ALLOWED_USERS=123456789

# Multiple users
TELEGRAM_ALLOWED_USERS=123456789,987654321,555666777
Get your ID from @userinfobot.

​
CLAUDE_WORKING_DIR

Default working directory for Claude. Claude can access files and run commands from here. 
CLAUDE_WORKING_DIR=~/my-assistant
superturtle start sets this automatically to the current project directory. If you intentionally run the bot-folder launcher directly (bun run start or bun run dev), set CLAUDE_WORKING_DIR in your shell first so the launcher can find CLAUDE_WORKING_DIR/.superturtle/.env. For repo development, prefer node super_turtle/bin/superturtle.js start from the repo root.

​
OPENAI_API_KEY

API key for voice transcription (optional but required for voice messages). 
OPENAI_API_KEY=sk-proj-1234567890abcdef
Get from platform.openai.com/api-keys. Voice transcription won’t work without this, but other features are unaffected.

​
SHOW_TOOL_STATUS

Show routine tool-call progress messages in Telegram while an answer runs. 
SHOW_TOOL_STATUS=false
Default: false. Keep this at false for quieter chats; set it to true only if you want the old per-tool progress updates back.

​
MAIN_PROVIDER

Startup default driver for the Telegram meta-agent. 
MAIN_PROVIDER=claude
Options:
  • claude
  • codex
Default: claude. This is a startup default, not a forced override. Effective precedence is:
  1. Saved last-used driver from Telegram
  2. MAIN_PROVIDER
  3. Built-in fallback claude
That means /restart keeps the user’s last selected driver. If you set MAIN_PROVIDER=codex, you must also set CODEX_ENABLED=true and have a working local codex CLI; otherwise startup falls back to Claude.

​
Codex

​
CODEX_ENABLED

Enable Codex driver and usage reporting. 
CODEX_ENABLED=true
Default: false. Requires a working local codex CLI login.

​
META_CODEX_SANDBOX_MODE

Sandbox restrictions for Codex SubTurtles. 
META_CODEX_SANDBOX_MODE=workspace-write
Options:
  • read-only — Can only read files
  • workspace-write — Can read/write workspace (default, recommended)
  • danger-full-access — Full file system access (use cautiously)

​
META_CODEX_APPROVAL_POLICY

When to ask for approval before running Codex. 
META_CODEX_APPROVAL_POLICY=never
Options:
  • never — Run without asking (default)
  • on-request — Ask only when explicitly requested
  • on-failure — Ask if something fails
  • untrusted — Ask for untrusted tasks

​
META_CODEX_NETWORK_ACCESS

Allow Codex to make network requests. 
META_CODEX_NETWORK_ACCESS=false
Default: false. Set to true only if Codex needs to fetch URLs, call APIs, etc.

​
File Access & Security

​
ALLOWED_PATHS

Comma-separated list of directories Claude can access. 
# Default (if not set):
ALLOWED_PATHS=$CLAUDE_WORKING_DIR,~/Documents,~/Downloads,~/Desktop,~/.claude

# Custom:
ALLOWED_PATHS=~/my-assistant,~/Documents/Notes,~/.claude
If you set this, it overrides all defaults. Make sure to include ~/.claude if you use Claude Code plan mode.

​
AUDIT_LOG_PATH

Path for security audit logs. 
AUDIT_LOG_PATH=/tmp/claude-telegram-audit.log
Default: /tmp/claude-telegram-audit.log. Set to empty string to disable logging.

​
AUDIT_LOG_JSON

Log in JSON format (easier to parse programmatically). 
AUDIT_LOG_JSON=true
Default: false. Logs as text instead.

​
Voice Transcription

​
TRANSCRIPTION_CONTEXT_FILE

Path to a file with context for voice transcription. 
TRANSCRIPTION_CONTEXT_FILE=~/my-assistant/transcription-context.txt
Optional. If set, Claude will use this context when transcribing voice messages. Useful for including domain-specific words or acronyms. Example file content: 
This person discusses:
- Technologies: React, Node.js, TypeScript, Bun
- Companies: Anthropic, OpenAI, Typefully
- Personal interests: Sim racing, fitness, photography

​
Dashboard (Optional)

​
DASHBOARD_ENABLED

Enable the bot’s web dashboard. 
DASHBOARD_ENABLED=true
Default: true. Runs the local web dashboard unless explicitly disabled.

​
DASHBOARD_AUTH_TOKEN

Authentication token for dashboard access. 
DASHBOARD_AUTH_TOKEN=your-secret-token
Optional. For local-only usage, leave unset. If set, dashboard requires this token (Authorization: Bearer <token>, x-dashboard-token, or ?token=).

​
Advanced Configuration

​
CLAUDE_CLI_PATH

Path to the Claude CLI binary. 
CLAUDE_CLI_PATH=/opt/homebrew/bin/claude
Usually auto-detected. Set only if claude command is not in your PATH.

​
Default Models & Effort

These values seed fresh driver preferences only. Once a user changes model, effort, or driver in Telegram, the saved preference wins over the env default.

​
DEFAULT_CLAUDE_MODEL

Default Claude model for new users / empty preference files. 
DEFAULT_CLAUDE_MODEL=claude-sonnet-4-6
Options:
  • claude-opus-4-6
  • claude-sonnet-4-6
  • claude-haiku-4-5-20251001
Default: claude-opus-4-6

​
DEFAULT_CLAUDE_EFFORT

Default Claude effort level for new users / empty preference files. 
DEFAULT_CLAUDE_EFFORT=medium
Options:
  • low
  • medium
  • high
Default: high

​
DEFAULT_CODEX_MODEL

Default Codex model for new users / empty preference files. 
DEFAULT_CODEX_MODEL=gpt-5.3-codex-spark
Options:
  • gpt-5.3-codex
  • gpt-5.3-codex-spark
Default: gpt-5.3-codex

​
DEFAULT_CODEX_EFFORT

Default Codex reasoning effort for new users / empty preference files. 
DEFAULT_CODEX_EFFORT=low
Options:
  • minimal
  • low
  • medium
  • high
  • xhigh
Default: medium

​
Configuration Groups

​
Minimal Setup

Bare minimum to run: 
TELEGRAM_BOT_TOKEN=your-token
TELEGRAM_ALLOWED_USERS=your-id

​
Development Setup

Good for local testing: 
TELEGRAM_BOT_TOKEN=your-token
TELEGRAM_ALLOWED_USERS=your-id
CLAUDE_WORKING_DIR=~/my-dev-folder
SHOW_TOOL_STATUS=false
DEFAULT_CLAUDE_MODEL=claude-sonnet-4-6
DEFAULT_CLAUDE_EFFORT=medium
RATE_LIMIT_REQUESTS=100
OPENAI_API_KEY=your-key

​
Personal Assistant Setup

Full-featured personal use: 
TELEGRAM_BOT_TOKEN=your-token
TELEGRAM_ALLOWED_USERS=your-id
CLAUDE_WORKING_DIR=~/my-assistant
SHOW_TOOL_STATUS=false
DEFAULT_CLAUDE_MODEL=claude-sonnet-4-6
DEFAULT_CLAUDE_EFFORT=medium
ALLOWED_PATHS=~/my-assistant,~/Documents/Notes,~/.claude
OPENAI_API_KEY=your-key
AUDIT_LOG_PATH=/tmp/claude-telegram-audit.log
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS=50

​
Production with Codex

Full setup with both drivers: 
TELEGRAM_BOT_TOKEN=your-token
TELEGRAM_ALLOWED_USERS=your-id,other-id
CLAUDE_WORKING_DIR=/var/lib/claude-assistant
DEFAULT_CLAUDE_MODEL=claude-sonnet-4-6
DEFAULT_CLAUDE_EFFORT=medium
ALLOWED_PATHS=/var/lib/claude-assistant,/home/user/Documents,~/.claude
OPENAI_API_KEY=your-key
CODEX_ENABLED=true
DEFAULT_CODEX_MODEL=gpt-5.3-codex-spark
DEFAULT_CODEX_EFFORT=low
META_CODEX_SANDBOX_MODE=workspace-write
META_CODEX_APPROVAL_POLICY=never
AUDIT_LOG_PATH=/var/log/claude-telegram.log
AUDIT_LOG_JSON=true
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS=50
RATE_LIMIT_WINDOW=60

​
Example .env File

# ============ Required ============
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_ALLOWED_USERS=123456789

# ============ Recommended ============
CLAUDE_WORKING_DIR=~/my-assistant
OPENAI_API_KEY=sk-proj-1234567890abcdef
SHOW_TOOL_STATUS=false
MAIN_PROVIDER=claude
DEFAULT_CLAUDE_MODEL=claude-sonnet-4-6
DEFAULT_CLAUDE_EFFORT=medium

# ============ File Access ============
ALLOWED_PATHS=~/my-assistant,~/Documents/Notes,~/.claude

# ============ Security ============
AUDIT_LOG_PATH=/tmp/claude-telegram-audit.log
AUDIT_LOG_JSON=false
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS=20
RATE_LIMIT_WINDOW=60

# ============ Voice ============
TRANSCRIPTION_CONTEXT_FILE=~/my-assistant/transcription-context.txt

# ============ Codex (Optional) ============
# CODEX_ENABLED=true
# MAIN_PROVIDER=codex
# DEFAULT_CODEX_MODEL=gpt-5.3-codex-spark
# DEFAULT_CODEX_EFFORT=low
# META_CODEX_SANDBOX_MODE=workspace-write
# META_CODEX_APPROVAL_POLICY=never
# META_CODEX_NETWORK_ACCESS=false

# ============ Dashboard (Optional) ============
# DASHBOARD_ENABLED=true
# DASHBOARD_AUTH_TOKEN=your-secret-token

​
Rate Limiting

​
RATE_LIMIT_ENABLED

Enable per-user inbound Telegram request throttling. 
RATE_LIMIT_ENABLED=true
Default: true. This applies a token bucket before the bot starts processing text, voice, and file messages.

​
RATE_LIMIT_REQUESTS

How many inbound requests each Telegram user can send per window. 
RATE_LIMIT_REQUESTS=20
Default: 20 requests. Increase it if you expect a heavier personal usage pattern.

​
RATE_LIMIT_WINDOW

Time window in seconds. 
RATE_LIMIT_WINDOW=60
Default: 60 seconds. With the defaults, each user gets 20 inbound requests per 60 seconds.

​
Validation

The bot validates on startup:
ValidationErrorFix
TELEGRAM_BOT_TOKEN missing”ERROR: TELEGRAM_BOT_TOKEN required”Add to .superturtle/.env
TELEGRAM_ALLOWED_USERS missing”ERROR: TELEGRAM_ALLOWED_USERS required”Add your ID
RATE_LIMIT_REQUESTS invalidFalls back to 20Use integer
CODEX_SANDBOX_MODE invalidWarns, falls back to “workspace-write”Use valid option
Working directory doesn’t existBot starts but Claude can’t access itCreate directory

​
Restart required

All variables are read at startup. Restart the bot for any changes to take effect.

​
Security Best Practices

  1. Never commit .superturtle/.env — It contains secrets
  2. Use strong tokens — Telegram and OpenAI provide secure tokens
  3. Limit ALLOWED_PATHS — Only include directories Claude needs
  4. Restrict TELEGRAM_ALLOWED_USERS — Only trusted users
  5. Use read-only sandbox — For Codex if possible (read-only or workspace-write)
  6. Enable audit logging — Always log interactions for review

​
Next Steps

  • Security — Full security model and threat assessment
  • Platform Support — macOS/Linux/Windows differences
  • Drivers — Understanding Claude Code vs Codex