# JetBrains Central CLI in depth

This page describes the machinery underneath JetBrains Central CLI. Knowing it is not required for day-to-day use but may be helpful when you are reviewing JetBrains Central CLI for your organization, debugging an unusual failure, or writing a support request.

JetBrains Central CLI is a single binary that combines an interactive interface, scriptable commands, agent configuration helpers, and a local reverse proxy. The proxy adds JetBrains authentication to requests coming from AI coding agents and forwards them to the JetBrains AI Platform.

![cli-proxy-overview](images/cli-proxy-overview.png)

The agent's own configuration is pointed at a local URL of the form `/wire/{secret}/{agent}/{route}/...`. The proxy validates the secret, strips the placeholder provider credentials the agent sends, adds JetBrains authentication, and streams the platform response back.

Which credentials it adds and which platform path it targets depends on where your AI access comes from:

| AI access source | Header added | Platform path |
| --- | --- | --- |
| License | `Grazie-Authenticate-JWT` | `/user/v5/llm/...` |
| Workspace | `Authorization: Bearer {ai_org_user_token}` | `/llm/...` |
| JetBrains Central Server | `Authorization: Bearer {ai_org_user_token}` | `/application/v5/llm/...` on the server's own AI Enterprise URL |

## Components

### Interactive interface and commands

Running `central` opens the interactive interface, which covers login, AI access source selection, connecting agents, proxy control, usage limits, AI logs, settings, updates, issue reporting, logout, and uninstall. Every one of those actions also has a command you can script (see [Commands](cli-commands.html)).

### Proxy

The proxy is an HTTP server bound to `127.0.0.1:{port}`. Once an agent is connected, its requests go through JetBrains Central rather than the agent's own vendor account. Usage is billed to your JetBrains AI subscription, and your organization's AI governance and usage reporting apply. The proxy also keeps a local request log, which you can view with `central log`.

For each request, the proxy:

1. Validates the proxy secret embedded in the URL, using a constant-time comparison.

2. Parses the URL into an agent name, a route, and the remaining API path.

3. Enforces AI governance for workspace-backed sessions when a policy is available.

4. Strips the provider API key headers and query parameters the agent sends.

5. Adds the JetBrains authentication header for your access source.

6. Adds `Grazie-Agent` and `X-Client-Feature-ID` for platform-side attribution.

7. Streams the response back to the agent in 4 KB chunks, so streaming output is not buffered.

8. On an upstream `401` or `403`, refreshes the token and retries once before surfacing an error.

It also enforces size and time limits: 100 MB per request body, 1 GB per response body, and an 8-minute request timeout. A `GET /health` endpoint returns `200 OK` and is used internally to confirm the proxy is ready after startup.

### Authentication

Login uses OAuth 2.0 with PKCE against JetBrains Account. Once that completes, JetBrains Central CLI discovers which AI access sources are enabled for you:

* Workspace. Validates the organization and workspace, then mints tokens for AI calls, usage limits, and governance lookups.

* License. Uses the classic JetBrains AI Platform license flow.

* JetBrains Central Server. Authenticates against the server instance you specify.

Tokens are encrypted with AES-256-GCM and stored in `~/.jetbrains-central/tokens.enc`; the encryption key lives in the system keychain — Keychain on macOS, Secret Service on Linux, Credential Manager on Windows. A background check runs every 2 hours and proactively refreshes any token that expires within the next 4 hours, so a live request rarely has to pay for a refresh.

### Agent integration

Each supported agent is integrated separately, because each one stores its settings differently. An integration knows how to detect the agent on your `PATH`, where its configuration file lives, which keys JetBrains Central CLI will change, how to connect and disconnect it, and what to pass for a one-off `central run`.

The supported agents are Claude Agent, Codex, Gemini CLI, Junie CLI, and Pi. Connecting one edits that agent's own configuration file in place, after saving a timestamped backup next to it (see [How JetBrains Central CLI configures agents](#agent-configuration) below).

### Daemon

The proxy runs as a background daemon and records its state in `~/.jetbrains-central/proxy.pid`, so it outlives the terminal session that started it and can serve agents in other terminals. If the process dies without cleaning up, JetBrains Central CLI detects the stale file and removes it.

### Configuration

Settings live in `~/.jetbrains-central/config.json`:

```JSON
{
  "proxy_port": 19516,
  "proxy_secret": "<random 32-hex token>",
  "log_level": "info",
  "release_track": "stable",
  "jumpscare-mode": true,
  "ai_access": {
    "type": "workspace",
    "org_id": "org-123",
    "workspace_id": "ws-456"
  }
}
```

