Skip to content

Configuration

aimux reads its configuration from these files:

FileWhat it holds
~/.aimux/config.yamlThe settings on this page: providers, runtimes, sessions, remote access and the rest
~/.config/aimux/clients.yamlEach local client’s scope: its socket, profiles and limits (see Client scopes)
~/.config/aimux/profiles/Your own profiles, one file each (see Profiles)
~/.config/aimux/tool-sources.yamlThe tool sources and reviewed tool sets (see Tool sources)
~/.config/aimux/deciders.yamlThe decider Auto uses to pick a mode (see Auto)

aimux also writes state you approve but do not edit by hand: ~/.aimux/tools/pins.json, the pinned tools (see Pinned tools), written by aimux tools approve.

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

providers:
claude:
enabled: true
codex:
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: "haiku"
naming_daily_limit: 20
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: ""

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

FieldTypeDefaultDescription
enabledbooltrueWhether to discover agents from this provider
binarystringauto-detectOverride the binary path for this provider

aimux has six orthogonal configuration axes:

ValueStatusDescription
localSupportedDefault. Agent runs as a process on your machine
containerSupportedAgent runs inside a Podman/Docker container
ValueStatusDescription
/bin/zshSupportedDefault if $SHELL is zsh
/bin/bashSupported
/bin/fishSupported
ValueStatusDescription
localSupportedDefault. Tools execute on the same machine as the agent
hybridPlannedAgent runs locally, tool calls forwarded to remote host (K8s pod or SSH)

Session Manager (HOW terminal sessions are managed)

Section titled “Session Manager (HOW terminal sessions are managed)”
ValueStatusDescription
tmuxSupportedDefault. Sessions persist after detach
directSupportedAgent runs in foreground, dies when terminal closes

Terminal Emulator (auto-detected, not configurable)

Section titled “Terminal Emulator (auto-detected, not configurable)”
EmulatorDetectionUsed for
iTerm2$TERM_PROGRAM == "iTerm.app"Jump-to-session via split pane
OthersFallbacktmux pane
FieldTypeDefaultDescription
refresh_intervalstring"2s"How often to scan for agents
runtimestring"local"WHERE: "local" or "container"
shellstring$SHELLWHICH shell for agent sessions. Falls back to $SHELL, then /bin/sh
executionstring"local"WHERE tools run: "local" or "hybrid"
session_managerstring"tmux"HOW terminal sessions are managed
FieldTypeDefaultDescription
skip_permissionsboolfalsePass --dangerously-skip-permissions with aimux resume. The web dashboard ignores it and asks for Skip permissions on each resume
FieldTypeDefaultDescription
auto_titleboolfalseName sessions a phone client shows that have no name or description, once, with a small model call. Never touches text you wrote
title_modelstring"haiku"Model for names: "haiku" (claude-haiku-5-5), "sonnet", "opus"; an unknown name falls back to haiku
naming_daily_limitint20Sessions named automatically per local day; Update summary is not limited
api_keystringenv varAPI key for naming (overrides ANTHROPIC_API_KEY); without a key, claude -p in safe mode with your Claude Code login is used

At most 500 characters per session go to Anthropic for an automatic name (1,200 for Update summary). See Finding sessions for the sources, privacy and cost details.

macOS notification settings. All default to sensible values.

FieldTypeDefaultDescription
enabledbooltrueMaster switch for all notifications
on_waitingbooltrueNotify when agent needs permission
on_errorbooltrueNotify when agent crashes
on_idleboolfalseNotify when agent finishes a turn
on_donebooltrueNotify when agent finishes
soundboolfalsePlay macOS notification sound
bellbooltrueTerminal bell on attention events
desktopbooltruemacOS Notification Center alerts

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

FieldTypeDefaultDescription
endpointstringOTLP/HTTP endpoint (e.g., "localhost:5001")
insecurebooltrueUse HTTP instead of HTTPS
headersmapExtra HTTP headers for the export endpoint
mlflow.experiment_idstringMLflow experiment ID for trace grouping

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

FieldTypeDefaultDescription
enabledboolfalseEnable the OTEL receiver
portint4318Port to listen on

Pre-configured directories for the agent launcher.

FieldTypeDefaultDescription
directorieslist[]Directories shown at the top of the launcher’s directory picker

Google Tasks integration for task-driven agent launches.

FieldTypeDefaultDescription
backendstring"auto"Task backend: "auto", "mcp", or "api"
mcp_endpointstringMCP server endpoint URL for tasks
default_liststringDefault task list ID
prompt_templatestringsee aboveTemplate for agent prompts. Placeholders: {title}, {notes}, {user_prompt}

Automatically archive idle sessions after a duration of inactivity.

FieldTypeDefaultDescription
auto_archive_afterstring"" (disabled)Idle duration before auto-archiving (e.g., "1h", "30m")

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"
FieldTypeDefaultDescription
pathstringFile path relative to the project root
json_pathstringJSONPath expression to extract the badge value
labelstringPrefix label shown before the extracted value
colorstringHex color for the badge (e.g., "#22C55E")

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"
FieldTypeDefaultDescription
typestringRuntime type: "local", "container", or "openshell"
enginestringContainer engine: "podman" or "docker" (container type only)
imagestringContainer image to use (container type only)
sandboxboolfalseEnable sandbox policy (openshell type only)

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.

See Kubernetes Quickstart for full setup guide.

FieldTypeDefaultDescription
enabledboolfalseEnable K8s agent discovery
redis_urlstringRedis connection string (required when enabled)
team_idstringRedis key prefix for team isolation
namespacestring"agents"K8s namespace for agent deployments
kubeconfigstringautoPath to kubeconfig (omit for in-cluster)
otel_endpointstringOTEL collector URL for remote agent traces

