Configuration

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

Full Example

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.

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.

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 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