Only mutable state is stored; constants and service URLs are derived at runtime. The fields you can set yourself are `proxy_port`, `log_level`, `release_track`, and `jumpscare-mode`; the rest is written for you. `jumpscare-mode` controls whether starting the proxy may open the browser login page. The file is preserved across logout, so connected agents stay connected. To read the current values or change one, use `central config` and `central config set` (see [Commands](cli-commands.html)).

## Request URL scheme

```TEXT
http://127.0.0.1:{port}/wire/{secret}/{agent}/{route}/{api-path}
```

| Segment | Example | Purpose |
| --- | --- | --- |
| `port` | `19516` | Port the proxy listens on |
| `secret` | `a1b2c3...` | Persistent CSRF token, 32 hex characters |
| `agent` | `claude-code` | Agent identity, used for routing, analytics, and governance |
| `route` | `anthropic` | Provider route (`anthropic`, `openai`, `vertex`) or protocol route (`bedrock`, `ingrazzio`)  |
| `api-path` | `v1/messages` | Forwarded to the matching platform path |

The fourth segment is usually the LLM provider, but it can also be a protocol route when your organization has provisioned protocol-specific behavior for an agent. `bedrock` applies to Claude Agent and Pi when Bedrock is provisioned; `ingrazzio` applies to Junie CLI on a JetBrains Account login.

## How JetBrains Central CLI configures agents

`central add <agent>` wires an agent: it writes routing settings into that agent's own configuration, so the agent sends its model requests to the local JetBrains Central CLI proxy instead of to the model vendor. The proxy adds your JetBrains authentication and forwards the request on:

```TEXT
agent → local proxy on 127.0.0.1 → JetBrains Central → model provider
```

That single change is what brings agent traffic under your organization's control. Because every request now passes through JetBrains Central, it can be checked against your organization's AI governance policy, counted in usage reporting and analytics, and billed to your JetBrains AI subscription rather than to a model-vendor account of your own.

The edit itself is deliberately narrow. JetBrains Central CLI reads the existing file, changes only the settings it owns, and leaves your own options, hooks, and providers as they were. Model and provider selections are the one exception: depending on the agent, JetBrains Central CLI may set a default or clear a selection that would conflict with routing, so that a freshly connected agent works without further setup.

`central add` saves a timestamped copy of the file next to the original first, when there is an existing file to copy:

```TEXT
~/.claude/settings.backup.2025-02-08T14-30-45.json
```

`central add` does not install, update, or launch the agent, and it does not touch your prompts, projects, or MCP servers. If you would rather write nothing at all, `central run <agent>` injects the same routing into a single process and leaves the configuration file untouched (see [Agents](cli-agents.html)).

> **Note:**
> The URLs JetBrains Central CLI writes into these files carry the proxy port and the proxy secret from `~/.jetbrains-central/config.json`. The secret is a local CSRF token, not a credential for the JetBrains AI Platform, but there is no reason to share it — leave it out of bug reports and screenshots.

### Where each agent is configured

Each agent stores its settings differently, so each integration writes to a different place. Select an agent to see which files JetBrains Central CLI touches and what it changes in them.

Claude Agent:

Configuration file: `~/.claude/settings.json` (JSON). If the file does not exist, JetBrains Central CLI creates it.

* Sets the Anthropic base URL (`ANTHROPIC_BASE_URL`) to the proxy, so Claude Agent sends its model requests there instead of to Anthropic.

* Adds an API key helper, which starts the proxy when Claude Agent launches and hands it the local proxy secret in place of an API key.

* Clears an Anthropic API key or authentication token left behind by an earlier setup, since either one would conflict with the key helper.

Codex:

Configuration file: `~/.codex/config.toml` (TOML).

* Adds a model provider that points at the proxy, and selects it in place of Codex's default OpenAI endpoint.

* Enables hooks and adds a session-start hook that brings the proxy up when Codex starts or resumes a session, along with the trust record Codex needs in order to run that hook without asking.

Providers you added yourself are kept, and your own session-start hooks stay ahead of the one JetBrains Central CLI adds.

Gemini CLI:

Gemini CLI is the one agent configured through two files, both in `~/.gemini/`.

`.env` carries the routing. JetBrains Central CLI sets the Vertex AI base URL to the proxy and adds the handful of accompanying variables the Google SDK needs in order to build Vertex-shaped requests and send its key as a header. The key itself is only a placeholder that keeps the SDK from looking for application default credentials — the proxy strips it and adds real JetBrains authentication.

`settings.json` selects Vertex AI as the authentication mode and adds a session-start hook that starts the proxy.

Other variables in `.env` and other settings in `settings.json` are left alone.

> **Warning:**
> Gemini CLI reads neither file in a folder you have not trusted. If you decline the workspace trust prompt, the settings JetBrains Central CLI wrote are ignored and the authentication picker comes back (see [Troubleshooting](troubleshooting.html)).

Junie CLI:

