akadmin/headroom
1
0
Fork 0
mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
headroom/examples/deployment/macos-launchagent
History
Exact
Dashsoap 0d4571f72f
docs: fix broken macos-deployment.md link in launchagent example (#985) 
## 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".
2026-06-16 09:43:08 -05:00
..
com.headroom.proxy.plist.template fix(deployment): correct port placeholder in LaunchAgent plist template 2026-01-19 13:44:30 -08:00
install.sh docs(deployment): add macOS LaunchAgent deployment guide and templates 2026-01-19 13:34:52 -08:00
README.md docs: fix broken macos-deployment.md link in launchagent example (#985) 2026-06-16 09:43:08 -05:00
shell-integration.sh docs(deployment): add macOS LaunchAgent deployment guide and templates 2026-01-19 13:34:52 -08:00
uninstall.sh docs(deployment): add macOS LaunchAgent deployment guide and templates 2026-01-19 13:34:52 -08:00

README.md

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_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)

./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:

  1. Copy template and customize:

    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:

    mkdir -p ~/Library/Logs/headroom

  4. Load the LaunchAgent:

    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.headroom.proxy.plist

Documentation

For complete documentation, see wiki/macos-deployment.md