# cc-gateway: a reverse proxy that rewrites Claude Code's device identity

> cc-gateway sits between Claude Code and the Anthropic API and replaces the device fingerprint, environment block and process metrics with one canonical profile. It is an alpha-stage TypeScript proxy for people running the CLI on several machines.

**motiful/cc-gateway** — AI API identity gateway — reverse proxy that normalizes device fingerprints and telemetry for privacy-preserving API proxying

- Repository: https://github.com/motiful/cc-gateway
- Stars: 3,056 · Forks: 503
- Language: TypeScript
- License: MIT
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/motiful-cc-gateway

## The problem cc-gateway takes on

Claude Code reports a lot about the machine it runs on. The README states that the client collects 640+ telemetry event types across three parallel channels, fingerprints the host with 40+ environment dimensions, and phones home every five seconds. Device ID, email, OS version, installed runtimes, shell type, CPU architecture and physical RAM are all part of that stream. Run the CLI on a laptop and a desktop and each gets its own permanent identifier, with no built-in way to decide how that identity is presented.

cc-gateway targets that gap. It is a reverse proxy placed between the Claude Code client and the Anthropic API. Rather than blocking telemetry, it rewrites the fields before they leave your network, mapping every machine onto a single canonical profile. The audience is narrow and specific: people who already run Claude Code on more than one machine, or who run it on a machine whose hardware and toolchain they would rather not describe in detail, and who are willing to put a proxy in the request path to change that. It is not a general API gateway and it does not proxy arbitrary HTTP services.

## What the rewriter actually changes in each request

The README describes the rewrite as substitution rather than patching. The env object, which carries the 40+ environment dimensions, is replaced wholesale, not edited field by field. Device ID and email in metadata and events are mapped to a canonical value. Process metrics are masked too: constrainedMemory, which reports physical RAM, becomes a canonical figure, while rss, heapTotal and heapUsed are randomized inside what the README calls a realistic range. That last choice is worth noting. Randomized heap numbers are less obviously fake than a fixed constant, but they are also not reproducible, so anyone debugging a memory-related client issue through the gateway is looking at synthetic values.

The prompt text is rewritten as well. The env block that Claude Code injects into every prompt (Platform, Shell, OS Version, working directory) is adjusted to match the canonical profile, and home directory prefixes such as /Users/xxx/ and /home/xxx/ are replaced with a canonical prefix. On the header side, User-Agent is set to a canonical Claude Code version, x-api-key is replaced with the real OAuth token injected by the gateway, and x-anthropic-billing-header is stripped entirely. Two leak fields, baseUrl and gateway, are removed so that analytics events do not reveal that a proxy is in use.

The billing header removal is the one item the README ties to an official switch, noting it is consistent with CLAUDE_CODE_ATTRIBUTION_HEADER=false. The README also links to a Claude Code issue and claims this enables cross-session prompt cache sharing and reduces system prompt costs by roughly 85 percent. That figure comes from the project's own documentation, not from an independent measurement, and the caching behaviour depends on the upstream API rather than on the proxy alone.

## Installing cc-gateway and routing a first client through it

The quick start assumes Node.js 22 or newer and an existing Claude Code login on the same machine. The setup script extracts OAuth credentials from the macOS Keychain, generates a canonical device identity and a client token, writes config.yaml, produces a launcher under ./clients/, and starts the gateway on http://localhost:8443.

```bash
git clone https://github.com/motiful/cc-gateway.git
cd cc-gateway
npm install
bash scripts/quick-setup.sh
```

After that, the launcher script is the entry point. Running it starts Claude Code with traffic routed through the gateway, and the README says no environment variables need to be set and no files edited by hand.

```bash
./clients/cc-<hostname>
```

For a second person, the admin generates a separate launcher with a unique token, and the recipient installs it as the ccg command.

```bash
bash scripts/add-client.sh alice
```

```bash
chmod +x cc-alice
./cc-alice install
ccg
```

All Claude arguments are documented as passing through, so ccg --print "hello" and ccg --resume behave as expected. The ccg hijack command aliases claude to ccg for new terminals, and ccg release restores the native binary; both are opt-in and reversible. If the machine reaches the internet through a proxy, the setup script accepts HTTPS_PROXY, for example HTTPS_PROXY=http://127.0.0.1:7890, and routes both API calls and token refresh through it. For a container deployment the README points at scripts/admin-setup.sh, which builds and starts the Docker image, mounts config.yaml and certs read-only, and publishes port 8443. The compose file defines a healthcheck that fetches http://localhost:8443/_health every 30 seconds, so that endpoint is the first thing to check when a container reports unhealthy.

## Where cc-gateway stops being the right tool

The project labels itself alpha and tells you to test with a non-primary account first. Treat that as the primary constraint. A proxy that rewrites request bodies sits directly in the path of every API call, so a bug in the rewriter is not a cosmetic problem; it is a failed request or, worse, a malformed one. The README does not document a rollback path for a bad config, and the repository has no releases, so there is no versioned artifact to pin to. You are running main.

