Agent Configuration¶

The AI agent is configured through two mechanisms:

1. init.endo -- primary configuration via builtin properties (provider, model, limits, MCP servers, web search).
2. agent.yml -- API key store managed exclusively by endo agent login / endo agent logout.

All agent settings (provider selection, model, limits, plan mode, tracing) are configured in ~/.config/endo/init.endo. The agent.yml file only stores API keys.

Authentication¶

Manage API keys from the terminal:

# Interactive login (select provider, enter API key)
endo agent login
endo agent login claude

# Show configured providers and authentication status
endo agent status

# Remove a stored API key
endo agent logout
endo agent logout gemini

API keys are stored in ~/.config/endo/agent.yml. You can also set keys directly in init.endo (e.g., agent_claude_api_key <- "sk-ant-...") or via environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY).

Agent Settings (init.endo)¶

All properties are set from ~/.config/endo/init.endo using <- assignment syntax. They execute at shell startup and configure the agent before you enter agent mode. Properties can also be read as expressions (e.g., print agent_provider).

General¶

Claude (Anthropic)¶

OpenAI¶

OpenAI-Compatible¶

Google Gemini¶

Local (llama.cpp)¶

The local provider runs inference on your machine using GGUF models via llama.cpp. No API key is required -- authentication is based on having a valid model path configured. See Local LLM Inference for the full setup guide.

Plan Mode¶

Explore Sub-Agent¶

Session¶

Permissions¶

agent_permissions_policy <- "ask"
agent_trusted_tool <- ["read_file"; "glob"; "grep"; "search"]
agent_blocked_pattern <- ["rm -rf /"; ":(){ :|:& };:"]

Error Recovery¶

# Enable interactive error recovery prompt on command failure
agent_error_recovery_action <- "ask"

# Or automatically analyze failed commands without asking
# agent_error_recovery_action <- "analyze"

# Use a faster/cheaper model for error analysis
agent_error_recovery_model <- "claude-haiku-4-5-20251001"

By default, error recovery is disabled ("ignore"). Set to "ask" to show a prompt after each failed command offering to analyze the error, or "analyze" to automatically analyze without asking. When using "ask", options include "Analyze (always)" and "Ignore (always)" to set session-level overrides. Error analysis uses the Contour terminal's Semantic Block Query extension (DEC Mode 2034) to capture the failed command's output. Non-Contour terminals gracefully skip error recovery (no prompts appear).

Tracing¶

MCP Server Configuration¶

Model Context Protocol (MCP) servers expose external tools to the agent over a JSON-RPC 2.0 stdio transport. Configure them in ~/.config/endo/init.endo using three builtins:

Adding a Server¶

add_mcp_server "filesystem" "npx -y @modelcontextprotocol/server-filesystem /home/user"
add_mcp_server "github" "npx -y @modelcontextprotocol/server-github"

The first argument is a name (used for identification and set_mcp_env). The second is the command line -- Endo splits it on spaces into executable and arguments.

Setting Environment Variables¶

Some MCP servers need API keys or other environment variables:

set_mcp_env "github" "GITHUB_TOKEN" "$GITHUB_TOKEN"

Removing a Server¶

remove_mcp_server "filesystem"

Lifecycle¶

MCP servers are started when you enter agent mode (Ctrl+T) and shut down when you leave. Each server's tools appear alongside the built-in tools -- the agent can call them transparently.

If a server fails to start, the error is logged but agent mode still activates with the remaining tools.

Web Search Configuration¶

The agent's web_search tool can use DuckDuckGo (default, no API key), Brave Search, or Google Custom Search. Configure it in init.endo:

# Select search engine
agent_web_search_engine <- "duckduckgo"   # default, no key required
agent_web_search_engine <- "brave"
agent_web_search_engine <- "google"

# API key (required for Brave and Google)
agent_web_search_api_key <- "your-api-key"

# Maximum results per query (default: 5, max: 20)
agent_web_search_max_results <- 5

# Google Custom Search Engine ID (required for Google)
agent_web_search_cx <- "your-cx-id"

Complete init.endo Example¶

# ~/.config/endo/init.endo

# Agent provider and model (cloud)
agent_provider <- "claude"
agent_claude_model <- "claude-sonnet-4-6"
agent_log_tool_uses <- true

# -- Or use a local model instead --
# agent_provider <- "local"
# agent_local_model_path <- "~/.local/share/endo/models/qwen2.5-coder-7b-instruct-q4_k_m.gguf"
# agent_local_gpu_layers <- -1
# agent_local_context_size <- 32768

# Plan mode
agent_plan_mode_enabled <- true
agent_plan_mode_max_exploration_turns <- 20

# Explore sub-agent
agent_explore_max_turns <- 15

# Permissions
agent_permissions_policy <- "ask"
agent_trusted_tool <- ["read_file"; "glob"; "grep"; "search"]

# Error recovery
agent_error_recovery_action <- "ask"

# Tracing
agent_trace_max_files <- 10

# Shell prompt
shell_prompt_preset <- "endo-signature"

# MCP servers
add_mcp_server "filesystem" "npx -y @modelcontextprotocol/server-filesystem /home/user"
add_mcp_server "github" "npx -y @modelcontextprotocol/server-github"
set_mcp_env "github" "GITHUB_TOKEN" "$GITHUB_TOKEN"

# Web search
agent_web_search_engine <- "duckduckgo"

Further Reading¶

• Overview -- What the agent is and how to get started
• Local LLM Inference -- Offline inference with llama.cpp, model management
• Tools & Commands -- Built-in tools, slash commands, plan mode