Files

Cameron 8c4a472480 feat: add LETTABOT_CONFIG env var for config path (#152 )

* docs: add TESTING.md guide

Comprehensive testing documentation covering:
- Unit test setup and patterns
- E2E test setup with Letta Cloud
- MockChannelAdapter usage
- CI/CD workflow
- Best practices

Written by Cameron ◯ Letta Code

* feat: add LETTABOT_CONFIG env var for config path

Addresses Discord feedback from fpl9000 who was confused about where
to put the config file after a global npm install.

Changes:
- Add LETTABOT_CONFIG env var that overrides the config search order
- Update error messages to show the env var option
- Document in docs/configuration.md

Now users doing global installs can either:
- Create ~/.lettabot/config.yaml, or
- Set LETTABOT_CONFIG=/path/to/config.yaml

Written by Cameron ◯ Letta Code

"Configuration should be explicit, not magic." - The Twelve-Factor App

2026-02-04 18:36:10 -08:00

5.8 KiB

Raw Blame History

Configuration Reference

Complete reference for LettaBot configuration options.

Config File Locations

LettaBot checks these locations in order:

LETTABOT_CONFIG env var - Explicit path override
./lettabot.yaml - Project-local (recommended)
./lettabot.yml - Project-local alternate
~/.lettabot/config.yaml - User global
~/.lettabot/config.yml - User global alternate

For global installs (npm install -g), either:

Create ~/.lettabot/config.yaml, or
Set export LETTABOT_CONFIG=/path/to/your/config.yaml

Example Configuration

# Server connection
server:
  mode: cloud                    # 'cloud' or 'selfhosted'
  apiKey: letta_...              # Required for cloud mode

# Agent settings
agent:
  name: LettaBot
  model: claude-sonnet-4
  # id: agent-...                # Optional: use existing agent

# Channel configurations
channels:
  telegram:
    enabled: true
    token: "123456:ABC-DEF..."
    dmPolicy: pairing

  slack:
    enabled: true
    botToken: xoxb-...
    appToken: xapp-...
    dmPolicy: pairing

  discord:
    enabled: true
    token: "..."
    dmPolicy: pairing

  whatsapp:
    enabled: true
    selfChat: true               # IMPORTANT: true for personal numbers
    dmPolicy: pairing

  signal:
    enabled: true
    phone: "+1234567890"
    selfChat: true
    dmPolicy: pairing

# Features
features:
  cron: true
  heartbeat:
    enabled: true
    intervalMin: 60

# Voice transcription
transcription:
  provider: openai
  apiKey: sk-...                 # Optional: falls back to OPENAI_API_KEY
  model: whisper-1

# Attachment handling
attachments:
  maxMB: 20
  maxAgeDays: 14

Server Configuration

Option	Type	Description
`server.mode`	`'cloud'` \| `'selfhosted'`	Connection mode
`server.apiKey`	string	API key for Letta Cloud
`server.baseUrl`	string	URL for self-hosted server (e.g., `http://localhost:8283`)

Self-Hosted Mode

server:
  mode: selfhosted
  baseUrl: http://localhost:8283

Run Letta server with Docker:

docker run -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
  -p 8283:8283 \
  -e OPENAI_API_KEY="..." \
  letta/letta:latest

Agent Configuration

Option	Type	Description
`agent.id`	string	Use existing agent (skips creation)
`agent.name`	string	Name for new agent
`agent.model`	string	Model ID (e.g., `claude-sonnet-4`)

Channel Configuration

All channels share these common options:

Option	Type	Description
`enabled`	boolean	Enable this channel
`dmPolicy`	`'pairing'` \| `'allowlist'` \| `'open'`	Access control mode
`allowedUsers`	string[]	User IDs/numbers for allowlist mode

DM Policies

Note: For WhatsApp/Signal with selfChat: true (personal number), dmPolicy is ignored - only you can message via "Message Yourself" / "Note to Self".

For dedicated bot numbers (selfChat: false), onboarding defaults to allowlist:

allowlist (default for dedicated numbers): Only specified phone numbers can message
pairing: New users get a code, approve with lettabot pairing approve
open: Anyone can message (not recommended)

Channel-Specific Options

Option	Type	Description
`token`	string	Bot token from @BotFather

Slack

Option	Type	Description
`botToken`	string	Bot User OAuth Token (xoxb-...)
`appToken`	string	App-Level Token (xapp-...) for Socket Mode

Discord

Option	Type	Description
`token`	string	Bot token from Discord Developer Portal

Option	Type	Description
`selfChat`	boolean	Critical: `true` = only "Message Yourself" works

Signal

Option	Type	Description
`phone`	string	Phone number with + prefix
`selfChat`	boolean	`true` = only "Note to Self" works

Features Configuration

Heartbeat

features:
  heartbeat:
    enabled: true
    intervalMin: 60    # Check every 60 minutes

Heartbeats are background tasks where the agent can review pending work.

Cron Jobs

features:
  cron: true

Enable scheduled tasks. See Cron Setup.

Transcription Configuration

Voice message transcription via OpenAI Whisper:

transcription:
  provider: openai
  apiKey: sk-...       # Optional: uses OPENAI_API_KEY env var
  model: whisper-1     # Default

Attachments Configuration

attachments:
  maxMB: 20           # Max file size to download (default: 20)
  maxAgeDays: 14      # Auto-delete after N days (default: 14)

Attachments are stored in /tmp/lettabot/attachments/.

Environment Variables

Environment variables override config file values:

Env Variable	Config Equivalent
`LETTABOT_CONFIG`	Path to config file (overrides search order)
`LETTA_API_KEY`	`server.apiKey`
`LETTA_BASE_URL`	`server.baseUrl`
`LETTA_AGENT_ID`	`agent.id`
`LETTA_AGENT_NAME`	`agent.name`
`LETTA_MODEL`	`agent.model`
`TELEGRAM_BOT_TOKEN`	`channels.telegram.token`
`TELEGRAM_DM_POLICY`	`channels.telegram.dmPolicy`
`SLACK_BOT_TOKEN`	`channels.slack.botToken`
`SLACK_APP_TOKEN`	`channels.slack.appToken`
`DISCORD_BOT_TOKEN`	`channels.discord.token`
`WHATSAPP_ENABLED`	`channels.whatsapp.enabled`
`WHATSAPP_SELF_CHAT_MODE`	`channels.whatsapp.selfChat`
`SIGNAL_PHONE_NUMBER`	`channels.signal.phone`
`OPENAI_API_KEY`	`transcription.apiKey`

See SKILL.md for complete environment variable reference.

5.8 KiB Raw Blame History