How to Set Up Persistent Installs for Headroom's Proxy Server on macOS

Use headroom install apply --preset persistent-service to deploy Headroom as a macOS LaunchAgent that automatically starts at login, restarts on crashes, and routes AI client traffic through localhost:8787.

Headroom is an open-source proxy server that optimizes AI API calls through caching and compression. While you can run it on-demand with headroom proxy, production environments require a persistent install that survives reboots and system crashes according to the chopratejas/headroom source code. This guide explains how to configure Headroom's persistent-service preset on macOS using LaunchAgent integration.

Understanding the Persistent Service Architecture

Headroom's persistent install architecture consists of three coordinated layers that manage the proxy lifecycle.

The Deployment Manifest

When you run the install command, Headroom creates a deployment manifest under ~/.headroom/deploy/… that stores configuration state. The persistent-service preset instructs the CLI to generate a macOS LaunchAgent configuration rather than a foreground process. As documented in wiki/persistent-installs.md, this manifest tracks the selected port (default 8787), enabled providers, and supervisor type.

LaunchAgent Integration

The persistent install creates a property-list file (.plist) that defines how macOS manages the proxy process. According to wiki/macos-deployment.md, this configuration specifies:

• The executable path and launch arguments
• Environment variables exported to the process
• Standard output and error log paths
• Crash recovery behavior via KeepAlive directives

The LaunchAgent ensures the proxy restarts automatically if it crashes and starts immediately when you log in.

Installing the Persistent Proxy

You can deploy Headroom either through the automated CLI workflow or by manually configuring the LaunchAgent files.

Automated Installation via CLI

The recommended approach uses Headroom's built-in install command, which creates the manifest, generates the plist, and loads the service in one operation:

# Install the proxy as a persistent service with automatic provider detection

headroom install apply --preset persistent-service --providers auto

This command references the implementation in src/cli.rs (or equivalent Rust entry point) that writes the deployment manifest and invokes the LaunchAgent loading sequence. The --preset persistent-service flag specifically triggers the macOS service supervisor path as defined in wiki/persistent-installs.md (line 23).

Manual LaunchAgent Setup

For custom configurations or specialized deployment scenarios, use the manual installer provided in the examples directory:

# Navigate to the macOS deployment example

cd examples/deployment/macos-launchagent

# Run the interactive installer (prompts for port, defaults to 8787)

./install.sh

The install.sh script performs the steps documented in wiki/macos-deployment.md (lines 64-70): creating log directories, copying com.headroom.proxy.plist.template to ~/Library/LaunchAgents/, substituting template variables, and executing launchctl load.

Configuring Shell Integration

To ensure AI clients automatically route through the proxy, source the shell integration script in your shell configuration:

# Add to ~/.zshrc or ~/.bash_profile

source /path/to/headroom/examples/deployment/macos-launchagent/shell-integration.sh

This script, referenced in wiki/macos-deployment.md, checks if the LaunchAgent is running and sets ANTHROPIC_BASE_URL (or other provider-specific variables) to http://localhost:8787. It optionally starts the service if not already active, ensuring seamless integration with Claude, Copilot, and other supported tools.

Managing and Verifying the Service

Once installed, the persistent service runs independently of your terminal sessions.

Checking Service Status

Verify the deployment state and confirm the LaunchAgent is active:

# Display current persistent install status

headroom install status

The output includes the profile, preset, runtime, and supervisor fields, confirming the service is managed via LaunchAgent as documented in wiki/persistent-installs.md (lines 16-24).

Test connectivity using the health endpoint:

# Verify the proxy is responding

curl http://localhost:8787/health

A response of {"status":"healthy"} confirms the LaunchAgent is successfully serving the proxy implementation from src/proxy.rs (or crates/headroom-proxy/src/proxy.rs).

Lifecycle Management

Control the persistent service using the install CLI subcommands:

# Stop the persistent proxy

headroom install stop

# Restart the service after configuration changes

headroom install restart

# Remove the deployment and unload the LaunchAgent

headroom install remove

These commands interact with the same manifest created during installation, ensuring clean lifecycle management without orphaned processes as specified in wiki/persistent-installs.md (lines 48-56).

Testing the Proxy Connection

Confirm client tools route through the persistent proxy by setting the environment variable and making a test request:

export ANTHROPIC_BASE_URL=http://localhost:8787
python - <<'PY'
import anthropic
client = anthropic.Anthropic()
resp = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=50,
    messages=[{"role":"user","content":"Hello"}],
)
print(resp.content[0].text)
PY

This test validates the full data path: the client connects to localhost:8787, the Headroom proxy (running under the LaunchAgent) processes the request, and the response returns through the cached layer as described in wiki/macos-deployment.md (lines 52-63).

Summary

• Use the persistent-service preset with headroom install apply to create a LaunchAgent that survives reboots and crashes.
• The deployment manifest at ~/.headroom/deploy/… stores your configuration and maps to the macOS service supervisor.
• Shell integration automatically configures ANTHROPIC_BASE_URL to point to localhost:8787 for seamless client routing.
• Manage the lifecycle using headroom install status, stop, restart, and remove commands rather than manual launchctl operations.
• Verify health via curl http://localhost:8787/health before deploying client workloads.

Frequently Asked Questions

What is the difference between headroom proxy and headroom install apply?

headroom proxy starts a foreground process that terminates when you close the terminal or log out. headroom install apply --preset persistent-service creates a background LaunchAgent service that starts automatically at login, restarts after crashes, and continues running between sessions. The persistent install is recommended for daily development workflows.

Where does the LaunchAgent store log files?

The LaunchAgent configuration generated by install.sh or the CLI typically writes logs to ~/Library/Logs/headroom/ or paths specified in the generated plist template at examples/deployment/macos-launchagent/com.headroom.proxy.plist.template. Check the StandardOutPath and StandardErrorPath keys in ~/Library/LaunchAgents/com.headroom.proxy.plist for exact locations.

Can I change the port after installation?

Yes, but you must update the deployment manifest and reload the service. Run headroom install remove to clear the existing configuration, then headroom install apply --preset persistent-service --port <NEW_PORT> to recreate the LaunchAgent with the new port. Alternatively, manually edit the plist file and run launchctl unload followed by launchctl load.

How do I uninstall the persistent proxy completely?

Run headroom install remove to delete the deployment manifest and unload the LaunchAgent. For manual installations, run examples/deployment/macos-launchagent/uninstall.sh or execute launchctl unload ~/Library/LaunchAgents/com.headroom.proxy.plist followed by rm ~/Library/LaunchAgents/com.headroom.proxy.plist.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}