Environment Variables - Dark-Alex-17/coyote GitHub Wiki

Coyote is designed to be highly dynamic and customizable. As a result, Coyote utilizes a number of environment variables that can be used to modify its behavior at runtime without needing to modify the existing configuration files.

Coyote also supports defining environment variables via a .env file in the Coyote configuration directory. This directory varies between systems, so you can find the location of your configuration directory using the following command:

dirname $(coyote --info | grep ^config_file | awk '{print $2}')

Global Configuration Related Variables

All configuration items in the global config file have environment variables that can be overridden at runtime. To see all configuration options and more thorough descriptions, refer to the example config file.

Below are the most commonly used configuration settings and their corresponding environment variables:

Setting Environment Variable
model COYOTE_MODEL
temperature COYOTE_TEMPERATURE
top_p COYOTE_TOP_P
reasoning_effort COYOTE_REASONING_EFFORT
stream COYOTE_STREAM
save COYOTE_SAVE
editor COYOTE_EDITOR
wrap COYOTE_WRAP
wrap_code COYOTE_WRAP_CODE
save_session COYOTE_SAVE_SESSION
compression_threshold COYOTE_COMPRESSION_THRESHOLD
function_calling_support COYOTE_FUNCTION_CALLING_SUPPORT
enabled_tools COYOTE_ENABLED_TOOLS
tool_timeout COYOTE_TOOL_TIMEOUT
mcp_server_support COYOTE_MCP_SERVER_SUPPORT
enabled_mcp_servers COYOTE_ENABLED_MCP_SERVERS
rag_embedding_model COYOTE_RAG_EMBEDDING_MODEL
rag_reranker_model COYOTE_RAG_RERANKER_MODEL
rag_top_k COYOTE_RAG_TOP_K
rag_chunk_size COYOTE_RAG_CHUNK_SIZE
rag_chunk_overlap COYOTE_RAG_CHUNK_OVERLAP
rag_extractor_model COYOTE_RAG_EXTRACTOR_MODEL
rag_extractor_prompt COYOTE_RAG_EXTRACTOR_PROMPT
rag_graph_hops COYOTE_RAG_GRAPH_HOPS
highlight COYOTE_HIGHLIGHT
raw_markdown COYOTE_RAW_MARKDOWN
theme COYOTE_THEME
serve_addr COYOTE_SERVE_ADDR
user_agent COYOTE_USER_AGENT
save_shell_history COYOTE_SAVE_SHELL_HISTORY
sync_models_url COYOTE_SYNC_MODELS_URL

Client Related Variables

The following environment variables are available for clients in Coyote:

Environment Variable Description
{client}_API_KEY For clients that require an API key, you can define the keys either through environment variables or
using the vault. The variables are named after the client to which they apply;
e.g. OPENAI_API_KEY, GEMINI_API_KEY, etc.
COYOTE_PLATFORM Combine with {client}_API_KEY to run Coyote without a configuration file.
This variable is ignored if a configuration file exists.
COYOTE_PATCH_{client}_CHAT_COMPLETIONS Patch chat completion requests to models on the corresponding client; Can modify the URL, body,
or headers.
COYOTE_SHELL Specify the shell that Coyote should be using when executing commands
COYOTE_TOOL_TIMEOUT Wall-clock cap in seconds for any single tool-call subprocess (built-in and custom tools alike).
When exceeded, the tool process is killed and a tool_call_error is returned to the model instead of hanging the session forever.
Set to 0 for unlimited. Default: 1800 (30 minutes).
Counterpart of the tool_timeout config key; the environment variable takes precedence.
COYOTE_CURRENT_MODEL Set by Coyote (not read by it) in the environment of every tool-call subprocess: the running session's active model in client:name form (e.g. claude:claude-opus-5).
Lets tools adapt to the model driving the session — e.g. web_search_coyote.sh prefers the current model for native web search when it supports it, falling back to WEB_SEARCH_MODEL otherwise.
Agent-declared variables: envs with the same name take precedence.

Files and Directory Related Variables

You can also customize the files and directories that Coyote loads its configuration files from:

