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

> Deploy Headroom as a macOS LaunchAgent for persistent proxy server installs. Automate startups and restarts with `headroom install apply --preset persistent-service`.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-13

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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:

```bash

# 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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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:

```bash

# 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`](https://github.com/chopratejas/headroom/blob/main/install.sh) script performs the steps documented in [`wiki/macos-deployment.md`](https://github.com/chopratejas/headroom/blob/main/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:

```bash

# 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`](https://github.com/chopratejas/headroom/blob/main/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:

```bash

# 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`](https://github.com/chopratejas/headroom/blob/main/wiki/persistent-installs.md) (lines 16-24).

Test connectivity using the health endpoint:

```bash

# 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`](https://github.com/chopratejas/headroom/blob/main/src/proxy.rs) (or [`crates/headroom-proxy/src/proxy.rs`](https://github.com/chopratejas/headroom/blob/main/crates/headroom-proxy/src/proxy.rs)).

### Lifecycle Management

Control the persistent service using the install CLI subcommands:

```bash

# 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`](https://github.com/chopratejas/headroom/blob/main/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:

```bash
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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`.