Configuration

The agent is configured through two files. Every value can also be overridden via environment variables.

Configuration Files

File	Purpose	Committed?
.env	Secrets (API keys, tokens)	No (gitignored)
agent.toml	Everything else	Yes

Environment variables take precedence over agent.toml values.

Sections Reference

[agent]

Core agent settings.

Key	Env Var	Default	Description
working_dir	AGENT_HOME	~/.agent	Working directory for the agent
default_persona	AGENT_DEFAULT_PERSONA	default	Default persona name
timezone	AGENT_TIMEZONE	UTC	Timezone for cron, DND, and time-aware features
restrict_to_working_dir	AGENT_RESTRICT_TO_WORKING_DIR	false	Restrict file access to working directory

[api]

LLM API configuration.

Key	Env Var	Default	Description
base_url	OPENAI_BASE_URL	https://api.deepseek.com/v1	OpenAI-compatible API endpoint
model	OPENAI_MODEL	—	Model name
temperature	OPENAI_TEMPERATURE	0.7	Sampling temperature
max_tokens	OPENAI_MAX_TOKENS	4096	Max response tokens
tool_choice	OPENAI_TOOL_CHOICE	auto	Tool choice mode
max_tool_rounds	MAX_TOOL_ROUNDS	50	Max tool-calling rounds per turn
context_window_warn_percent	CONTEXT_WINDOW_WARN_PERCENT	50	Warn when context window is this percent full

[api.retry]

Retry policy for transient failures.

Key	Env Var	Default	Description
max_retries	OPENAI_MAX_RETRIES	3	Max retry attempts
delay_ms	OPENAI_RETRY_DELAY_MS	1000	Initial delay in ms
backoff_multiplier	OPENAI_RETRY_BACKOFF_MULTIPLIER	2.0	Exponential backoff multiplier

[bash]

Bash tool settings.

Key	Env Var	Default	Description
default_workdir	BASH_DEFAULT_WORKDIR	/tmp	Default working directory
output_limit	BASH_OUTPUT_LIMIT	4000	Max output characters
clear_env	BASH_CLEAR_ENV	true	Clear environment variables before execution
foreground_max_ms	BASH_FOREGROUND_MAX_MS	300000	Max foreground execution time
background_detection	BASH_BACKGROUND_DETECTION	true	Detect nohup/disown/& wrappers

[web]

Web fetch tool settings.

Key	Env Var	Default	Description
response_limit	WEB_RESPONSE_LIMIT	8000	Max response characters
ssrf_protection	WEB_SSRF_PROTECTION	true	Enable SSRF protection
url_secret_scan	WEB_URL_SECRET_SCAN	true	Scan URLs for embedded secrets

[browser]

Browser automation tool settings.

Key	Env Var	Default	Description
command	BROWSER_COMMAND	npx agent-browser	Browser CLI command
headless	BROWSER_HEADLESS	true	Run in headless mode
engine	BROWSER_ENGINE	auto	Browser engine (chromium/firefox/webkit/auto)

[memory]

Memory plugin settings.

Key	Env Var	Default	Description
max_entry_chars	MEMORY_MAX_ENTRY_CHARS	2200	Max characters per memory entry
max_user_chars	MEMORY_MAX_USER_CHARS	1375	Max characters for user-provided content
scan_enabled	MEMORY_SCAN_ENABLED	true	Enable content validation scanning
dedup_enabled	MEMORY_DEDUP_ENABLED	true	Enable duplicate detection

[session]

Session lifecycle settings.

Key	Env Var	Default	Description
auto_title	SESSION_AUTO_TITLE	true	Auto-generate titles via LLM
retention_days	SESSION_RETENTION_DAYS	90	Auto-prune ended sessions after N days
crash_recovery	SESSION_CRASH_RECOVERY	true	Recover active sessions on daemon restart

[guardrails.tool_loop]

Circuit breaker for stuck tool loops.

Key	Env Var	Default	Description
enabled	GUARDRAILS_ENABLED	true	Enable circuit breaker
warn_threshold	GUARDRAILS_WARN_THRESHOLD	3	Consecutive loops before warning
block_threshold	GUARDRAILS_BLOCK_THRESHOLD	5	Consecutive loops before blocking
halt_threshold	GUARDRAILS_HALT_THRESHOLD	10	Consecutive loops before halting
no_progress_detection	GUARDRAILS_NO_PROGRESS	true	Detect idempotent tool calls

[context.compression]

Context window compression settings.

Key	Env Var	Default	Description
enabled	CONTEXT_COMPRESSION_ENABLED	true	Enable compression
trigger_percent	CONTEXT_COMPRESSION_TRIGGER	70	Trigger at this percent of context window
protected_head	CONTEXT_COMPRESSION_HEAD	2	Messages to protect at the head
protected_tail	CONTEXT_COMPRESSION_TAIL	6	Messages to protect at the tail

[gateway.telegram]

Telegram gateway settings.

Key	Env Var	Default	Description
notify_chat_id	TELEGRAM_NOTIFY_CHAT_ID	—	Default notification chat ID
dedup_window_ms	TELEGRAM_DEDUP_WINDOW_MS	10000	Deduplication window
polling_timeout	TELEGRAM_POLLING_TIMEOUT	30	Long-poll timeout in seconds
http_timeout_ms	TELEGRAM_HTTP_TIMEOUT_MS	90000	HTTP client timeout

[pulse], [reflection], [cron], [harness]

Autonomy features. Each has an enabled flag and feature-specific settings. See the Architecture page for context on how these fit together.

Environment Variable Precedence

The config loader checks, in order:

1. .env file
2. agent.toml defaults
3. Actual environment variables (highest priority)

This means you can override any agent.toml value at runtime:

OPENAI_MODEL=deepseek-v4-pro MAX_TOOL_ROUNDS=30 gleam run