Environment Variable Description Default Value
COYOTE_CONFIG_DIR Customize the location of the Coyote configuration directory. Also holds the mesh identity and trust list (mesh/). <user-config-dir>/coyote
COYOTE_CACHE_DIR Customize the location of the Coyote cache directory. Used for the log file, OAuth tokens, the embedded sbx kit cache, the embedded sbx vault-provider mixin cache, and the mesh peer table, knocks, correlations, propagation fetch store and instance locks (mesh/; the full list is on What is on disk). <user-cache-dir>/coyote
COYOTE_ENV_FILE Customize the location of the .env file to load at startup. <coyote-config-dir>/.env
COYOTE_CONFIG_FILE Customize the location of the global config.yaml configuration file. <coyote-config-dir>/config.yaml
COYOTE_ROLES_DIR Customize the location of the roles directory. <coyote-config-dir>/roles
COYOTE_SESSIONS_DIR Customize the location of the global sessions directory. Does not affect workspace sessions (.coyote/sessions). <coyote-config-dir>/sessions
COYOTE_RAGS_DIR Customize the location of the rags directory. <coyote-config-dir>/rags
COYOTE_FUNCTIONS_DIR Customize the location of the functions directory. <coyote-config-dir>/functions
COYOTE_HOOKS_DIR Customize the location of the hooks directory that --install-builtins hooks and bundle installs write hook scripts to. Note: relative global-hook commands (./hooks/x.sh) still resolve against the config directory. <coyote-config-dir>/hooks
COYOTE_WORKSPACE_CONFIG_DIR Customize the workspace-specific configuration directory. Useful when working with other CLIs like .claude. <current_working_directory>/.coyote

Agent Related Variables

You can also customize the location of full agent configurations using the following environment variables:

Environment Variable Description
<AGENT_NAME>_CONFIG_FILE Customize the location of the agent's configuration file; e.g. SQL_CONFIG_FILE
<AGENT_NAME>_MODEL Customize the model used for the agent; e.g SQL_MODEL
<AGENT_NAME>_TEMPERATURE Customize the temperature used for the agent; e.g. SQL_TEMPERATURE
<AGENT_NAME>_TOP_P Customize the top_p used for the agent; e.g. SQL_TOP_P
<AGENT_NAME>_GLOBAL_TOOLS Customize the global_tools that are enabled for the agent (a JSON string array); e.g. SQL_GLOBAL_TOOLS
<AGENT_NAME>_MCP_SERVERS Customize the mcp_servers that are enabled for the agent (a JSON string array); e.g. SQL_MCP_SERVERS
<AGENT_NAME>_AGENT_SESSION Customize the agent_session used with the agent; e.g. SQL_SESSION
<AGENT_NAME>_INSTRUCTIONS Customize the instructions for the agent; e.g. SQL_INSTRUCTIONS
<AGENT_NAME>_VARIABLES Customize the variables used for the agent (in JSON format of [{"key1": "value1", "key2": "value2"}]);
e.g. SQL_VARIABLES

Hook Related Variables

Hooks are external commands Coyote runs when lifecycle events fire. Coyote sets the following variables in the environment of every hook process (which ones are present depends on the event; see the event catalog for the per-event breakdown):

Environment Variable Description
COYOTE_EVENT The dotted event name that fired, e.g. turn.completed (set on every event)
COYOTE_HOOK_NAME The name: of the hook being run (set on every event)
COYOTE_CONFIG_DIR The Coyote configuration directory (set on every event)
COYOTE_EVENT_TIMESTAMP When the event fired, RFC 3339 UTC (set on every event)
COYOTE_SESSION_ID The active session's name, when a session is present
COYOTE_AGENT_NAME The active agent's name, when an agent is present
COYOTE_ERROR The turn's error text, on turn.failed
COYOTE_TOOL_NAME The tool name (prefixes intact, e.g. user__select, mcp_invoke_github), on tool.* and job.* events
COYOTE_TOOL_DURATION_MS Tool wall-clock duration, on tool.completed
COYOTE_TOOL_ERROR The tool's error text, on tool.failed
COYOTE_HOOK_PAYLOAD_FILE Path to a temporary read-only JSON file holding the tool call's arguments, on tool.* events. See the payload file.
COYOTE_LLM_PROVIDER The LLM client name, on llm.request.* events
COYOTE_LLM_MODEL The model id, on llm.request.* events
COYOTE_LLM_DURATION_MS Request duration, on llm.request.completed
COYOTE_LLM_ERROR_KIND aborted, api_error, or other, on llm.request.failed
COYOTE_LLM_STATUS The HTTP status code, on llm.request.failed with kind api_error
COYOTE_LLM_ERROR The request's error text (the immediate error only, like COYOTE_TOOL_ERROR), on llm.request.failed
COYOTE_AGENT_ID The agent run's id (spawn id, or top-<name>-<nonce> for top-level runs), on agent.* events
COYOTE_AGENT_ERROR The agent run's error text, on agent.failed
COYOTE_ESCALATION_ID The escalation's id (stable across both events for one escalation), on escalation.* events
COYOTE_ESCALATION_FROM_AGENT_ID The asking agent's id, on escalation.* events
COYOTE_ESCALATION_FROM_AGENT_NAME The asking agent's name, on escalation.* events
COYOTE_ESCALATION_QUESTION The escalated question text, on escalation.* events
COYOTE_ESCALATION_REPLY The submitted reply text, on escalation.answered
COYOTE_NODE_ID The graph node's id, on graph.node.* events
COYOTE_NODE_TYPE The graph node's type, on graph.node.* events
COYOTE_NODE_DURATION_MS Node duration, on graph.node.completed / graph.node.failed
COYOTE_NODE_ROUTE The route taken out of the node (when known), on graph.node.completed
COYOTE_NODE_ERROR The node's error text, on graph.node.failed
COYOTE_JOB_ID The background job's id, on job.* events
COYOTE_JOB_ERROR The job's error text, on job.failed

