---
title: Configuration
description: Full reference for ~/.aimux/config.yaml
---

All configuration lives in `~/.aimux/config.yaml`. Every setting is optional. Defaults are shown below.

## Full Example

```yaml
providers:
  claude:
    enabled: true
  codex:
    enabled: true
  gemini:
    enabled: true

# Six orthogonal axes
runtime: "local"              # WHERE: local | container
execution: "local"            # WHERE tools run: local | hybrid
shell: "/bin/zsh"             # WHICH: shell binary
session_manager: "tmux"       # SESSION: tmux | direct
# terminal emulator: auto-detected (not configurable)

refresh_interval: "2s"

resume:
  skip_permissions: false

sessions:
  auto_title: false
  title_model: "flash"

notifications:
  enabled: true
  on_waiting: true
  on_error: true
  on_idle: false
  on_done: true
  sound: false
  bell: true
  desktop: true

export:
  endpoint: "localhost:5001"
  insecure: true
  mlflow:
    experiment_id: "1"

otel:
  enabled: false
  port: 4318

quick_launch:
  directories:
    - "~/projects/my-app"
    - "~/projects/my-lib"

tasks:
  backend: "auto"
  default_list: ""
  prompt_template: "Work on the following task: {title}\n\nDetails: {notes}\n\nAdditional instructions: {user_prompt}\n\nWhen done, summarize what you did."

auto_archive_after: "1h"

badges:
  - path: "package.json"
    json_path: "$.version"
    label: "v"
    color: "#22C55E"
  - path: "Cargo.toml"
    json_path: ""
    label: "rust"
    color: "#F5921B"

runtimes:
  devbox:
    type: container
    engine: podman
    image: "ghcr.io/my-org/agent-sandbox:latest"

kubernetes:
  enabled: false
  redis_url: ""
  team_id: ""
  namespace: "agents"
  kubeconfig: ""
  otel_endpoint: ""
```

## Providers

Enable or disable agent providers. Unknown providers default to enabled.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | `true` | Whether to discover agents from this provider |
| `binary` | string | auto-detect | Override the binary path for this provider |

## Config Axes

aimux has six orthogonal configuration axes:

### Runtime (WHERE the agent runs)

| Value | Status | Description |
|-------|--------|-------------|
| `local` | **Supported** | Default. Agent runs as a process on your machine |
| `container` | **Supported** | Agent runs inside a Podman/Docker container |

### Shell (WHICH shell interprets commands)

| Value | Status | Description |
|-------|--------|-------------|
| `/bin/zsh` | **Supported** | Default if `$SHELL` is zsh |
| `/bin/bash` | **Supported** | |
| `/bin/fish` | **Supported** | |

### Execution (WHERE tool calls run)

| Value | Status | Description |
|-------|--------|-------------|
| `local` | **Supported** | Default. Tools execute on the same machine as the agent |
| `hybrid` | **Planned** | Agent runs locally, tool calls forwarded to remote host (K8s pod or SSH) |

### Session Manager (HOW terminal sessions are managed)

| Value | Status | Description |
|-------|--------|-------------|
| `tmux` | **Supported** | Default. Sessions persist after detach |
| `direct` | **Supported** | Agent runs in foreground, dies when terminal closes |

### Terminal Emulator (auto-detected, not configurable)

| Emulator | Detection | Used for |
|----------|-----------|----------|
| iTerm2 | `$TERM_PROGRAM == "iTerm.app"` | Jump-to-session via split pane |
| Others | Fallback | tmux pane |

## General

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `refresh_interval` | string | `"2s"` | How often to scan for agents |
| `runtime` | string | `"local"` | WHERE: `"local"` or `"container"` |
| `shell` | string | `$SHELL` | WHICH shell for agent sessions. Falls back to `$SHELL`, then `/bin/sh` |
| `execution` | string | `"local"` | WHERE tools run: `"local"` or `"hybrid"` |
| `session_manager` | string | `"tmux"` | HOW terminal sessions are managed |

## Resume

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `skip_permissions` | bool | `false` | Always pass `--dangerously-skip-permissions` on resume |

## Sessions

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `auto_title` | bool | `false` | Generate titles via LLM on session discovery |
| `title_model` | string | `"flash"` | LLM for title generation: `"flash"`, `"haiku"`, `"sonnet"`, `"opus"` |
| `api_key` | string | env var | API key for title generation (overrides `GOOGLE_API_KEY` / `ANTHROPIC_API_KEY`) |

## Notifications

macOS notification settings. All default to sensible values.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | `true` | Master switch for all notifications |
| `on_waiting` | bool | `true` | Notify when agent needs permission |
| `on_error` | bool | `true` | Notify when agent crashes |
| `on_idle` | bool | `false` | Notify when agent finishes a turn |
| `on_done` | bool | `true` | Notify when agent finishes |
| `sound` | bool | `false` | Play macOS notification sound |
| `bell` | bool | `true` | Terminal bell on attention events |
| `desktop` | bool | `true` | macOS Notification Center alerts |

## Export

OTEL/HTTP export settings for sending traces to MLflow, Jaeger, or any OTLP-compatible backend.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `endpoint` | string | | OTLP/HTTP endpoint (e.g., `"localhost:5001"`) |
| `insecure` | bool | `true` | Use HTTP instead of HTTPS |
| `headers` | map | | Extra HTTP headers for the export endpoint |
| `mlflow.experiment_id` | string | | MLflow experiment ID for trace grouping |

## OTEL Receiver

