Configuration Overview

Snippbot uses a four-tier configuration system. Values are resolved in this priority order (highest first):

1. Environment variables    (SNIPPBOT_*, ANTHROPIC_API_KEY, etc.)
2. Encrypted SecretStore    (~/.snippbot/secrets.db — for sensitive keys only)
3. Config file              (~/.snippbot/config.toml)
4. Default values           (built into the application)

The first tier with a non-empty value wins.

Which tier applies to which key?

• Sensitive keys (API keys, tokens listed in UserConfig.SENSITIVE_KEYS): all four tiers are consulted. The CLI writes new sensitive values to the encrypted SecretStore — never to plaintext config.toml. Legacy plaintext values are auto-migrated to the SecretStore on first server start.
• Non-sensitive keys (ports, hosts, log level, booleans, paths): three tiers — env var → config file → default. The SecretStore tier is skipped.

This means you can safely commit an example config.toml without leaking secrets: sensitive values never end up in that file.

Note

The SecretStore tier was added in a later release and is transparent to users: snippbot config set anthropic_api_key sk-ant-... still works as before, but the value is now stored encrypted at rest. Use snippbot secrets for direct control of the encrypted vault.

---

Config file

The config file lives at ~/.snippbot/config.toml:

~/.snippbot/config.toml

# Server settings
server_host = ""  # Empty = dual-stack (IPv4 + IPv6)
server_port = 18781
log_level = "info"
auto_open_browser = true

# AI provider keys
anthropic_api_key = "sk-ant-..."
openai_api_key = ""

# Optional
data_dir = "~/.snippbot"

View and edit the config via CLI:

snippbot config list            # Show all values
snippbot config set log_level debug
snippbot config get server_port
snippbot config path            # Show file location

---

Environment variables

All config keys are available as environment variables. The naming convention is:

Config key	Environment variable
server_port	SNIPPBOT_PORT
server_host	SNIPPBOT_HOST
log_level	SNIPPBOT_LOG_LEVEL
anthropic_api_key	ANTHROPIC_API_KEY
openai_api_key	OPENAI_API_KEY

Note

Server settings use the SNIPPBOT_ prefix. API keys use their standard names (e.g., ANTHROPIC_API_KEY, not SNIPPBOT_ANTHROPIC_API_KEY).

For the full list, see Environment Variables.

---

Data separation

Snippbot separates system configuration from user profile data:

Data	Storage	Purpose
API keys, ports, log level	~/.snippbot/config.toml	System / service configuration
Display name, email, avatar, timezone	profile_settings.db	User profile and preferences
Auth credentials, sessions, API keys	auth.db	Authentication
Setup wizard progress	~/.snippbot/setup.json	Transient setup state

User profile data is managed via the Settings page in the UI, not via config.toml.

setup.json fields

The setup wizard writes the following fields to ~/.snippbot/setup.json as the user progresses:

Field	Type	Description
complete	bool	Whether the wizard finished. Once true, the file is locked from soft reset.
current_step	string	The last step the user was on (e.g. permissions, marketplace).
steps_completed	string[]	Ordered list of completed steps.
steps_skipped	string[]	Optional steps the user explicitly skipped via the Skip button (voice, permissions, marketplace).
permissions_granted	object	{ microphone, notifications } → `granted
essentials_selection	string[]	Package IDs the user chose from the Marketplace starter bundle.
essentials_installed	string[]	Package IDs that successfully installed.
first_agent_created	bool	Set after the Awakening flow finishes.
user_profile	object	{ display_name, email }.
voice_selection	object	{ tts_provider, tts_voice } written to VOICE.json on agent creation.

Provider catalog (LLM + voice) is sourced from the shared module snippbot_core.providers — adding or editing a provider only requires touching that file.

---

Ports

Service	Default	Environment variable
Backend API	18781	SNIPPBOT_PORT
Channel adapter	18790	SNIPPBOT_CHANNEL_PORT
Gateway	8787	SNIPPBOT_GATEWAY_PORT
UI dev server	5173	SNIPPBOT_UI_PORT

---

Related

• Environment Variables — full env var reference
• Config File — config.toml format and all keys
• Settings Reference — UI settings (9 categories)
• CLI: config command — manage config from the terminal
• CLI: secrets command — direct control of the encrypted SecretStore tier