Skip to content

Troubleshooting

aimux doctor checks what Wingman’s work lane and the sandboxed profiles depend on, and writes nothing. Each check has a stable id, a status (ok, warn or fail), what it found and, for a problem, one fix. In the fixes below, <registry> is ~/.config/aimux/tool-sources.yaml and <wrapper binary> is the aimux that ~/.aimux/wingman/host.sh execs.

Terminal window
aimux doctor # one line per check, a fix line under each problem
aimux doctor --json # {"schema_version", "healthy", "problems", "checks": [{"id", "status", "detail", "fix"}]}

Each fix is also printed as a Next: <fix> line on stderr, as the other commands hint, in text and JSON mode; a healthy run prints none, and a fix that is only “nothing to do” gets no Next: line. Exit status: 1 when any check is fail; warnings alone exit 0 (text output ends with N warnings, no failure (exit 0)). In JSON, healthy is false only when a check fails, and problems counts every warn and fail. Doctor writes no file, not even a temporary one: an unmigrated readonly.json is converted in memory. Its probes are read-only: it lists each tool source’s live tools (as aimux tools status does; a cli source only when the tool runner aimux-tools is already Ready, through sandbox exec <binary> --version) and runs podman image exists, openshell -g local status, provider list and sandbox list, ps and lsof. It never starts the gateway, migrates readonly.json or approves a tool.

To fix what is missing in one go, run aimux setup (see below).

Check idStatusProblemFix
tools.legacywarntool-sources.yaml is absent and ~/.aimux/wingman/readonly.json is not migrated yet; it is read in its place.aimux setup --yes (migrates it once; the old file is kept as readonly.json.migrated)
tools.pinsfail~/.aimux/tools/pins.json does not read. Until it is fixed no tool is granted or served.move ~/.aimux/tools/pins.json aside, then aimux tools diff and aimux tools approve <set> for each set you review
tools.registryfailThe registry does not load at all (strict YAML: an unknown key, a second document, a wrong version). The other tools checks are skipped.fix <registry> (strict YAML; aimux tools status shows the same error)
tools.registry.set.<set>warnOne set is malformed or points at an unknown or broken source, so it is skipped. The detail names the profiles that request it.fix set <set> in <registry>, then aimux tools status
tools.registry.source.<source>warnOne source is malformed, so it and its sets are skipped.fix source <source> in <registry>, then aimux tools status
tools.reviewfailThe live tools could not be judged at all (rare).aimux tools status
tools.review.<set>/<tool>warnThe tool is unpinned (listed live, never approved), changed (its live definition differs from the approved one, or it is gone) or source_changed (approved from another URL or folder than the registry names now). It is not served until approved.aimux tools diff <set>/<tool>, then aimux tools approve <set>/<tool>
tools.no_set.<source>/<tool>warnThe tool is pinned, but no set lists it, so it is never served. When the source itself is gone (aimux tools remove), the pin is kept but unused.add <tool> to a set of source <source> in <registry> if it should be served (else nothing to do). Source gone: nothing to do; to serve it again, add source <source> back with aimux tools add (same folder or URL)
tools.backend.<source>warnThe source could not be listed; its tools are hidden.MCP source: start the <source> MCP server at <url>, then aimux tools status. Notes source: create the notes folder <root> or fix source <source> in <registry>, then run aimux tools status
tools.omitted.<profile>.<set>warnA profile requests a set its compile leaves out (not in the registry, or none of its tools pinned). The profile runs without it. A builtin’s opt-in set (gh:readonly in work-readonly) that is not in the registry at all is not reported.No pinned tools: aimux tools diff <set>, then aimux tools approve <set>. Not in the registry: add set <set> to <registry>, or remove it from the profile

A pin detects schema changes; it does not prove a tool is read-only.

