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
pratikbin 42b1cd24de docs: fix env var discrepancies across markdown files 
Audit all .md files against codebase; fix wrong names, remove phantom
variables, and correct outdated values:

- HEADROOM_PROXY_PORT → HEADROOM_PORT (proxy.py envvar="HEADROOM_PORT")
- HEADROOM_BIND → HEADROOM_HOST + HEADROOM_PORT (RUST_DEV.md)
- HEADROOM_LEARN_{CLAUDE,CODEX,GEMINI}_ENABLED → HEADROOM_LEARN_CLI
  (only HEADROOM_LEARN_CLI exists in learn/analyzer.py)
- HEADROOM_TRACING_ENABLED → HEADROOM_LANGFUSE_ENABLED=1 with correct
  LANGFUSE_PUBLIC_KEY/SECRET_KEY vars (tracing.py)
- HEADROOM_LOG_LEVEL/LOG_FORMAT → --log-level CLI flag / RUST_LOG
  (no HEADROOM_LOG_LEVEL var exists in code)
- HEADROOM_LOG_LEVEL/HEADROOM_STORE_URL/HEADROOM_DEFAULT_MODE rows
  removed from wiki/configuration.md (all phantom)
- HEADROOM_SUMMARY_{ENABLED,THRESHOLD,RATIO} noted as not yet
  implemented (no code exists)
- HEADROOM_DB_URL/HEADROOM_CACHE_BACKEND → explanatory notes pointing
  to HEADROOM_WORKSPACE_DIR (no external DB support in code)
- HEADROOM_DB_PATH/HEADROOM_CACHE_PATH table rows replaced with actual
  HEADROOM_WORKSPACE_DIR/CONFIG_DIR (paths.py)
2026-05-29 15:04:13 +05:30
..
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 env var discrepancies across markdown files 2026-05-29 15:04:13 +05:30
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 docs/macos-deployment.md