mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
0d4571f72f
## Description The macOS LaunchAgent example README links to `../../../docs/macos-deployment.md`, but that file does not exist — the guide lives at `wiki/macos-deployment.md`. This fixes the broken link (path and text) so "complete documentation" resolves. Closes # ## 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) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `examples/deployment/macos-launchagent/README.md`: link target `../../../docs/macos-deployment.md` → `../../../wiki/macos-deployment.md`, and the link text `docs/macos-deployment.md` → `wiki/macos-deployment.md`. ## Testing <!-- Check what you actually ran, then paste the real command output below. --> - [ ] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [ ] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text # The old target does not exist; the real guide is under wiki/: $ git ls-files '*macos-deployment.md' wiki/macos-deployment.md $ ls docs/content/docs | grep -i macos # nothing — no docs/macos-deployment.md $ test -f examples/deployment/macos-launchagent/../../../wiki/macos-deployment.md && echo "new link resolves" new link resolves # This was the only stale reference to docs/macos-deployment.md in the repo: $ grep -rn 'docs/macos-deployment' --include='*.md' --include='*.mdx' . (only the line fixed by this PR, now pointing at wiki/) ``` ## Real Behavior Proof - Environment: local clone at `origin/main`; documentation-only change. - Exact command / steps: ran a relative-link checker across all Markdown/MDX, which flagged `examples/deployment/macos-launchagent/README.md:168` as the only broken internal link; confirmed the guide is at `wiki/macos-deployment.md`; repointed the link there. - Observed result: the new relative path `../../../wiki/macos-deployment.md` resolves to the existing macOS Deployment Guide (which itself documents this exact LaunchAgent setup). - Not tested: N/A — single-line Markdown link fix; no code, build, or runtime behavior involved. ## 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 - [ ] I have updated the CHANGELOG.md if applicable ## Additional Notes Documentation-only change, so `pytest`/`ruff`/`mypy` over the `headroom` package are N/A — the diff contains no Python source. The target guide (`wiki/macos-deployment.md`) covers the same LaunchAgent deployment this example sets up, so it is the correct destination for "complete documentation".
168 lines
3.2 KiB
Markdown
168 lines
3.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# Install the proxy service
|
|
./install.sh
|
|
|
|
# Add shell integration to ~/.bashrc or ~/.zshrc
|
|
export HEADROOM_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_URL` for 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)
|
|
|
|
```bash
|
|
./install.sh
|
|
```
|
|
|
|
### Custom Port
|
|
|
|
```bash
|
|
./install.sh --port 9000
|
|
```
|
|
|
|
### Unattended Install
|
|
|
|
```bash
|
|
./install.sh --port 8787 --unattended
|
|
```
|
|
|
|
## Verification
|
|
|
|
Check if the service is running:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# Standard output
|
|
tail -f ~/Library/Logs/headroom/proxy.log
|
|
|
|
# Error output
|
|
tail -f ~/Library/Logs/headroom/proxy-error.log
|
|
```
|
|
|
|
## Uninstallation
|
|
|
|
```bash
|
|
# Remove service only
|
|
./uninstall.sh
|
|
|
|
# Remove service and logs
|
|
./uninstall.sh --remove-logs
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Service won't start
|
|
|
|
Check logs for errors:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
lsof -iTCP:8787 -sTCP:LISTEN
|
|
```
|
|
|
|
Change to a different port:
|
|
|
|
```bash
|
|
./uninstall.sh
|
|
./install.sh --port 9000
|
|
```
|
|
|
|
### Service not auto-starting
|
|
|
|
Verify LaunchAgent is loaded:
|
|
|
|
```bash
|
|
launchctl list | grep headroom
|
|
```
|
|
|
|
If not loaded:
|
|
|
|
```bash
|
|
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.headroom.proxy.plist
|
|
```
|
|
|
|
## Manual Installation
|
|
|
|
If you prefer manual installation:
|
|
|
|
1. Copy template and customize:
|
|
|
|
```bash
|
|
cp com.headroom.proxy.plist.template ~/Library/LaunchAgents/com.headroom.proxy.plist
|
|
```
|
|
|
|
2. Edit the plist file:
|
|
- Replace `__HEADROOM_PATH__` with output of `command -v headroom`
|
|
- Replace `__PORT__` with your desired port
|
|
- Replace `__HOME__` with your home directory path
|
|
|
|
3. Create log directory:
|
|
|
|
```bash
|
|
mkdir -p ~/Library/Logs/headroom
|
|
```
|
|
|
|
4. Load the LaunchAgent:
|
|
|
|
```bash
|
|
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.headroom.proxy.plist
|
|
```
|
|
|
|
## Documentation
|
|
|
|
For complete documentation, see [wiki/macos-deployment.md](../../../wiki/macos-deployment.md)
|