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
passthrough_env	BASH_PASSTHROUGH_ENV	—	Comma-separated extra env vars to preserve

[web]

Web fetch tool settings.

Key	Env Var	Default	Description
fetch_backend	WEB_FETCH_BACKEND	httpc	HTTP backend: httpc (Erlang built-in) or curl
max_response_chars	WEB_MAX_RESPONSE_CHARS	8000	Truncate response body at this many characters
max_error_chars	WEB_MAX_ERROR_CHARS	500	Truncate error bodies at this many characters
request_timeout_ms	WEB_REQUEST_TIMEOUT_MS	30000	HTTP client timeout per request, in milliseconds
user_agent	WEB_USER_AGENT	agent/1.0	User-Agent header sent with every request

[web.security]

SSRF protection and URL safety scanning.

Key	Env Var	Default	Description
allow_private_ips	WEB_ALLOW_PRIVATE_IPS	false	Allow requests to private/internal IP ranges
scan_url_secrets	WEB_SCAN_URL_SECRETS	true	Scan URLs for embedded API keys/secrets

[code]

Code execution tool settings. Controls the sandbox for Python, JavaScript, and shell snippets.

Key	Env Var	Default	Description
timeout_cmd	CODE_TIMEOUT_CMD	timeout	Command for execution timeout (use gtimeout on macOS)
timeout_seconds	CODE_TIMEOUT_SECONDS	30	Max code execution time in seconds
max_output_chars	CODE_MAX_OUTPUT_CHARS	4000	Truncate stdout at this many characters
python_cmd	CODE_PYTHON_CMD	python3	Python interpreter command
javascript_cmd	CODE_JAVASCRIPT_CMD	node	Node.js command
shell_cmd	CODE_SHELL_CMD	sh	Shell interpreter command
tempdir_cmd	CODE_TEMPDIR_CMD	mktemp -d	Command to create temp directories

[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.

[logger]

Structured logging service. Outputs JSON-lines to file and human-readable format to stdout.

Key	Env Var	Default	Description
level	LOG_LEVEL	info	Minimum log level: debug, info, warn, or error
file	LOG_FILE	~/.agent/agent.log	Log file path (JSON-lines format)
max_file_size_mb	LOG_MAX_FILE_SIZE_MB	10	Rotate log file after this many MB
max_files	LOG_MAX_FILES	3	Keep this many rotated log files

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