Sandbox Architecture

This page covers implementation details. For the conceptual overview, see Concepts.

Container naming and resolution

muthr derives the container name from the project directory basename, relative to workspace_root.

~/src/homepage → muthr-homepage
~/src/muthr    → muthr-muthr

If you run muthr sandbox shell from /tmp, muthr exits with a context error because it cannot resolve a project under workspace_root.

Mount configuration

Each sandbox mounts the project workspace into /workspace inside the container. The mount uses a bind volume from the host path.

Only the project directory mounts by default. Additional paths require explicit configuration. Files created inside /workspace retain host ownership unless UID/GID syncing is active.

Provision transport

muthr copies the profile provision script and shared provisioning library into /tmp inside the container, then executes the script as the muthr user. Before execution, muthr validates all injected environment values and the model name.

The provisioning library content hashes into MUTHR_SPECS_REV. muthr compares the current hash against the last provisioned hash. A match skips the reinstall step. A mismatch triggers a full reprovision.

Baseline hardening

Every sandbox gets a baseline setup before the profile script runs:

• Required tooling installs (bash, curl, git, nodejs, npm)
• The muthr user exists with a matching UID/GID to the host user when possible
• Home directory setup inside the container (~/.bashrc, ~/.profile)

UID/GID matching prevents file ownership drift on bind mounts. If the host user lacks a matching UID in the container image, muthr falls back to UID 1000.

Network posture

Profiles declare a network policy. The default is full internet access. Profiles can request network none for restricted execution. muthr applies the policy through the Apple container network API. If the backend does not support deferred network updates, muthr emits a warning and continues with the default policy.

Audit log format

--audit-log PATH writes NDJSON to the specified file. Each line is a complete JSON object. Example structure:

{"event":"session_start","ts":"2026-01-15T10:23:41Z","project":"muthr","tty":true,"runtime":"mlxcel","inference_url":"http://host:8080"}
{"event":"command","ts":"2026-01-15T10:23:42Z","argv":["hermes","agent","--run"]}
{"event":"session_exit","ts":"2026-01-15T10:31:07Z","exit_code":0,"duration":446}

---

See also: Concepts · Security · Troubleshooting