The scope of the rewrite is also narrower than the tagline suggests. It normalizes what the client reports. It does not change your IP address, it does not encrypt anything the client sends, and it does not stop a network observer from seeing that traffic goes to the Anthropic API. If your threat model is a corporate middlebox rather than vendor-side profiling, this is the wrong layer. There is also a practical cost to the canonical identity itself: because every client presents the same device ID and the same environment, per-device usage attribution inside the vendor's own analytics is gone. That is the intent, but it is a real trade, and it means you cannot use the vendor dashboard to tell which machine made a request. Centralized OAuth is another trade: the gateway holds the refresh token and clients never contact platform.claude.com, which concentrates the credential in one place. The README gives no detail on how that token is stored at rest beyond the config file and the Keychain extraction step.

## How it compares with a plain forward proxy

The obvious alternative is a general forward proxy such as mitmproxy or a Squid instance with TLS interception. The difference is where the logic lives. A forward proxy operates on the connection and on HTTP semantics; to change a device_id inside a JSON body it needs a script or an addon that parses the payload, and you write and maintain that script yourself. cc-gateway ships the field-level knowledge already: which fields exist, which object gets replaced wholesale, which header gets stripped. The README's rewrite table is effectively a specification of that knowledge, and the repository carries it in src/ with tests in tests/rewriter.test.ts.

The trade runs the other way too. A forward proxy is generic, so it covers any client you point at it and any endpoint, and it is a well-understood piece of infrastructure. cc-gateway only understands Claude Code. Point another client at it and you get a proxy that rewrites fields the other client never sends. If your requirement is "route this traffic through a controlled egress point," a forward proxy answers it. If your requirement is "make three machines look like one machine to this specific API," cc-gateway is doing work a forward proxy would leave to you.

## Licence, maintenance and what an upgrade costs

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive grant, and it also means the authors offer no warranty. The README carries a disclaimer section and a separate disclaimer link; read it in full before deploying, since the project is explicitly altering request data sent to a third-party service. Nothing here is legal advice, and the terms of the upstream API are a separate question from the licence of this proxy.

On maintenance, the last push to the repository was on 2026-04-02, and the package version is 0.2.0 with no releases published. The README describes the project as under active development, but the commit history is the thing to check, and there is no release cadence to plan around. Upgrading means pulling main and reinstalling dependencies. The dependency surface is small, which helps: the runtime dependencies listed in package.json are https-proxy-agent and yaml, with tsx and typescript on the development side. The Dockerfile builds with node:22-slim in two stages and runs node dist/index.js with the config path as an argument, so a container upgrade is a rebuild rather than a pull. Because config.yaml is mounted read-only, a change to the rewriter's expectations about config keys is the failure mode to watch for across an upgrade; the repository includes config.example.yaml, so diffing your live config against that example is the cheap check before restarting.

## Conclusion

Adopt cc-gateway if you run Claude Code across several machines and want one canonical identity presented to the API, and you are comfortable running alpha software against a non-primary account. Do not adopt it if you need a stable, documented release, if you cannot inspect the rewriter in src/, or if you expect it to hide your traffic from a corporate network monitor; it normalizes what the client reports, not where the packets go. Before trusting it, read config.example.yaml against the config.yaml the setup script writes, run npm test to see the rewriter assertions, and confirm the _health endpoint answers on port 8443 after a container start.

## FAQ

### What is cc-gateway and what does it do?

It is a reverse proxy that sits between Claude Code and the Anthropic API and normalizes device identity, the environment fingerprint and process metrics to one canonical profile. The README describes it as an AI API identity gateway that gives you control over what telemetry leaves your network.

### What is a CC gateway in the context of Claude Code?

In this project, it is the proxy process that Claude Code clients connect through instead of reaching the Anthropic API directly. It rewrites the request fields listed in the README's rewrite table, injects the real OAuth token, and strips the billing header and proxy-revealing leak fields.

### What are the requirements to install cc-gateway?

The quick start states Node.js 22 or newer and an existing Claude Code login on the same machine. The setup script extracts OAuth credentials from the macOS Keychain, so that extraction step is macOS-specific as documented.

### Does cc-gateway change the claude command on my machine?

Not by default. The README says ccg and claude coexist, and that ccg hijack is what aliases claude to ccg for new terminals. ccg release restores the native claude binary, so the change is reversible.

### Can cc-gateway run behind an HTTP proxy?

Yes. The README documents HTTPS_PROXY and HTTP_PROXY support for outbound connections, and gives the example of running the setup script with HTTPS_PROXY=http://127.0.0.1:7890 so that API calls and token refresh both route through it.

### Is cc-gateway stable enough for a primary account?

The README marks the project as alpha and advises testing with a non-primary account first. There are no published releases, so there is no versioned artifact to pin an upgrade to.

## Sources

- [Issues](https://github.com/motiful/cc-gateway/issues)
- [License: MIT](https://github.com/motiful/cc-gateway/blob/main/LICENSE)
- [motiful/cc-gateway on GitHub](https://github.com/motiful/cc-gateway)
- [README](https://github.com/motiful/cc-gateway/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/motiful-cc-gateway