Configuration

LLM Providers

Specifies configurations related to Large Language Model providers, detailing which models to use and their respective settings.

• llms: Defines the configuration for different LLM providers as a named map of LLM definitions where each can have the following properties.
  • provider: Type of provider, e.g., openai.
  • models: List of models supported by the provider, where each has the following properties:
    • name: Unique name for the model, which can be used with the session.model property.
    • model: The name of the model as defined by the provider
    • settings: Optional map of settings that are applied per model when in use
      • exclude_past_reasoning: Set to true to ask Enkaidu not to send reasoning content in responses from past turns when prompting the next turn if using this specific model. Some models (e.g. gemma4) recommend enabling this.
      • think: Set to one of default|none|low|medium|high. Unspecified means default.
      • New in 0.9.13 temperature: Set to a number greater than 0 and less than or equal to 2. Omitting it means default.
  • env: Environmental variables specific to the provider, essential for authentication and connection.

Example

llms:
  my-ollama:
    provider: ollama
    models:
    - name: glimmer
      model: muse-glimmer:30b-mxfp8
      settings:
        temperature: 1
        think: low
        exclude_past_reasoning: false

Session Settings Profile Config

Manages user session-specific configurations, including model selection and auto-loading preferences. Some properties within this section are optional.

• session: Configurations specific to a user session.
  • provider_type: (optional) Specifies the type of LLM provider to be used, such as openai or ollama. You never need this if you define llms, in which case you only need model property.
  • model: (optional) Defines the model used for the session, e.g., gpt4. When defining llms in the configuration, this can be the name of a model and there is no need for the above provide_type property.
  • streaming: Indicates whether streaming responses are supported. When disabled the formatted responses appear all at once. Streaming is enabled by default.
  • input_history_file: (optional) Path to a file for saving input history.
  • quiet: Set to true to enable a quiet mode that reduces the information messages that Enkaidu typically generates. Combined with streaming, this provides less verbose user experience for those times when we just don’t want to see how it all works all the time.
  • exclude_past_reasoning: Set to true to ask Enkaidu not to send reasoning content in responses from past turns when prompting the next turn. Some models (e.g. gemma4) recommend enabling this. (Use LLM model settings to control per model.)
  • allow_tool_discovery: Set to true to allow tool discovery / install by AI models. Disallowed by default.
  • allow_sub_agents: Set to true to allow spawning sub-agents by AI models. Disallowed by default.
  • New in 0.9.10 allow_global_state: Set to true to allow access to global state by AI models using tool calling. Disallowed by default.
  • New in 0.9.11 allow_shell_commands: Set to true to enable the AI models to run allowed and approved shell commands. Disallowed by default.
  • readonly: Set to true to restrict all available built-in tools to only those with read-only side-effects, effectively preventing the AI models from making any changes.

Example

session:
  # name of a model defined in `llms:` above
  model: glimmer          
  streaming: true
  quiet: true
  input_history_file: ./.enkaidu/input_history.yml
  # allow some system tools
  allow_sub_agents: true
  allow_shell_commands: true

Autoload Settings Profile Config

Specifies when and which tools, toolsets, system prompts to enable / load when starting Enkaidu.

• auto_load: Contains settings for automatically loading specific resources.
  • system_prompt_name: (optional) Specify the session’s system prompt by using the name of the system prompt template.
  • mcp_servers: (optional) List of MCP servers to automatically connect to on startup.
  • toolsets: (optional) List of toolsets to automatically load, where each toolset can be specified by name to load all tools, or as a map of name: and select: to specify the tools to load from the named toolset.

Example

auto_load:
  system_prompt_name: dev_assistant
  mcp_servers:
    - weather
  toolsets:
    - DateAndTime
    - name: TextEditing
      select:
        - read_text_file

Tool Settings Profile Config

Some built-in tools support configurable settings, which can be specified using tool settings in the confuration YAML.

• tool_settings: Contains settings for tools by name
  • <tool_name>:
    • <setting_name>: <setting_value> where a value can be
      • a simple string, integer, or boolean, or
      • an array with only one of the simple types (i.e. array of strings)

Example

Look up the various system tools and built-in toolsets for specific settings for tools.

tool_settings:
  shell_command:
    allowed_commands: [ "find", "grep" ]

Cordon (Sandbox) Settings Profile Config

New in 0.9.11 Enkaidu supports sandboxing execution of shell commands for platforms that support it. On macOS this is done using the built-in sandbox-exec helper command. On Linux platforms Enkaidu looks for bubblewrap which has to be installed by the user.

Warning If your platform does not have a supported sandbox, then Enkaidu runs in unsafe mode and runs shell commands directly.