Settings for aimux remote serve, under the remote_access key (separate from remote, which configures remote agent backends). See Remote Access for setup and the API. Which profiles each local client may use, its socket and its limits are not set here but in ~/.config/aimux/clients.yaml (client scopes); profiles are files in $AIMUX_PROFILE_DIR or ~/.config/aimux/profiles (Profiles).

remote_access:
allowed_logins:
- you@example.com
FieldTypeDefaultDescription
portint7382Port on 127.0.0.1
allowed_loginslistemptyTailscale logins admitted; empty admits nobody
adapterstringnpx -y @agentclientprotocol/claude-agent-acpACP adapter command for Claude sessions
max_runsint2Sessions running at once; each is a full agent process
approval_timeoutduration10mUnanswered permission requests are denied after this
device_loginbooltrueOnly devices paired with aimux remote pair may use the API, logged in with Face ID or Touch ID (see Device login); false admits any device of an allowed login, and remote serve then starts only with --unsafe-no-device-login or --local-only
step_up_legacyboolfalseAlso require a fresh login (under 60 seconds old, from a Secure Enclave iPhone) for new sessions started without a profile, which run on the Mac like the coding profile. Sessions under a runs: host profile always need it
terminal_input.enabledboolfalseType phone messages into Claude Code sessions open in iTerm2 (see Typing into terminal sessions)
terminal_input.allow_while_in_useboolfalseType even into the session you are using on the Mac; for testing at the Mac only
terminal_input.allow_slash_commandsboolfalseLet a phone message start with / (a slash command); a leading ! is always refused
terminal_input.keep_draftsboolfalseKeep a draft you left in the input box: a phone message is then refused (409 draft_in_box) instead of replacing it. Claude Code’s grey suggestion is always typed over
hostnameslistdetected from tailscale statusHost names the API accepts (this machine’s tailnet names); others are refused
push.ntfy.topicstringoffntfy topic that gets an alert for each permission request; on when set
push.ntfy.serverstringhttps://ntfy.shntfy server (2.16 or later also takes the alert back once the request is settled)
push.ntfy.token_envstringnoneEnvironment variable holding an ntfy access token; remote serve refuses to start if it is not set
push.ntfy.click_urlstringhttps://<tailnet name>:8443/app/Web client a tapped alert opens
push.apns.key_filepathoffApple token signing key (.p8, P-256) for the aimux iPhone app; ~/ is expanded
push.apns.key_id, push.apns.team_id, push.apns.topicstringnoneThe key’s id, your Apple team id and the app’s bundle id; all four apns fields or none

See Approval notifications for setting up the phone.

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

MethodPathDescription
GET/api/agentsList active agents. Query params: filter, sort
POST/api/agents/launchLaunch a new agent session
POST/api/agents/{id}/killKill an agent by session ID or PID
POST/api/agents/{id}/focusBring a running agent’s iTerm2 pane to the front (session ID, unique prefix or PID). 404 not running, 409 ambiguous prefix, 422 no pane, 502 iTerm2 focus failed (422 and 502 bodies carry hint with the tmux attach command for agents in tmux)
POST/api/agents/{id}/archiveArchive an agent session
GET/api/agents/{id}/traceGet trace for an agent
GET/api/agents/{id}/diffGet file diffs for an agent session
MethodPathDescription
GET/api/historyList session history with metadata. Every session the dashboard can reveal is returned, each with shownTitle and hidden (the switches that must all be on to show it: subagents, automated, analyzers, search); sessions no switch can reveal are left out
GET/api/searchSearch session content (q); automated sessions are left out unless automated=1 (the dashboard’s Automated switch)
DELETE/api/sessions/{id}Delete a session
POST/api/sessions/{id}/annotateAdd an annotation to a session turn
GET/api/sessions/{id}/annotationsGet annotations for a session
POST/api/sessions/metaUpdate session metadata (tags, notes)
GET/api/sessions/metaGet session metadata
GET/api/sessions/diffsGet file diffs from a session file
POST/api/sessions/generate-titlesGenerate LLM titles for sessions
POST/api/sessions/{id}/export/jsonlExport session as JSONL
POST/api/sessions/{id}/export/otelExport session traces via OTEL
MethodPathDescription
GET/api/traceFast trace lookup
POST/api/trace/subscribe/{sessionId}Subscribe to live trace updates
POST/api/trace/unsubscribe/{sessionId}Unsubscribe from trace updates
MethodPathDescription
GET/api/costsCost breakdown by project
GET/api/healthBasic health check
GET/api/health/providersProvider health: enabled status and binary availability
MethodPathDescription
GET/api/teamsList team configurations from ~/.claude/teams/
MethodPathDescription
GET/api/pluginsList loaded plugins
GET/api/plugins/{name}/dataGet plugin data
POST/api/insightRun a plugin insight
MethodPathDescription
GET/api/tasks/listsList Google Tasks lists
GET/api/tasksList tasks
POST/api/tasks/{id}/completeMark a task as complete
POST/api/tasks/{id}/reopenReopen a completed task
MethodPathDescription
GET/api/directories/browseBrowse filesystem directories
GET/api/directories/recentList recently used directories
GET/api/quick-launchGet quick launch directory list
MethodPathDescription
GET/POST/api/terminal/{session}WebSocket terminal connection
GET/POST/api/terminal-resume/{id}Resume a terminal session
MethodPathDescription
GET/api/eventsServer-Sent Events stream for live updates