Aleph
Getting Started

Configuration

Configure your Aleph setup

Aleph uses a TOML configuration file at ~/.aleph/config.toml.

Basic Structure

# Agent configuration
[agent]
default_model = "anthropic/claude-sonnet-4"
thinking = "medium"

# Gateway configuration
[gateway]
port = 18790
bind = "127.0.0.1"
require_auth = false

# Channel configuration
[channel.telegram]
enabled = false
token = "BOT_TOKEN"

[channel.discord]
enabled = false
token = "BOT_TOKEN"

# Session configuration
[session]
auto_reset_hour = 4
expiry_days = 30

Agent Configuration

Model Selection

[agent]
# Primary model
model = "anthropic/claude-opus-4-20250514"

# Fallback models (failover chain)
models = [
  "anthropic/claude-opus-4-20250514",
  "openai/gpt-4o",
  "google/gemini-pro"
]

Thinking Levels

LevelDescription
offNo extended thinking
minimalBrief reasoning
lowQuick analysis
mediumBalanced (default)
highDeep analysis
xhighMaximum depth

Identity

[agent]
identity = "You are Aleph, a personal AI assistant. Be helpful, concise, and accurate."

# Group chat behavior
[agent.group_chat]
require_mention = true
prefix = "@aleph"

Gateway Configuration

[gateway]
# Port to listen on
port = 18790

# Bind address
bind = "127.0.0.1"    # localhost only
# bind = "0.0.0.0"    # all interfaces

# Authentication
require_auth = true

# TLS (optional)
[gateway.tls]
cert = "/path/to/cert.pem"
key = "/path/to/key.pem"

Channel Configuration

Telegram

[channel.telegram]
enabled = true
token = "123456:ABC..."

# Allowlist (optional)
allow_from = ["+1234567890"]

# Group behavior
[channel.telegram.groups]
"*" = { require_mention = true }

Discord

[channel.discord]
enabled = true
token = "YOUR_BOT_TOKEN"

# Guild/server restrictions
allow_guilds = ["guild-id-1", "guild-id-2"]

Provider Configuration

Aleph supports multiple LLM providers. Each provider is configured under the [provider] table:

[provider.claude]
protocol = "anthropic"
model = "claude-opus-4-20250514"
api_key = "sk-ant-..."

[provider.openai]
protocol = "openai"
model = "gpt-4o"
api_key = "sk-..."

See Providers for the full list of supported providers.

Session Configuration

[session]
# Auto-reset hour (0-23, local time)
auto_reset_hour = 4

# Session expiry
expiry_days = 30

# Compaction
[session.compaction]
enabled = true
threshold = 50000  # tokens

Environment Variables

Configuration values can use environment variables:

[channel.telegram]
token = "${TELEGRAM_BOT_TOKEN}"

Hot Reload

Configuration changes are automatically detected and applied. The gateway watches config.toml for changes and reloads without restart.

Configuration Locations

FilePurpose
~/.aleph/config.tomlMain configuration file
~/.aleph/defaults.tomlDefault value overrides
~/.aleph/config.toml.bakAutomatic backup before migrations

On this page