• cordon:
  • confirm: defaults to true, to confirm if cordon is available for your platform.
  • mode: use this to set how the cordon is deployed, or disabled, by using one of the following values:
    • commands (default) to run shell commands within a cordon
    • unsafe to not use a cordon
  • policy: can be used to define custom policy rules for the cordon.
    • read_only_paths: [...] (default []) array of paths to allow read-only access from within the cordon; executables in these paths are allowed to be run as well.
    • read_write_paths: [...] (default []) array of paths where read and write access is allowed from within the cordon.
    • New in 0.9.13 allow_network: true | false (default false) to enable networking (inbound, outbound, and binding) for commands executed within the cordon. Be careful enabling this: it is all-or-nothing at this time — every command run in the cordon gets full network access with no way to restrict hosts or ports.
  • workspace: Properties here can be used enable / configure presets specific to your workspace.
    • using_brew: true | false (default false) to ensure brew-installed commands are reachable from within the cordon
    • using_ruby: in two ways
      • using_ruby: true (default false) to use platform-supplied Ruby, including brew-installed Ruby if using_brew is true.
      • using_ruby:
        • ruby_path: PATH_STR will ensure the Ruby at this location is allowed
    • using_python: in two ways
      • using_python: true (default false) to use platform-supplied Python, including brew-installed Python if using_brew is true.
      • using_python:
        • venv_path: PATH_STR will ensure Python virtual environment is allowed.

Example

cordon:
  # shell commands run inside the cordon
  mode: commands            
  policy:
    read_only_paths:
      - /usr/share/zoneinfo
    read_write_paths:
      - ./scratch
    # networking for cordon commands is off by default
    allow_network: false
  workspace:
    using_brew: true
    using_ruby: true

Macros

• macros: Define named macros that can be invoked using !<name>
  • <name>:
    • description: An description of the macro (required)
    • queries: An array of queries where each entry is treated as if the user typed in a query.
  • Macros support parameter substitution, enabling macro calls that can include positional and named arguments which are in turn substituted before the macro is expanded into the command queue.
    • Positional parameters are specified as %{N} where N is a positive integer.
    • Named parameters are specified as %{WORD} where WORD is a string with letters and digits and _.
    • When calling a macro, positional parameters must precede named ones.
    • Example: !explain_folder path=src/ will substitute all references to %{path} in all the macro queries.
    • Experimental New in 0.9.11 A query entry can be a block, started with the <enter> key whose value is an array of nested queries. A block can be exited early using a ?break conditional command. See Macros for the full description and an example.

Example

macros:
  explain_folder:
    description: |
      Explain the contents of a folder
    queries:
      - |
        Explain the purpose and structure
        of the code in %{path}

This example macro can be invoked from the Enkaidu prompt input like this: !explain_folder path=./src/

Custom Prompts

• prompts: Define named custom parametrized prompt templates. These are auto-loaded when Enkaidu starts.
  • <prompt_name>:
    • description: A description of the prompt
    • arguments: This is a named map of aguments:
    • <arg_name>:
      • description: A description of the argument
    • template: The template is a string based on the Liquid templating language as implemented by the liquid.cr Crystal shard. The template is invoked with arguments as well as system and profile properties as follows:
    • Arguments are available with the arg. prefix
    • Profile variables are available with the var. prefix
    • System properties are available via the sys. prefix

Example

prompts:
  define:
    description: Define a word or phrase
    arguments:
      word:
        description: |
          What do you want to define?
    template: |
      Define the meaning of "{{ word }}".
      If there are multiple definitions,
      present them as a list.

When you invoke this example macro at the prompt input as /prompt use define, Enkaidu will prompt you to enter the word or phrase.

System Prompts

• system_prompts: Define named system prompts as templates. These are auto-loaded when Enkaidu starts.
  • <prompt_name>:
    • description: An optional description of the prompt
    • template: The template is a string based on the Liquid templating language as implemented by the liquid.cr Crystal shard. The template is invoked with system and profile properties as follows:
    • Profile variables are available with the var. prefix
    • System properties are available via the sys. prefix

Example

system_prompts:
  shakespeare:
    description: Victorian era role play
    template: |
      You are Shakespeare. Respond as you 
      would in your time in history. Don't mind
      that the subject of my questions may not
      mean anything to someone of your time.

MCP Servers

Defines the configuration for MCP (Multiple Control Protocol) servers, enabling extended functionalities through server connections.

• mcp_servers: Defines one or more MCP servers as a named map of server definitions where each can have the following properties. These can be auto-loaded (see session above) or you can load them using the /use_mcp command with the name in the config.
  • url: URL endpoint for the MCP server.
  • transport: (optional) The MCP protocol supports either http (modern) or legacy; default is auto which tries to pick the right one. For quick connectivity specify the transport.
  • bearer_auth_token: (optional) Token or API key required for authenticated access to the server that supports authentication.

Example

mcp_servers:
  weather:
    url: https://mcp.example.com/weather
    transport: http
    # only if the server requires authentication
    bearer_auth_token: secret_token  

Debug Settings

Controls debug settings useful when trouble-shooting connectivity issues.

• debug: Debug configuration applicable to the whole application.
  • trace_mcp: Enables tracing of MCP communication, useful for debugging purposes.
  • recording_file: (optional) Path to a file where session recordings are saved.

Example

debug:
  trace_mcp: true
  recording_file: ./logs/session-recording.json