Troubleshooting

sandbox shell says command not found for profile tools

Re-apply profile assets and reprovision:

muthr init --force
muthr sandbox shell --profile hermes-agent --no-tty --command "command -v hermes || true"

Sandbox cannot reach inference API

Validate host bind and endpoints:

muthr config show
muthr engine status

For sandbox access, ensure bind host is 0.0.0.0.

Probe from sandbox:

muthr sandbox shell --profile opencode --no-tty --command "python3 - <<'PY'
import os, urllib.request
u=os.environ['MUTHR_INFERENCE_URL'].rstrip('/') + '/models'
print('url', u)
print('status', urllib.request.urlopen(u, timeout=8).status)
PY"

Running from wrong directory/context

muthr sandbox commands require project context under workspace_root.

If you are outside that root, muthr exits with usage-context errors.

Sandbox cleanup

List + stop all managed sandboxes:

muthr sandbox ls
muthr sandbox stop --all

Delete uses current project context:

cd ~/src/project-a && muthr sandbox delete --yes
cd ~/src/project-b && muthr sandbox delete --yes

Service plane issues

muthr services status --output json
muthr services restart

Engine/process drift

muthr engine stop --all
muthr engine start --runtime mlxcel

Inference server reachable from sandbox but not from host

The engine may bind to 127.0.0.1 (host-only) while sandboxes need 0.0.0.0. Check:

muthr config show | grep bind_host
lsof -i :8080 -P -n

If bind_host shows 127.0.0.1, sandboxes cannot reach the API. Set default_engine_bind_host = "0.0.0.0" in muthr.toml and restart the engine.

Profile provisioning hangs

Provisioning hangs usually mean the container cannot reach package mirrors or the host gateway is misconfigured.

muthr sandbox shell --profile hermes-agent --no-tty --command "ping -c 3 github.com"
muthr config show | grep gateway

If DNS fails, the container network is broken. Check MUTHR_CONTAINER_HOST_GATEWAY and try muthr init --force to regenerate network configs.

If apt/curl timeouts appear, the host gateway IP may be wrong for your network. Set container_host_gateway explicitly in muthr.toml.

UID/GID drift on mounted files

Files created inside a sandbox appear on the host with the container UID instead of your host UID. Check:

ls -ln ~/src/myproject
id

If the file owner shows a numeric UID that does not match your id -u, muthr could not sync the user. Recreate the sandbox:

muthr sandbox stop --name muthr-myproject
muthr sandbox shell --profile opencode

muthr rebuilds the muthr user with the correct host UID on the next creation.

Pre-flight diagnostics

muthr doctor

This checks container CLI availability, arm64 buildkit behavior, config resolution, and managed runtime state.

---

See also: Installation · Configuration · Security