Check idStatusProblemFix
router.configfail~/.config/aimux/deciders.yaml does not load; Auto asks every time until it is fixed.fix ~/.config/aimux/deciders.yaml, then aimux router status
router.keywarnNo OpenRouter key, or the key is only in OPENROUTER_API_KEY in your shell. The serve Chrome starts for Wingman does not inherit your shell’s environment. The key itself is never read or printed.macOS: security add-generic-password -U -a "$USER" -s aimux-openrouter -w (the service named in deciders.yaml). Linux: put the key in a file with mode 0600 at ~/.config/aimux/keys/openrouter
Check idStatusProblemFix
port.7390fail127.0.0.1:7390, where the tool gateway worker serves sandboxes, is held by another program (the detail names its pid and command). Held by the worker (aimux mcp proxy gateway serve) is ok.kill <pid> (or stop that program), then: launchctl kickstart -k gui/$(id -u)/com.aimux.tool-gateway
port.7390warnHeld by an aimux remote serve from before the gateway worker, which still runs its own gateway.restart aimux remote serve from the current aimux, then: aimux mcp proxy gateway install
gateway.workerfailThe tool gateway worker does not answer on ~/.aimux/gateway.sock, so Workspace turns fail. Setup’s summary shows the same as its worker line.aimux mcp proxy gateway install
port.7390warnlsof could not check the port.lsof -nP -iTCP:7390 -sTCP:LISTEN (install lsof if it is missing)
wingman.servewarnA running aimux remote serve --local-only runs another aimux than <wrapper binary>, or started more than 2 seconds before that file was last replaced, so it runs the older build. Doctor matches serves whose command line starts with that path (a path with spaces works; a grep or sh -c that mentions a serve is ignored) and compares the start time with the file’s modification time. Without host.sh the check is ok (Wingman not installed).kill <pid>; the next Wingman panel starts serve from <wrapper binary>
wingman.servewarnThe binary host.sh execs is gone.reinstall aimux at <wrapper binary> or run aimux setup --extension-id <id> from the aimux you use, then kill <pid>
wingman.servewarnhost.sh has no exec '<path>' browser host line (not written by aimux).aimux setup --extension-id <id> (rewrites the wrapper)
wingman.servewarnps failed.ps -axww -o pid=,lstart=,command= | grep 'remote serve --local-only'
Check idStatusProblemFix
gatewayfailThe OpenShell gateway local is unreachable. The provider and sandbox policy checks are skipped.start the OpenShell gateway: openshell-gateway --config ~/.config/openshell/gateway-podman.toml (aimux setup --yes, aimux sandbox setup and remote serve start it too)
gatewaywarnopenshell -g local status answers but sandbox list fails, most often because the local gateway is not registered.openshell gateway list; if local is missing, register it: openshell gateway add http://<bind_address of ~/.config/openshell/gateway-podman.toml> --name local, then aimux doctor
sandbox.imagefaillocalhost/wingman-sandbox:2.1.319 is missing.aimux setup --yes (or aimux sandbox setup)
sandbox.imagewarnPodman does not answer.podman machine start, then aimux doctor
sandbox.providerfailThe provider wingman-claude is missing (it needs the Keychain item wingman-claude-oauth).aimux setup --yes (or aimux sandbox setup)
sandbox.providerwarnprovider list failed.openshell -g local provider list, then aimux doctor
sandbox.runner_imagefailThe tool runner image localhost/aimux-tools:2.103.3 is missing (cli and http-openapi tools run in it).aimux setup --yes (or aimux sandbox setup)
sandbox.runner_imagewarnPodman does not answer.podman machine start, then aimux doctor
sandbox.runner_providerfailThe runner provider aimux-github is missing and an approved source (the gh pack) needs it. Missing with nothing needing it is ok.aimux setup --yes (or aimux sandbox setup; it creates it when the GitHub token is in the secret store)
sandbox.runner_providerwarnprovider list failed.openshell -g local provider list, then aimux doctor
sandbox.runner_sourceswarnSources left out of the tool runner, each with its reason (a missing provider, a spec that cannot be read, a refused base URL).aimux sandbox status, then fix what each reason names
sandbox.policy.<profile>warnThe profile’s sandbox runs another policy than the profile compiles to now (stale). Serve applies the new one before the next turn.work-readonly: applies on the next Workspace question, plus ; or run aimux sandbox verify while port 7390 is free or held by the tool gateway worker (verify uses it). research: applies on the next Web question. Others: applies on the next turn in <profile>
sandbox.policy.<profile>failThe profile does not compile.aimux tools status, then fix what the error names