Embedded OTLP/HTTP receiver for collecting live telemetry from agents.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | `false` | Enable the OTEL receiver |
| `port` | int | `4318` | Port to listen on |

## Quick Launch

Pre-configured directories for the agent launcher.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `directories` | list | `[]` | Directories shown at the top of the launcher's directory picker |

## Tasks

Google Tasks integration for task-driven agent launches.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `backend` | string | `"auto"` | Task backend: `"auto"`, `"mcp"`, or `"api"` |
| `mcp_endpoint` | string | | MCP server endpoint URL for tasks |
| `default_list` | string | | Default task list ID |
| `prompt_template` | string | see above | Template for agent prompts. Placeholders: `{title}`, `{notes}`, `{user_prompt}` |

## Auto Archive

Automatically archive idle sessions after a duration of inactivity.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `auto_archive_after` | string | `""` (disabled) | Idle duration before auto-archiving (e.g., `"1h"`, `"30m"`) |

## Badges

Project file badge rules. Badges extract values from project files and display them alongside session names.

```yaml
badges:
  - path: "package.json"
    json_path: "$.version"
    label: "v"
    color: "#22C55E"
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `path` | string | | File path relative to the project root |
| `json_path` | string | | JSONPath expression to extract the badge value |
| `label` | string | | Prefix label shown before the extracted value |
| `color` | string | | Hex color for the badge (e.g., `"#22C55E"`) |

## Runtimes

Named runtime environments for launching agents in containers or sandboxed modes.

```yaml
runtimes:
  devbox:
    type: container
    engine: podman
    image: "ghcr.io/my-org/agent-sandbox:latest"
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `type` | string | | Runtime type: `"local"`, `"container"`, or `"openshell"` |
| `engine` | string | | Container engine: `"podman"` or `"docker"` (container type only) |
| `image` | string | | Container image to use (container type only) |
| `sandbox` | bool | `false` | Enable sandbox policy (openshell type only) |

## Project-Local Config

You can place a `.aimux/config.yaml` inside any project directory. Project-local settings override the global `~/.aimux/config.yaml` for sessions running in that directory. This is useful for per-project badge rules, runtime overrides, or notification preferences.

## Kubernetes

See [Kubernetes Quickstart](/advanced/k8s-quickstart/) for full setup guide.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | `false` | Enable K8s agent discovery |
| `redis_url` | string | | Redis connection string (required when enabled) |
| `team_id` | string | | Redis key prefix for team isolation |
| `namespace` | string | `"agents"` | K8s namespace for agent deployments |
| `kubeconfig` | string | auto | Path to kubeconfig (omit for in-cluster) |
| `otel_endpoint` | string | | OTEL collector URL for remote agent traces |

## API Endpoints

The web dashboard exposes a REST API on `http://127.0.0.1:<port>`. All endpoints return JSON.

### Agents and Discovery

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/agents` | List active agents. Query params: `filter`, `sort` |
| `POST` | `/api/agents/launch` | Launch a new agent session |
| `POST` | `/api/agents/{id}/kill` | Kill an agent by session ID or PID |
| `POST` | `/api/agents/{id}/archive` | Archive an agent session |
| `GET` | `/api/agents/{id}/trace` | Get trace for an agent |
| `GET` | `/api/agents/{id}/diff` | Get file diffs for an agent session |

### Sessions

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/history` | List session history with metadata |
| `GET` | `/api/search` | Search session content |
| `DELETE` | `/api/sessions/{id}` | Delete a session |
| `POST` | `/api/sessions/{id}/annotate` | Add an annotation to a session turn |
| `GET` | `/api/sessions/{id}/annotations` | Get annotations for a session |
| `POST` | `/api/sessions/meta` | Update session metadata (tags, notes) |
| `GET` | `/api/sessions/meta` | Get session metadata |
| `GET` | `/api/sessions/diffs` | Get file diffs from a session file |
| `POST` | `/api/sessions/generate-titles` | Generate LLM titles for sessions |
| `POST` | `/api/sessions/{id}/export/jsonl` | Export session as JSONL |
| `POST` | `/api/sessions/{id}/export/otel` | Export session traces via OTEL |

### Traces

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/trace` | Fast trace lookup |
| `POST` | `/api/trace/subscribe/{sessionId}` | Subscribe to live trace updates |
| `POST` | `/api/trace/unsubscribe/{sessionId}` | Unsubscribe from trace updates |

### Costs and Health

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/costs` | Cost breakdown by project |
| `GET` | `/api/health` | Basic health check |
| `GET` | `/api/health/providers` | Provider health: enabled status and binary availability |

### Teams

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/teams` | List team configurations from `~/.claude/teams/` |

### Plugins

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/plugins` | List loaded plugins |
| `GET` | `/api/plugins/{name}/data` | Get plugin data |
| `POST` | `/api/insight` | Run a plugin insight |

### Tasks

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/tasks/lists` | List Google Tasks lists |
| `GET` | `/api/tasks` | List tasks |
| `POST` | `/api/tasks/{id}/complete` | Mark a task as complete |
| `POST` | `/api/tasks/{id}/reopen` | Reopen a completed task |

### Directories and Launch

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/directories/browse` | Browse filesystem directories |
| `GET` | `/api/directories/recent` | List recently used directories |
| `GET` | `/api/quick-launch` | Get quick launch directory list |

### Terminal

| Method | Path | Description |
|--------|------|-------------|
| `GET/POST` | `/api/terminal/{session}` | WebSocket terminal connection |
| `GET/POST` | `/api/terminal-resume/{id}` | Resume a terminal session |

### Events

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/events` | Server-Sent Events stream for live updates |
