Files
HetCreepandClaude Sonnet 5.5 46a3d910c9 docs(examples): name the port variable shell-integration.sh reads (#4735)
## 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>
2026-11-10 09:08:18 -06:00

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

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