Configuration

Moltis is configured through moltis.toml, located in ~/.config/moltis/ by default.

On first run, a complete configuration file is generated with sensible defaults. You can edit it to customize behavior.

Configuration File Location

Basic Settings

[server]
port = 13131                    # HTTP/WebSocket port
bind = "0.0.0.0"               # Listen address

[identity]
name = "Moltis"                 # Agent display name

[tools]
agent_timeout_secs = 600        # Agent run timeout (seconds, 0 = no timeout)
agent_max_iterations = 25       # Max tool call iterations per run

LLM Providers

Configure providers through the web UI or directly in moltis.toml. API keys can be set via environment variables (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY) or in the config file.

[providers]
offered = ["anthropic", "openai", "gemini"]

[providers.anthropic]
enabled = true

[providers.openai]
enabled = true
models = ["gpt-5.3", "gpt-5.2"]
stream_transport = "sse"        # "sse", "websocket", or "auto"

[providers.gemini]
enabled = true
models = ["gemini-2.5-flash-preview-05-20", "gemini-2.0-flash"]

[providers.local-llm]
enabled = true
models = ["qwen2.5-coder-7b-q4_k_m"]

[chat]
priority_models = ["gpt-5.2"]

See Providers for the full list of supported providers and configuration options.

Sandbox Configuration

Commands run inside isolated containers for security:

[tools.exec.sandbox]
mode = "all"                    # "off", "non-main", or "all"
scope = "session"               # "command", "session", or "global"
workspace_mount = "ro"          # "ro", "rw", or "none"
# host_data_dir = "/host/path/data"  # Optional override if auto-detection cannot resolve the host path
home_persistence = "shared"     # "off", "session", or "shared" (default: "shared")
# shared_home_dir = "/path/to/shared-home"  # Optional path for shared mode
backend = "auto"                # "auto", "docker", or "apple-container"
no_network = true

# Packages installed in the sandbox image
packages = [
    "curl",
    "git",
    "jq",
    "tmux",
    "python3",
    "python3-pip",
    "nodejs",
    "npm",
    "golang-go",
]

If Moltis runs inside Docker and also mounts the host container socket (/var/run/docker.sock), Moltis now auto-detects the host path backing /home/moltis/.moltis from the parent container’s mount table. If that inspection cannot resolve the correct path, set host_data_dir explicitly.

Web Search

Configure the built-in web_search tool:

[tools.web.search]
enabled = true
provider = "brave"               # "brave" or "perplexity"
max_results = 5                  # 1-10
timeout_seconds = 30
cache_ttl_minutes = 15
duckduckgo_fallback = false      # Default: do not use DuckDuckGo fallback
# api_key = "..."                # Brave key, or use BRAVE_API_KEY

[tools.web.search.perplexity]
# api_key = "..."                # Or use PERPLEXITY_API_KEY / OPENROUTER_API_KEY
# base_url = "..."               # Optional override
# model = "perplexity/sonar-pro" # Optional override

If no search API key is configured:

• with duckduckgo_fallback = false (default), Moltis returns a clear hint to set BRAVE_API_KEY or PERPLEXITY_API_KEY
• with duckduckgo_fallback = true, Moltis attempts DuckDuckGo HTML search, which may hit CAPTCHA/rate limits

Skills

Configure skill discovery and agent-managed personal skills:

[skills]
enabled = true
auto_load = ["commit"]
enable_agent_sidecar_files = false  # Opt-in: allow agents to write sidecar text files in personal skills

enable_agent_sidecar_files is disabled by default. When enabled, Moltis registers the write_skill_files tool so agents can write supplementary files such as script.sh, Dockerfile, templates, or _meta.json inside <data_dir>/skills/<name>/. Writes stay confined to that personal skill directory, reject path traversal and symlink escapes, and are recorded in ~/.moltis/logs/security-audit.jsonl.

Chat Message Queue

When a new message arrives while an agent run is already active, Moltis can either replay queued messages one-by-one or merge them into a single follow-up message.

[chat]
message_queue_mode = "followup"  # Default: one-by-one replay

# Options:
#   "followup" - Queue each message and run them sequentially
#   "collect"  - Merge queued text and run once after the active run

Memory System

Long-term memory uses embeddings for semantic search:

[memory]
backend = "builtin"             # Or "qmd"
provider = "openai"             # Or "local", "ollama", "custom"
model = "text-embedding-3-small"
citations = "auto"              # "on", "off", or "auto"
llm_reranking = false
session_export = false

