# How to Start the Local Caveman Proxy: Installation, Startup, and Verification > Learn how to start the local Caveman proxy easily. Install the CLI with npm and run `caveman start` or let it auto-launch with any agent command. - Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman) - Tags: how-to-guide - Published: 2026-09-06 --- **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: ```bash 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`](https://github.com/JuliusBrussee/caveman/blob/main/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: ```bash 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`](https://github.com/JuliusBrussee/caveman/blob/main/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 ` invocation will trigger this behavior: ```bash 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`](https://github.com/JuliusBrussee/caveman/blob/main/packages/cli/README.md). ## Verifying the Proxy is Running After startup, confirm the proxy is accepting connections by querying its health endpoint: ```bash curl -s http://127.0.0.1:8787/health/ready ``` A successful response returns JSON indicating the service state: ```json {"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`](https://github.com/JuliusBrussee/caveman/blob/main/proxy/internal/gateway/server.go) and documented in [`proxy/CLAUDE.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.