Configuration file: `~/.junie/config.json` (JSON). JetBrains Central CLI adds one or more proxy entries that point at the proxy, plus a session-start hook that starts it.

How many entries are written depends on how you logged in, because the two login modes reach different platforms. You do not choose this — JetBrains Central CLI resolves it from the active session:

* JetBrains Account. A single entry for JetBrains' own LLM gateway, which fronts several model vendors itself.

* JetBrains Central Server. That gateway does not exist there, so Junie gets one entry per model provider instead.

Entry names are cosmetic: JetBrains Central CLI recognizes its own entries by the proxy URL they point at. Proxy entries you added yourself are preserved, and only JetBrains Central CLI's own entries are replaced when Junie is re-wired — so switching login mode does not leave a stale entry behind.

Pi:

Pi is the one agent whose own settings are never edited. Instead, `central add pi` installs a single new file — an extension — and nothing else:

```TEXT
~/.pi/agent/extensions/jetbrains-central.ts
```

The extension registers Pi's providers against the proxy and sets up a session-start hook that starts the proxy. Extensions are discovered automatically, so nothing else in `~/.pi/agent/` has to change.

* Because the extension names no models, every model those providers offer stays available, along with any you added yourself.

* When your organization provisions Pi over the Amazon Bedrock protocol, the extension targets Pi's Bedrock provider instead. JetBrains Central CLI regenerates the file itself when governance switches the protocol.

### What persists

Agents stay connected across proxy restarts, reboots, logout, and JetBrains Central CLI updates. No reconnection is needed.

The exception is changing the proxy port with `central config set port`: connected agents still address the old one. Run `central add <agent>` again for each.

### What removal changes

`central remove <agent>` removes only the settings JetBrains Central CLI wrote, including those written by older versions. The agent then reaches its provider directly. Your own entries, hooks, and options are kept. Blocks left empty are removed, and a file is deleted only if JetBrains Central CLI's settings were its entire contents.

Removal rewrites the file, so comments, key order, and formatting are lost. To get the original file back, restore the backup that `central add` writes before its first edit:

* Backups are saved next to the original as `<name>.backup.<timestamp>.<extension>`, readable only by you.

* `central remove` writes no backup. The interactive interface asks whether to save one.

* Each `central add` writes another backup, so there may be several.

To restore a backup: disconnect the agent, copy the backup over the current file, restart the agent, then run `central status`.

Claude Agent:

Removed from `~/.claude/settings.json`: the routing and the API key helper. The plugin registration, which is partly outside this file, is cleared as well.

```BASH
central remove claude
ls ~/.claude/settings.backup.*.json
cp ~/.claude/settings.backup.2025-02-08T14-30-45.json ~/.claude/settings.json
```

Codex:

Removed from `~/.codex/config.toml`: the JetBrains Central CLI model provider. Codex returns to its default OpenAI endpoint. The plugin registration, which is partly outside this file, is cleared as well.

```BASH
central remove codex
ls ~/.codex/config.backup.*.toml
cp ~/.codex/config.backup.2025-02-08T14-30-45.toml ~/.codex/config.toml
```

With `CODEX_HOME` set, the configuration and its backups are in that directory instead.

Gemini CLI:

Removed from `~/.gemini/.env`: the JetBrains Central CLI variables. Removed from `~/.gemini/settings.json`: the authentication mode and the session-start hook.

Only `settings.json` has a backup. The `.env` stays as removal left it.

```BASH
central remove gemini
ls ~/.gemini/settings.backup.*.json
cp ~/.gemini/settings.backup.2025-02-08T14-30-45.json ~/.gemini/settings.json
```

Removal clears the authentication mode instead of restoring the previous value, so Gemini CLI prompts for an authentication method at the next start.

Junie CLI:

Removed from `~/.junie/config.json`: the JetBrains Central CLI proxy entries, the session-start hook, and the model and provider defaults JetBrains Central CLI set, if you have not changed them.

```BASH
central remove junie
ls ~/.junie/config.backup.*.json
cp ~/.junie/config.backup.2025-02-08T14-30-45.json ~/.junie/config.json
```

Pi:

Removal deletes the extension JetBrains Central CLI installed. Pi's own configuration is not modified. There is no backup and none is needed.

```BASH
central remove pi
```

A governance refresh removes an agent automatically when it leaves your organization's allow-list (see [Agents](cli-agents.html)). Removal does not uninstall the agent, does not log you out, and does not affect your other connected agents. To remove JetBrains Central CLI itself, run `central uninstall` (see [Setup](cli-setup.html)).

## See also

### Learn how to

[Agents](cli-agents.html) [Setup](cli-setup.html)

### Related

[Commands](cli-commands.html) [Data collection](cli-data-collection.html) [Troubleshooting](troubleshooting.html)