How to Start the Local Caveman Proxy: Installation, Startup, and Verification

You can start the local Caveman proxy by running caveman start after installing the CLI with npm install -g @caveman-ai/cli, or let it auto-launch when invoking any agent command like caveman claude.

The Caveman proxy is a lightweight Go binary included in the JuliusBrussee/caveman repository that intercepts provider-side HTTP traffic on 127.0.0.1, enabling local compression before data reaches your LLM. The proxy ships as part of the @caveman-ai/cli package and runs on port 8787 by default. This guide walks through the exact commands and environment variables required to install, launch, and verify the proxy using the source implementation.

Installing the Caveman CLI and Proxy Binary

Before you can start the local Caveman proxy, you must install the CLI and its required binaries. The CLI is distributed via npm and includes a setup command that builds and installs the proxy binary.

Run the following command to install the CLI globally and execute the setup routine:

npm install -g @caveman-ai/cli && caveman setup --install

The caveman setup --install command checks for required binaries—including caveman-proxy and caveman-engine—and builds them if missing. By default, these binaries are placed in ~/.caveman/bin as documented in the Install section of README.md.

Starting the Local Caveman Proxy

Once installed, you have two methods to start the proxy: explicit command execution or automatic startup via agent invocation.

Explicit Startup with caveman start

To manually start the proxy, use the top-level CLI command:

caveman start

This command invokes the binary specified by the CAVEMAN_PROXY_BIN environment variable, or falls back to the binary located at ~/.caveman/bin/caveman-proxy. The proxy binds to 127.0.0.1:8787 by default and prints a status panel showing the PID and binary path. If port 8787 is already in use, the proxy displays an informative error message rather than crashing.

The environment variable handling and server initialization logic resides in proxy/internal/gateway/server.go according to the proxy's internal architecture documentation.

Automatic Startup via Agent Commands

If you prefer not to run the start command manually, the CLI includes built-in "pre-start" logic that automatically launches the proxy the first time it is needed. Any caveman <agent> invocation will trigger this behavior:

caveman claude

This command starts the proxy in the background if it is not already running, then launches the Claude Code agent. This automatic startup mechanism is implemented in the CLI package and documented in packages/cli/README.md.

Verifying the Proxy is Running

After startup, confirm the proxy is accepting connections by querying its health endpoint:

curl -s http://127.0.0.1:8787/health/ready

A successful response returns JSON indicating the service state:

{"status":"ready","pid":12345}

The proxy also outputs its process ID and binary location to the terminal status panel upon startup, allowing you to verify which binary is running without using curl.

Configuring the Proxy with Environment Variables

The proxy respects several environment variables for customization, as defined in proxy/internal/gateway/server.go and documented in proxy/CLAUDE.md:

• CAVEMAN_PROXY_BIN: Specifies a custom path to the caveman-proxy binary, overriding the default ~/.caveman/bin location.
• CAVEMAN_PROXY_PORT: Overrides the default listen port of 8787.
• CAVEMAN_TELEMETRY: Controls anonymous telemetry collection; set to 0 to disable.

These variables allow you to run multiple proxy instances or integrate the binary into custom deployment pipelines while maintaining the same CLI interface.

Summary

• Install the CLI and proxy binary using npm install -g @caveman-ai/cli && caveman setup --install, which populates ~/.caveman/bin by default.
• Start the local Caveman proxy explicitly with caveman start or let it auto-start when running agent commands like caveman claude.
• Verify operation by checking http://127.0.0.1:8787/health/ready for a ready status response.
• Customize behavior using CAVEMAN_PROXY_BIN, CAVEMAN_PROXY_PORT, and CAVEMAN_TELEMETRY environment variables.

Frequently Asked Questions

What port does the Caveman proxy use by default?

The proxy binds to 127.0.0.1:8787 by default. You can override this by setting the CAVEMAN_PROXY_PORT environment variable before starting the proxy, as implemented in proxy/internal/gateway/server.go.

Can I start the Caveman proxy without installing the CLI?

No, the recommended workflow requires the NPM CLI. The caveman setup --install command ensures that the caveman-proxy binary is compiled and available in ~/.caveman/bin. While you could theoretically run the binary directly from a manual build, the CLI manages environment variables and lifecycle hooks that the proxy expects.

How do I know if the proxy started successfully when using an agent command?

When running commands like caveman claude, the CLI checks for an existing proxy process before launching the agent. If the proxy is not running, it starts silently in the background. You can verify the proxy started by running curl http://127.0.0.1:8787/health/ready in another terminal or by checking for the PID logged in the initial CLI output.

Where does the Caveman proxy store its binary after installation?

By default, the setup command places the caveman-proxy binary in ~/.caveman/bin. You can change which binary the CLI invokes by exporting the CAVEMAN_PROXY_BIN environment variable to point to a different path, which is useful for testing custom builds or running specific versions from the JuliusBrussee/caveman repository.

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