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.

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).

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:

Validates the proxy secret embedded in the URL, using a constant-time comparison.
Parses the URL into an agent name, a route, and the remaining API path.
Enforces AI governance for workspace-backed sessions when a policy is available.
Strips the provider API key headers and query parameters the agent sends.
Adds the JetBrains authentication header for your access source.
Adds Grazie-Agent and X-Client-Feature-ID for platform-side attribution.
Streams the response back to the agent in 4 KB chunks, so streaming output is not buffered.
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, Pi, and GitHub Copilot. 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 below). GitHub Copilot is configured through environment variables instead.

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:

                {
                  "proxy_port": 19516,
                  "proxy_secret": "<random 32-hex token>",
                  "log_level": "info",
                  "release_track": "stable",
                  "jumpscare-mode": true,
                  "google_analytics_accepted": 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, jumpscare-mode, approve-all-policies, and google_analytics_accepted; the rest is written for you. approve-all-policies controls whether MCP servers are approved automatically. jumpscare-mode controls whether starting the proxy may open the browser login page. google_analytics_accepted stores your product analytics choice, and is omitted from the file until you make one — see When product analytics are sent. 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).

Request URL scheme

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. GitHub Copilot uses the copilot agent segment with the openai or anthropic route, depending on the provider you selected.

How JetBrains Central CLI configures agents

central add <agent> connects 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:

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:

~/.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 your own 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).

Both central add and central run also register a JetBrains Central CLI plugin or extension with the agent. If your organization provides MCP servers, JetBrains Central CLI writes the servers you allow to ~/.jetbrains-central/provisioned/, and the plugin adds them to the agent. The files are written for every agent that supports MCP servers, but only agents that you connect or run through JetBrains Central CLI use them.

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.

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.

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 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.

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 connected again — so switching login mode does not leave a stale entry behind.

Pi's own settings are never edited. Instead, central add pi installs a single new file — an extension — and nothing else:

~/.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.

GitHub Copilot is the one agent configured through environment variables rather than through its own configuration file. JetBrains Central CLI uses Copilot's bring-your-own-key (BYOK) mode, in which Copilot sends its requests to a model provider you specify — here, the proxy. No GitHub account or Copilot subscription is involved.

JetBrains Central CLI sets the following variables:

COPILOT_PROVIDER_BASE_URL: the proxy address for the provider you selected.
COPILOT_PROVIDER_TYPE: openai or anthropic.
COPILOT_MODEL: the model you selected.
COPILOT_PROVIDER_API_KEY: a placeholder key. The proxy replaces it with your JetBrains credentials.
COPILOT_PROVIDER_WIRE_API (responses, for OpenAI only) and COPILOT_PROVIDER_TRANSPORT (http): how Copilot talks to the proxy.

It also clears COPILOT_PROVIDER_BEARER_TOKEN, COPILOT_PROVIDER_HEADERS, COPILOT_PROVIDER_MODEL_ID, and COPILOT_PROVIDER_WIRE_MODEL.

On macOS and Linux, the variables are set in an environment file:

~/.jetbrains-central/agents/copilot/configure-env.sh

JetBrains Central CLI loads the file from the startup files of Bash and Zsh, the two supported shells. It configures each of them that is available on your PATH, regardless of the shell you are using:

Bash: ~/.bashrc, and the first existing file of ~/.bash_profile, ~/.bash_login, and ~/.profile. If none of them exists, JetBrains Central CLI creates ~/.bash_profile.
Zsh: .zshenv in the directory set by the ZDOTDIR environment variable, or in your home directory when ZDOTDIR is not set. If ZDOTDIR is set, it must be an absolute path, one that starts with /.

In each startup file, JetBrains Central CLI adds only the following marked block and leaves the rest of the file as it was, so no backup is saved:

                        # >>> jetbrains-central-copilot >>>
                        [ ! -r "$HOME/.jetbrains-central/agents/copilot/configure-env.sh" ] || . "$HOME/.jetbrains-central/agents/copilot/configure-env.sh"
                        # <<< jetbrains-central-copilot <<<
                    

On Windows, there is no environment file. The variables are written to your user environment (HKCU\Environment).

On all platforms, JetBrains Central CLI also adds a session-start hook that starts the proxy. It is written to ~/.copilot/hooks/jetbrains-central.json, or to $COPILOT_HOME/hooks/ when COPILOT_HOME is set.

Keep the following in mind:

Terminals that were already open don't see the new variables. Open a new terminal after connecting or disconnecting Copilot.
If Copilot's providers.json file defines any providers or models, Copilot uses that file instead of the variables that JetBrains Central CLI sets (see GitHub's documentation).
Disconnect Copilot before you change COPILOT_HOME or ZDOTDIR. JetBrains Central CLI looks for its settings only in the current locations, so settings in the old location are not removed automatically.
Models come from the built-in list of JetBrains Central CLI. Your organization's model settings in JetBrains Central don't apply to Copilot yet.
The model ID is not checked when you connect. An unknown ID shows up as an error inside Copilot when it sends a request.
Thinking effort is never stored. Copilot uses its own default for the model unless you pass Copilot's --effort flag.

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. To reconnect them all, run central repair. GitHub Copilot keeps the provider and model you selected.

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. The JetBrains Central CLI plugin is unregistered as well, so the agent no longer uses the MCP servers that your organization provides. 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.

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.

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

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.

                        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.

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.

                        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.

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.

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

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

central remove pi

Removal deletes the environment file and the session-start hook, and removes the marked block from your shell startup files — including those of a shell that is no longer on your PATH. The rest of each startup file is not changed. Open a new terminal afterwards: terminals that are already open keep the old environment.

On Windows, removal clears the Copilot provider variables that JetBrains Central CLI set in your user environment. It deletes COPILOT_PROVIDER_API_KEY only if it still holds the placeholder key that JetBrains Central CLI wrote. Values from before you connected Copilot are not restored, because JetBrains Central CLI did not save them.

central remove copilot

A governance refresh removes an agent automatically when it leaves your organization's allow-list (see Agents). 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).

16 October 2026