mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:07:29 +08:00
## Description In `examples/deployment/macos-launchagent/install.sh` (lines 96-113 on `1da8930a`), when the plist already exists the script runs `launchctl bootout` on the running service first and only then asks `Reinstall? [y/N]`. Answering `N` prints `Installation cancelled.` and exits 0, but the service is already stopped, so a cancelled install leaves the proxy down until the next login or a manual `launchctl bootstrap`. This PR moves the stop block below the prompt, unchanged, so `bootout` runs only after the user confirmed, or in `--unattended` mode (which never prompts). Nothing else changes. Part of #4730 ## 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 - `examples/deployment/macos-launchagent/install.sh`: the `launchctl print` / `launchctl bootout` block moves from before the `Reinstall?` prompt to after it, with a one-line comment. 6 lines moved, 1 comment added. ## Testing - [x] Unit tests pass (`pytest`) (the new test file only; I did not run the full suite) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed This is a shell example script, so the Python lint and type checks do not apply to it. The new test file is checked with ruff (below). The project's bug-fix policy asks for a test that fails before and passes after, so a committed test runs the real script against stubs (below), and the earlier manual driver is kept under it. ### Test Output #### Committed regression test `tests/test_macos_launchagent_install_cancel.py` runs the real `install.sh` under `bash` with stub `uname`, `launchctl`, `headroom` and `lsof` on `PATH` and a fake `HOME`. It is skipped when `bash` is not on `PATH`. Environment: Ubuntu on WSL2, bash, Python venv `/var/tmp/cb-fix-8mh5/repo/.venv`, pytest `-p no:cacheprovider`, test file run from a scratch copy (no `headroom` import, no repo conftest). Same test file, `install.sh` taken from `origin/main` (`1da8930a`): ```text FAILED test_declining_reinstall_keeps_the_service_running 1 failed, 1 passed in 0.14s (test_confirming_reinstall_stops_the_service passes: bootout is still called after y) ``` Same test file, `install.sh` from this branch: ```text 2 passed in 0.06s ``` `ruff format --check` and `ruff check` on the new file: clean. #### Earlier manual driver Driver: copies `install.sh` and the plist template into a scratch directory, puts stubs first on `PATH` (`uname` prints `Darwin`; `headroom` exits 0; `lsof` exits 1; `launchctl` appends each call to a log and exits 0, so `launchctl print` reports a running service), points `HOME` at a fake home that already contains `Library/LaunchAgents/com.headroom.proxy.plist`, and feeds stdin. Git Bash on Windows 11. Paths shortened to `<run>`; output filtered to the lines that matter. `origin/main` (`1da8930a`), `echo N | bash install.sh`: ```text ⚠ LaunchAgent already installed at: <run>/fakehome/Library/LaunchAgents/com.headroom.proxy.plist ==> Stopping existing service... Installation cancelled. rc=0 --- launchctl call log: launchctl print gui/197609/com.headroom.proxy launchctl bootout gui/197609/com.headroom.proxy ``` This branch, `echo N | bash install.sh`: ```text ⚠ LaunchAgent already installed at: <run>/fakehome/Library/LaunchAgents/com.headroom.proxy.plist Installation cancelled. rc=0 --- launchctl call log: (no calls) ``` This branch, `printf 'y\n\n' | bash install.sh` (answer `y`, then the default port). Reinstall still boots out and bootstraps; `origin/main` produces the same four calls: ```text ⚠ LaunchAgent already installed at: <run>/fakehome/Library/LaunchAgents/com.headroom.proxy.plist ==> Stopping existing service... ✓ Created: <run>/fakehome/Library/LaunchAgents/com.headroom.proxy.plist ✓ LaunchAgent loaded successfully ✓ Service is running ⚠ Service is running but port 8787 is not listening yet ✓ Headroom proxy installed successfully! rc=0 --- launchctl call log: launchctl print gui/197609/com.headroom.proxy launchctl bootout gui/197609/com.headroom.proxy launchctl bootstrap gui/197609 <run>/fakehome/Library/LaunchAgents/com.headroom.proxy.plist launchctl print gui/197609/com.headroom.proxy ``` (The "port 8787 is not listening" warning comes from the `lsof` stub exiting 1; it is not a finding.) ## Real Behavior Proof - Environment: Git Bash on Windows 11 with stubbed `uname`, `launchctl`, `headroom`, `lsof`; no macOS, no real LaunchAgent. - Exact command / steps: the driver above, `echo N | bash install.sh` on `origin/main`'s script and on this branch's, then `printf 'y\n\n' | bash install.sh` on both. - Observed result: on `origin/main`, answering `N` made the stub log `launchctl bootout` before `Installation cancelled.`; on this branch the log is empty. Answering `y` makes the same four `launchctl` calls on both. - Not tested: real macOS launchd (the proof uses stubs on Windows and WSL, not a live LaunchAgent); real `launchctl` on macOS; the `--unattended` path (the block there runs unchanged, only its place in the file differs, but I did not run it). ## Runtime Rollout Safety - Rollout-managed feature(s): none; example script only. - Minimum rollout channel: n/a - Stable/default behavior changed: only the cancel path: the running service is no longer stopped when the user declines. - Kill switch / disable path: n/a - Unsafe override required: no - Qualification impact: none - Rollback path: revert this commit. ## 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 - [ ] 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 (new test file only; the stubbed runs above are the check) - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes - Scope is an example script; the effect of the bug is a stopped proxy on the user's own machine. - Other defects in the same directory are in #4730 and separate PRs. Produced with AI assistance (Claude Code) operated by me (HetCreep); the driver was run on my machine against a clone of the repository. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com>
macOS LaunchAgent Deployment
This directory contains templates and scripts for running the headroom proxy server as a persistent background service on macOS using LaunchAgent.
Quick Start
# Install the proxy service
./install.sh
# Add shell integration to ~/.bashrc or ~/.zshrc
export HEADROOM_PROXY_PORT=8787
source /path/to/shell-integration.sh
Files
- com.headroom.proxy.plist.template: LaunchAgent plist template
- install.sh: Automated installation script
- uninstall.sh: Automated removal script
- shell-integration.sh: Shell integration for automatic ANTHROPIC_BASE_URL configuration
Features
- Automatic Startup: Service starts on user login
- Crash Recovery: Automatically restarts if the proxy crashes
- Configurable Port: Default 8787, customizable during installation
- Standard Logging: Logs to
~/Library/Logs/headroom/ - Shell Integration: Automatically sets
ANTHROPIC_BASE_URLfor Claude clients
Requirements
- macOS 10.13+ (High Sierra or later)
- headroom-ai installed with proxy support:
pip install headroom-ai[proxy] - Anthropic API key configured in environment
Installation Options
Quick Install (Recommended)
./install.sh
Custom Port
./install.sh --port 9000
Unattended Install
./install.sh --port 8787 --unattended
Verification
Check if the service is running:
# Check LaunchAgent status
launchctl print gui/$(id -u)/com.headroom.proxy
# Check if port is listening
lsof -iTCP:8787 -sTCP:LISTEN
# Test health endpoint
curl http://localhost:8787/health
Logs
View logs:
# Standard output
tail -f ~/Library/Logs/headroom/proxy.log
# Error output
tail -f ~/Library/Logs/headroom/proxy-error.log
Uninstallation
# Remove service only
./uninstall.sh
# Remove service and logs
./uninstall.sh --remove-logs
Troubleshooting
Service won't start
Check logs for errors:
tail -n 50 ~/Library/Logs/headroom/proxy-error.log
Common causes:
- Missing ANTHROPIC_API_KEY environment variable
- Port already in use
- headroom not installed with proxy support
Port already in use
Find what's using the port:
lsof -iTCP:8787 -sTCP:LISTEN
Change to a different port:
./uninstall.sh
./install.sh --port 9000
Service not auto-starting
Verify LaunchAgent is loaded:
launchctl list | grep headroom
If not loaded:
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.headroom.proxy.plist
Manual Installation
If you prefer manual installation:
-
Copy template and customize:
cp com.headroom.proxy.plist.template ~/Library/LaunchAgents/com.headroom.proxy.plist -
Edit the plist file:
- Replace
__HEADROOM_PATH__with output ofcommand -v headroom - Replace
__PORT__with your desired port - Replace
__HOME__with your home directory path
- Replace
-
Create log directory:
mkdir -p ~/Library/Logs/headroom -
Load the LaunchAgent:
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.headroom.proxy.plist
Documentation
For complete documentation, see wiki/macos-deployment.md