Authentication

Authentication is only required when accessing Moltis from a non-localhost address. When running on localhost or 127.0.0.1, no authentication is needed by default.

When you access Moltis from a network address (e.g., http://192.168.1.100:13131), a one-time setup code is printed to the terminal. Use it to set up a password or passkey.

[auth]
disabled = false                # Set true to disable auth entirely

Hooks

Configure lifecycle hooks:

[hooks]
[[hooks.hooks]]
name = "my-hook"
command = "./hooks/my-hook.sh"
events = ["BeforeToolCall", "AfterToolCall"]
timeout = 5                     # Timeout in seconds

[hooks.hooks.env]
MY_VAR = "value"               # Environment variables for the hook

See Hooks for the full hook system documentation.

MCP Servers

Connect to Model Context Protocol servers:

[mcp]
request_timeout_secs = 30
                                    # Default timeout for MCP requests (seconds)

[mcp.servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
request_timeout_secs = 90        # Optional override for this server

[mcp.servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_..." }

[mcp.servers.remote_api]
transport = "sse"
url = "https://mcp.example.com/mcp?api_key=$REMOTE_MCP_KEY"
headers = { Authorization = "Bearer ${REMOTE_MCP_TOKEN}" }

Remote MCP URLs and headers support $NAME or ${NAME} placeholders. For live remote servers, values resolve from Moltis-managed env overrides, either [env] in config or Settings → Environment Variables.

Telegram Integration

[channels.telegram.my-bot]
token = "123456:ABC..."
dm_policy = "allowlist"
allowlist = ["123456789"]       # Telegram user IDs or usernames (strings)

See Telegram for full configuration reference and setup instructions.

Discord Integration

[channels]
offered = ["telegram", "discord"]

[channels.discord.my-bot]
token = "MTIzNDU2Nzg5.example.bot-token"
dm_policy = "allowlist"
mention_mode = "mention"
allowlist = ["your_username"]

See Discord for full configuration reference and setup instructions.

Slack Integration

[channels]
offered = ["slack"]

[channels.slack.my-bot]
bot_token = "xoxb-..."
app_token = "xapp-..."
dm_policy = "allowlist"
allowlist = ["U123456789"]

See Slack for full configuration reference and setup instructions.

TLS / HTTPS

[tls]
enabled = true
cert_path = "~/.config/moltis/cert.pem"
key_path = "~/.config/moltis/key.pem"
# If paths don't exist, a self-signed certificate is generated

# Port for the plain-HTTP redirect / CA-download server.
# Defaults to the server port + 1 when not set.
# http_redirect_port = 13132

Override via environment variable: MOLTIS_TLS__HTTP_REDIRECT_PORT=8080.

Tailscale Integration

Expose Moltis over your Tailscale network:

[tailscale]
mode = "serve"                  # "off", "serve", or "funnel"
reset_on_exit = true

Observability

[metrics]
enabled = true
prometheus_endpoint = true

Process Environment Variables ([env])

The [env] section injects variables into the Moltis process at startup. This is useful in Docker deployments where passing individual -e flags is inconvenient, or when you want API keys stored in the config file rather than the host environment.

[env]
BRAVE_API_KEY = "your-brave-key"
OPENROUTER_API_KEY = "sk-or-..."
ELEVENLABS_API_KEY = "..."

Precedence: existing process environment variables are never overwritten. If BRAVE_API_KEY is already set via docker -e or the host shell, the [env] value is skipped. This means docker -e always wins.

Environment Variables

All settings can be overridden via environment variables:

CLI Flags

moltis --config-dir /path/to/config --data-dir /path/to/data

Complete Example

[server]
port = 13131
bind = "0.0.0.0"

[identity]
name = "Atlas"

[tools]
agent_timeout_secs = 600
agent_max_iterations = 25

[providers]
offered = ["anthropic", "openai", "gemini"]

[tools.exec.sandbox]
mode = "all"
scope = "session"
workspace_mount = "ro"
home_persistence = "session"
# shared_home_dir = "/path/to/shared-home"
backend = "auto"
no_network = true
packages = ["curl", "git", "jq", "python3", "nodejs", "golang-go"]

[memory]
backend = "builtin"
provider = "openai"
model = "text-embedding-3-small"

[auth]
disabled = false

[hooks]
[[hooks.hooks]]
name = "audit-log"
command = "./hooks/audit.sh"
events = ["BeforeToolCall"]
timeout = 5