mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
## Description `examples/deployment/macos-launchagent/README.md` (line 12 on `1da8930a`) tells users to add `export HEADROOM_PORT=8787` before sourcing `shell-integration.sh`. That script reads `HEADROOM_PROXY_PORT` (`shell-integration.sh:22`), and `install.sh:214` prints the same name in its own instructions. A user who follows the README with a non-default port exports a variable the script ignores, so it checks port 8787 and sets `ANTHROPIC_BASE_URL` to the wrong port or reports the proxy as not running. This PR changes the README line to `HEADROOM_PROXY_PORT`. Docs only. Part of #4730 ## Type of Change - [ ] 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) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `examples/deployment/macos-launchagent/README.md`: `export HEADROOM_PORT=8787` becomes `export HEADROOM_PROXY_PORT=8787`. One line. ## Testing - [ ] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [ ] New tests added for new functionality - [x] Manual testing performed Docs-only change; no code to run. Manual check: a grep of the directory before and after (below). ### Test Output `grep -rn "HEADROOM_PORT\|HEADROOM_PROXY_PORT" examples/deployment/macos-launchagent` on `origin/main` (`1da8930a`): ```text ./com.headroom.proxy.plist.template:24: <key>HEADROOM_PROXY_PORT</key> ./install.sh:214:echo " export HEADROOM_PROXY_PORT=${PORT}" ./README.md:12:export HEADROOM_PORT=8787 ./shell-integration.sh:11:# export HEADROOM_PROXY_PORT=8787 # Optional: customize port (default: 8787) ./shell-integration.sh:22:HEADROOM_PROXY_PORT="${HEADROOM_PROXY_PORT:-8787}" ./shell-integration.sh:34: lsof -iTCP:"${HEADROOM_PROXY_PORT}" -sTCP:LISTEN -t >/dev/null 2>&1 ./shell-integration.sh:59: export ANTHROPIC_BASE_URL="http://localhost:${HEADROOM_PROXY_PORT}" ./shell-integration.sh:64: export ANTHROPIC_BASE_URL="http://localhost:${HEADROOM_PROXY_PORT}" ./shell-integration.sh:65: echo "✓ Headroom proxy started on port ${HEADROOM_PROXY_PORT}" ./shell-integration.sh:68: echo "⚠ Headroom proxy not running on port ${HEADROOM_PROXY_PORT}" ``` This branch (same command): identical, except line 12 is now ```text ./README.md:12:export HEADROOM_PROXY_PORT=8787 ``` so `HEADROOM_PORT` no longer appears in the directory. ## Real Behavior Proof - Environment: docs-only; read in a clone of the repository at `1da8930a`. - Exact command / steps: the grep above, before and after. - Observed result: `README.md:12` was the only place in the directory that used `HEADROOM_PORT`; after the change every mention uses the name `shell-integration.sh` reads. - Not tested: the script itself was not run (docs-only). `wiki/macos-deployment.md` (lines 185, 249, 532) uses `HEADROOM_PORT` for the same shell-integration step; I left it out to keep this PR to the example directory. ## Runtime Rollout Safety - Rollout-managed feature(s): none; docs only. - Minimum rollout channel: n/a - Stable/default behavior changed: no - 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 - [ ] 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 - [ ] 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 (docs only, none affected) - [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 - Other defects in the same directory are in #4730 and separate PRs. Produced with AI assistance (Claude Code) operated by me (HetCreep). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
3.2 KiB
3.2 KiB
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