Files
headroom/wiki/persistent-installs.md
lorenzozane 7287589d23 fix(install): use safe model backends for persistent services (#3646)
## 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.
2026-10-01 15:57:06 -05:00

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 supervisor
  • persistent-task -> scheduled watchdog / recovery supervisor
  • persistent-docker -> Docker restart policy with no extra OS supervisor

Runtime kinds

  • --runtime python runs headroom proxy directly
  • --runtime docker runs 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.json env
  • Codex -> managed block in ~/.codex/config.toml
  • OpenClaw -> existing wrap openclaw / unwrap openclaw flow

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-docker lifecycle 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 as HEADROOM_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.