Configuration Reference

Complete reference for ~/.ashlr/ashlr.yaml, environment variables, and backend configuration.

Config File Location

Ashlr AO stores its configuration at ~/.ashlr/ashlr.yaml. This file is auto-created on first run with sensible defaults. You can edit it manually or update it through the dashboard settings (Cmd+,) or the PUT /api/config endpoint.

Full Config Reference

Below is the complete ashlr.yaml with all available options and their defaults:

# ~/.ashlr/ashlr.yaml

server:
  host: "127.0.0.1"                    # Bind address (use 0.0.0.0 for Docker)
  port: 5111                            # HTTP port
  log_level: "INFO"                     # DEBUG, INFO, WARNING, ERROR

agents:
  max_concurrent: 16                    # Max simultaneous agents (clamped by license)
  default_role: "general"               # Default role for new agents
  default_working_dir: "~/Projects"     # Default working directory
  output_capture_interval_sec: 1.0      # tmux capture frequency (seconds)
  memory_limit_mb: 2048                 # Per-agent memory limit (MB)
  default_backend: "claude-code"        # Default backend (claude-code|codex|aider|goose)
  backends:
    claude-code:
      command: "claude"
      args: ["--dangerously-skip-permissions"]
    codex:
      command: "codex"
      args: []
    aider:
      command: "aider"
      args: []
    goose:
      command: "goose"
      args: []

llm:
  enabled: false                        # Enable intelligence layer
  provider: "xai"                       # LLM provider
  model: "grok-4-1-fast-reasoning"      # Model name
  api_key_env: "XAI_API_KEY"            # Env var holding the API key
  base_url: "https://api.x.ai/v1"      # API base URL
  summary_interval_sec: 10.0            # Agent summary generation interval
  meta_interval_sec: 30.0               # Fleet analysis interval

voice:
  enabled: true                         # Enable push-to-talk voice input
  ptt_key: "Space"                      # Push-to-talk key binding

licensing:
  key: ""                               # JWT license key (set via API or YAML)

auto_pilot:
  auto_restart_on_stall: false          # Auto-restart stalled agents
  auto_approve_enabled: false           # Enable pattern-based auto-approve
  auto_approve_patterns: []             # Regex patterns to auto-approve
  auto_pause_on_critical_health: false  # Pause agents on critical health
  file_lock_enforcement: false          # Prevent concurrent edits to same file

display:
  theme: "dark"                         # dark or light
  cards_per_row: 4                      # Agent cards per grid row

Server Settings

Agent Settings

Backend Configuration

Each backend defines the CLI command and default arguments used to spawn agents:

claude-code

agents:
  backends:
    claude-code:
      command: "claude"
      args: ["--dangerously-skip-permissions"]

Claude Code supports additional per-agent options at spawn time:

• Plan mode — Replaces --dangerously-skip-permissions with --permission-mode plan
• Model selection — Adds --model <model-name> flag
• Tool restriction — Adds --allowedTools <tool-list> flag
• Stream-json mode — Uses --print --output-format stream-json instead of tmux (non-interactive)

codex

agents:
  backends:
    codex:
      command: "codex"
      args: []

aider

agents:
  backends:
    aider:
      command: "aider"
      args: []

goose

agents:
  backends:
    goose:
      command: "goose"
      args: []

Intelligence (LLM) Settings

Voice Settings

Auto-Pilot Settings

Display Settings

Licensing

Environment Variables

Environment variables override config file values where applicable:

Updating Config at Runtime

You can update configuration without restarting the server:

Via the Dashboard

Open Settings (Cmd+,) to modify agent limits, backend settings, auto-pilot options, and display preferences. Changes are saved to YAML and applied to the running server immediately.

Via the API

curl -X PUT http://127.0.0.1:5111/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "agents": {
      "max_concurrent": 10,
      "default_backend": "claude-code"
    },
    "auto_pilot": {
      "auto_restart_on_stall": true
    }
  }'

The server validates the update, merges it with the current config, writes to ~/.ashlr/ashlr.yaml, and applies changes to the running process. If auth is enabled, only admin users can update the config.

Background Tasks

Ashlr runs 6 supervised background tasks that are configured implicitly by the settings above:

All background tasks are supervised with automatic restart on failure.