Additionally, the bundled example hook log-events.sh reads COYOTE_HOOK_LOG. The log file it appends event snapshots to (default: ${XDG_STATE_HOME:-$HOME/.local/state}/coyote/hooks.log). See Hooks for the full contract, and COYOTE_HOOKS_DIR above for relocating the hooks/ directory itself.

No COYOTE_MESH_* variable overrides a mesh: config key. The COYOTE_MESH_* names you will meet are hook payload variables set by the mesh.* events, listed under Mesh events, and test-suite switches (COYOTE_MESH_INTEROP*, COYOTE_MESH_FUZZ_*), listed under How it is tested.

Sandbox Related Variables

The following variable controls Coyote's Sandbox mode:

Environment Variable Description Default Value
COYOTE_SANDBOX_KIT Override the path to the sbx kit used by coyote --sandbox. When set, Coyote skips extracting its embedded kit and passes this directory to sbx create --kit instead. Use for kit development, hardening, or pointing at a fork of the embedded kit. coyote --info | grep sbx_kit_dir | awk '{print $2}' (extracted)

Notes:

  • If COYOTE_SANDBOX_KIT points to a non-existent path, coyote --sandbox aborts with an error before any sandbox is created.
  • The path is passed verbatim to sbx create --kit; it must be a valid sbx kit (containing spec.yaml), not just any directory.
  • No environment variables map to the sandbox-mode CLI flags (--fresh, --no-mixins). These are intentionally CLI-only. They're one-time per-invocation decisions, not configuration knobs.

Logging Related Variables

The following variables can be used to change the log level of Coyote or the location of the log file:

Environment Variable Description Default Value
COYOTE_LOG_LEVEL Customize the log level of Coyote INFO
COYOTE_LOG_PATH Customize the location of the Coyote log file <user-cache-dir>/coyote/coyote.log

Pro-Tip: You can always tail the Coyote logs using the --tail-logs flag. If you need to disable color output, you can also pass the --disable-log-colors flag as well.

Miscellaneous Variables

Environment Variable Description Default Value
AUTO_CONFIRM Bypass all guard_* checks in the bash prompt helpers; useful for agent composition and routing. Set automatically when passing --dangerously-skip-permissions, --headless, or --acp-server (Coyote sets AUTO_CONFIRM=true for the process and all spawned tools/agents). See Unattended Mode.
LLM_TOOL_DATA_FILE Set automatically by Coyote on Windows. Points to a temporary file containing the JSON tool call data.
Tool scripts (run-tool.sh, run-agent.sh, etc.) read from this file instead of command-line args
to avoid JSON escaping issues when data passes through cmd.exe → bash. Not intended to be set by users.
COYOTE_SHOW_TOOL_CALLS Force tool-call log lines ("Call fs_ls ...") even when stdout is not a terminal, e.g. when running under pueue, cron, or with output piped to a file. Opt in with COYOTE_SHOW_TOOL_CALLS=1 (or "true").
⚠️ **GitHub.com Fallback** ⚠️