## Description Native persistent-service manifests now explicitly select CPU for the memory embedder and ONNX for Kompress by default. This avoids selecting Metal-specific model backends during supervised startup, while preserving explicit backend overrides. Closes #3604 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Add `HEADROOM_EMBEDDER_RUNTIME=cpu` and `HEADROOM_KOMPRESS_BACKEND=onnx` to native `persistent-service` manifests only. - Keep explicit `extra_env` values last so users can intentionally opt into another backend. - Add planner regression coverage for service defaults, overrides, and non-service presets. - Document the independent backend settings and the explicit MPS opt-in boundary. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text python -m pytest -q tests/test_install/test_planner.py tests/test_install/test_supervisors.py tests/test_install/test_runtime.py tests/test_cli/test_install_cli.py 133 passed ruff check headroom/install/planner.py tests/test_install/test_planner.py All checks passed ruff format --check headroom/install/planner.py tests/test_install/test_planner.py All checks passed git diff --check passed ``` ## Real Behavior Proof - Environment: Ubuntu/Linux development host; native macOS launchd and Apple Silicon Metal were not available. - Exact command / steps: Ran the focused planner, supervisor, runtime, and install CLI test suite plus Ruff and diff checks listed above. - Observed result: The planner emits CPU/ONNX defaults for native persistent services, preserves explicit backend overrides, and leaves persistent-task and Docker manifests unchanged; the focused suite passed. - Not tested: Real Apple Silicon macOS 26 behavior, launchd restart recovery, and ambient exported backend variables. The current base source also does not prove that a clean persistent-service install injected MPS; this PR is defensive safe-default hardening rather than a claim of reproducing the reported crash. ## Runtime Rollout Safety - Rollout-managed feature(s): None. - Minimum rollout channel: Standard release. - Stable/default behavior changed: Native `persistent-service` manifests use CPU/ONNX model backends by default. - Kill switch / disable path: Explicit `--env HEADROOM_EMBEDDER_RUNTIME=pytorch_mps` and/or `--env HEADROOM_KOMPRESS_BACKEND=pytorch_mps`, subject to platform and dependency support. - Unsafe override required: No. - Qualification impact: Persistent services no longer select Metal-specific model backends by default. - Rollback path: Revert this PR. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) N/A — this is a manifest, test, and documentation change. ## Additional Notes `mypy` was not locally runnable because the maturin editable build failed: the installed Rust toolchain lacked an applicable cargo component. The PR does not claim CI success or real macOS runtime validation.
6.6 KiB
Persistent Installs
Headroom can now be installed as a durable local runtime instead of only being started ad hoc with headroom proxy or headroom wrap ....
Use the Python-native headroom install CLI when you want supported tools to keep talking to an always-on proxy at http://127.0.0.1:8787 and have wrap reuse or recover that deployment instead of starting a second ephemeral proxy.
Runtime matrix
| Mode | What stays running | Primary entrypoint |
|---|---|---|
| Persistent Service | Native background service | headroom install apply --preset persistent-service |
| Persistent Task | Scheduled watchdog + on-demand runner | headroom install apply --preset persistent-task |
| Persistent Docker | Restartable Docker container | headroom install apply --preset persistent-docker |
| On-Demand CLI (Python) | Nothing after command exits | headroom proxy |
| On-Demand CLI (Docker) | Nothing after container exits | Docker-native wrapper / compose CLI |
| Wrapped (Python) | Proxy lasts for wrapped session | headroom wrap ... |
| Wrapped (Docker) | Containerized proxy + host tool session | Docker-native wrapper |
Quick examples
Persistent service on the local machine
headroom install apply --preset persistent-service --providers auto
headroom install status
This installs a background service on the current machine, applies persistent tool wiring, and keeps the proxy healthy on port 8787.
Native persistent-service manifests explicitly default the memory embedder to
cpu and Kompress to onnx. This avoids selecting the Apple Silicon Metal
backends during supervised startup, where a native MPS abort cannot be handled
by Python. These are safe defaults only: explicit --env HEADROOM_EMBEDDER_RUNTIME=pytorch_mps or
--env HEADROOM_KOMPRESS_BACKEND=pytorch_mps still opts into MPS and requires
the matching platform and optional dependencies. The two settings are
independent; the Kompress setting does not control memory embedding.
Persistent watchdog task
headroom install apply --preset persistent-task --providers manual --target claude --target codex
This installs a scheduled recovery path instead of a traditional always-running service.
Persistent Docker
headroom install apply --preset persistent-docker --scope user --providers auto
This uses Docker's restart policy instead of an OS supervisor.
If you are using the Docker-native host wrapper instead of a Python install, you can now use headroom install apply|status|start|stop|restart|remove for the persistent-docker preset directly from the installed wrapper. Service/task installs and provider/user/system mutation flows still belong to the Python-native CLI.
Command surface
headroom install apply
headroom install status
headroom install start
headroom install stop
headroom install restart
headroom install remove
apply creates or updates a named deployment profile, stores its manifest under ~/.headroom/deploy/<profile>/manifest.json, applies reversible configuration changes, and starts the selected runtime.
Presets and runtime kinds
Presets
persistent-service-> native service supervisorpersistent-task-> scheduled watchdog / recovery supervisorpersistent-docker-> Docker restart policy with no extra OS supervisor
Runtime kinds
--runtime pythonrunsheadroom proxydirectly--runtime dockerruns Headroom inside Docker while keeping the deployment managed locally
For persistent-docker, the runtime is always Docker.
Configuration scopes
| Scope | What changes |
|---|---|
provider |
Tool-specific config surfaces where Headroom can make a precise reversible edit |
user |
User-level shell or environment surfaces |
system |
Machine-wide shell or environment surfaces |
Provider scope today
Provider scope is intentionally conservative. The current direct adapters are:
- Claude Code ->
~/.claude/settings.jsonenv - Codex -> managed block in
~/.codex/config.toml - OpenClaw -> existing
wrap openclaw/unwrap openclawflow
For Copilot, Aider, Cursor, and broader env-driven setups, prefer --scope user or --scope system.
Provider selection
| Option | Meaning |
|---|---|
--providers auto |
Detect supported tools on the host and configure the best available defaults |
--providers all |
Configure all known targets |
--providers manual --target ... |
Configure only the named tools |
Examples:
headroom install apply --providers auto
headroom install apply --providers all --scope user
headroom install apply --providers manual --target claude --target copilot
Health and wrap behavior
Persistent deployments publish the same readyz and health endpoints as ad hoc proxy runs.
/health now also exposes deployment metadata when the proxy was launched through the install subsystem:
{
"deployment": {
"profile": "default",
"preset": "persistent-service",
"runtime": "python",
"supervisor": "service",
"scope": "user"
}
}
The Python-native headroom wrap ... flow checks for a matching persistent deployment on the requested port before it starts a new ephemeral proxy. If an installed deployment exists but is stopped or unhealthy, it attempts to recover it first.
The Docker-native host wrapper does not yet reuse or recover persistent profiles automatically; it still starts a fresh proxy container unless you opt into --no-proxy.
Docker-native relationship
The Docker-native host wrapper and the Python install CLI solve different layers of the runtime story:
- Docker-Native Install -> containerized on-demand CLI, wrapped host-tool flows, and Docker-native
persistent-dockerlifecycle commands headroom install ...-> full persistent service, task, and Docker lifecycle management, including provider/user/system mutation
For a no-Python persistent Docker workflow, use the compose-managed proxy path from docker/docker-compose.native.yml:
export HEADROOM_HOST_HOME="$HOME"
export HEADROOM_WORKSPACE="$PWD"
docker compose -f docker/docker-compose.native.yml up -d proxy
That keeps localhost:8787 stable and restarts the proxy automatically.
Note:
HEADROOM_WORKSPACE(the host-side bind-mount source used by the compose file) is not the same variable asHEADROOM_WORKSPACE_DIR(the canonical Headroom state root inside the container). Both are retained; the compose file sets the latter automatically. See Filesystem Contract for the full bucket model.