aimux sandbox status also lists the tool runner, aimux-tools, as (tool runner) after the profiles (runner in --json), with the same states and its recorded and compiled digests. error means the runner does not compile at all (for example a pins file that does not parse). An http-openapi source whose spec cannot be read, that names a credential, or whose base URL the compiler refuses (an IP literal, localhost, an .internal or .local name, the model host, or api.github.com, which the gh pack’s provider is bound to) is left out of the runner instead: the runner still compiles without it, and the reason shows under aimux tools status and in aimux sandbox status (Left out of the tool runner:, runner_dropped in --json). A second Provider: line shows aimux-github; missing there needs action only when an approved gh source is left out for it (then Next: aimux sandbox setup). Its GitHub provider aimux-github is created by aimux sandbox setup only when the platform’s secret store (Keychain on macOS, Secret Service on Linux) has the item aimux-github with a fine-grained, read-only GitHub token; without it setup prints the line to store it (security add-generic-password or secret-tool store), carries on, and the gh tools have no credential.

A profile that does not resolve (it widens its parent or extends a missing profile) gets no sandbox.policy.<profile> check, does not appear in aimux sandbox status, and is left out of the profiles doctor names next to a tool set (requested by ...). Run aimux profile check <name> to see why. Doctor does not check a profile’s roles; aimux profile check does. A sandbox profile whose name makes an invalid sandbox name (uppercase letters, underscores, a trailing or doubled dash, or over 19 characters with the aimux- prefix) shows a compile error in aimux sandbox status and, when the OpenShell gateway is reachable (doctor skips policy checks otherwise), a failed sandbox.policy.<profile> check in doctor; aimux profile check <name> names the rule.

On Linux, aimux sandbox setup still fails at the wingman-claude step when that provider is missing: it reads the Claude token with macOS security, not the Secret Service. Create wingman-claude with openshell provider create yourself, then run setup again for the images and aimux-github.

aimux setup checks the same concerns and runs only the steps that are missing:

  1. The tool registry: migrates readonly.json once, or writes the defaults.
  2. ~/.config/aimux/clients.yaml, when it is absent.
  3. The sandbox: starts the OpenShell gateway, builds the image and creates the provider, each only when missing (as aimux sandbox setup). It runs only when one of those is missing; to build the tool runner image localhost/aimux-tools:2.103.3 and create aimux-github, run aimux sandbox setup.
  4. The Chrome native host (as aimux browser install), with --extension-id <id>, or when an id is already pinned but no host manifest or wrapper is there.

On a terminal it asks before each step (Enter is yes); --yes runs them without asking. With no terminal, or with --json, and no --yes, it runs none and lists them as pending with Next: aimux setup --yes.

Then, only on a terminal and never with --json, it offers each tool that needs review: Show diff and approve now? [y/N] shows the diff, and a second yes to Approve <set>/<tool>? [y/N] pins it. Anything else, and end of input, is no. --yes never approves tools.

It ends with six lines, one per concern (sandbox, tools, router, browser, gateway, worker for the tool gateway worker), each ✓ (fine), ! (works, but needs attention) or ✗ (broken), and a Next: line on stderr for each problem. A second run with nothing missing changes nothing. Setup exits 1 only when a step failed.

aimux setup --json prints {"schema_version", "steps": [{"name", "action", "output"}], "approved", "summary": [{"concern", "status", "detail", "next"}]}; a step’s action is ran, pending, declined or failed.

Terminal window
aimux browser uninstall # the manifests in Chrome and Chrome Beta, and host.sh
aimux browser uninstall --all # also the pinned extension id

The ACP adapter under ~/.aimux/wingman/adapter is kept. Running it again when nothing is installed prints Nothing to remove.