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.
prompt_template: "Work on the following task: {title}\n\nDetails: {notes}\n\nAdditional instructions: {user_prompt}\n\nWhen done, summarize what you did."
Name sessions a phone client shows that have no name or description, once, with a small model call. Never touches text you wrote
title_model
string
"haiku"
Model for names: "haiku" (claude-haiku-5-5), "sonnet", "opus"; an unknown name falls back to haiku
naming_daily_limit
int
20
Sessions named automatically per local day; Update summary is not limited
api_key
string
env var
API 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.
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.
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
Field
Type
Default
Description
port
int
7382
Port on 127.0.0.1
allowed_logins
list
empty
Tailscale logins admitted; empty admits nobody
adapter
string
npx -y @agentclientprotocol/claude-agent-acp
ACP adapter command for Claude sessions
max_runs
int
2
Sessions running at once; each is a full agent process
approval_timeout
duration
10m
Unanswered permission requests are denied after this
device_login
bool
true
Only 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_legacy
bool
false
Also 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
Type even into the session you are using on the Mac; for testing at the Mac only
terminal_input.allow_slash_commands
bool
false
Let a phone message start with / (a slash command); a leading ! is always refused
terminal_input.keep_drafts
bool
false
Keep 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
hostnames
list
detected from tailscale status
Host names the API accepts (this machine’s tailnet names); others are refused
push.ntfy.topic
string
off
ntfy topic that gets an alert for each permission request; on when set
push.ntfy.server
string
https://ntfy.sh
ntfy server (2.16 or later also takes the alert back once the request is settled)
push.ntfy.token_env
string
none
Environment variable holding an ntfy access token; remote serve refuses to start if it is not set
push.ntfy.click_url
string
https://<tailnet name>:8443/app/
Web client a tapped alert opens
push.apns.key_file
path
off
Apple token signing key (.p8, P-256) for the aimux iPhone app; ~/ is expanded
Bring 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)
List 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/search
Search session content (q); automated sessions are left out unless automated=1 (the dashboard’s Automated switch)