Skip to main content

Connect Claude Code

Configure Claude Code gateway routing, find your settings file, select Gemini models, and verify inference and tools.

On this page

Use Claude Code in your terminal with models and tools provided by your organization's Dynapps gateway. This guide covers macOS, Linux, and native Windows. WSL remains an optional Linux setup.

For Cowork in Claude Desktop, use Connect Cowork. For native Windows, follow the PowerShell walkthrough, including its required bridge build, before using the launch modes below.

Before you start

  1. Install Claude Code using your organization's approved method or Anthropic's setup instructions. Confirm claude --version works.
  2. Install and sign in to the bridge, using your gateway's explicit HTTPS address and trusted manifest key.
  3. Keep the bridge app or proxy service running.

On macOS, define the CLI alias in each terminal where you run bridge commands:

alias dynapps-bridge=/Applications/DynappsBridge.app/Contents/MacOS/dynapps-bridge

1. Create the Claude Code configuration

On macOS or Linux, run:

dynapps-bridge sync
dynapps-bridge install --host claude-code
dynapps-bridge sync

On Windows PowerShell, use the verified executable path from the Windows guide:

& $Bridge sync
& $Bridge install --host claude-code
& $Bridge sync

Enrolment creates a standalone claude-code-settings.json file in the bridge configuration directory. Unix builds create a shell credential helper there; Windows settings invoke the installed bridge executable through PowerShell. It also merges gateway routing into Claude Code's persistent settings: the managed settings file when writable, otherwise your user settings file.

This step changes routing for subsequent Claude Code sessions. Close existing sessions before switching modes. It does not install a provider API key: the helper supplies a machine-local bridge credential.

Choose always-on routing or per-session routing below. On an IT-managed device, confirm that your organization allows you to change routing before removing a profile.

2. Choose how to launch

Always-on routing

Keep the configuration from step 1 and start Claude Code normally:

claude

To choose a gateway model explicitly:

claude --model gemini-3.8-flash

The example requires that your gateway and account have access to that exact model ID. Your administrator can provide the available IDs.

Per-session routing

First remove the bridge's persistent Claude Code routing. This keeps the generated standalone settings file for explicit launches:

dynapps-bridge uninstall --host claude-code
dynapps-bridge sync

Then pass that file when starting a gateway session.

macOS:

claude --settings "$HOME/Library/Application Support/dynapps/claude-code-settings.json" \
  --model gemini-3.8-flash

Linux or WSL:

claude --settings "${XDG_CONFIG_HOME:-$HOME/.config}/dynapps/claude-code-settings.json" \
  --model gemini-3.8-flash

Windows PowerShell:

& $Bridge uninstall --host claude-code
& $Bridge sync
claude --settings "$env:APPDATA\dynapps\claude-code-settings.json" --model gemini-3.8-flash

With a custom absolute XDG_CONFIG_HOME, substitute the actual file path reported by the bridge. Keep paths quoted, especially those containing spaces.

A plain claude launch no longer gets routing from the bridge's removed persistent profile. Other environment variables, project settings, and organization policies may still affect it. Per-session routing does not remove synchronized plugins or isolate you from managed policy.

Find your installed settings file

The file is generated by step 1, not by downloading the bridge or installing Claude Code alone. It is separate from your personal ~/.claude/settings.json.

On macOS, open Finder, press Command–Shift–G, and enter:

~/Library/Application Support/dynapps/

Or check it in Terminal without printing its contents:

ls -l "$HOME/Library/Application Support/dynapps/claude-code-settings.json"

On Linux or WSL:

ls -l "${XDG_CONFIG_HOME:-$HOME/.config}/dynapps/claude-code-settings.json"

On native Windows PowerShell:

Get-Item -LiteralPath "$env:APPDATA\dynapps\claude-code-settings.json"

If it is missing, check dynapps-bridge status for the configured directory, then repeat step 1 and reselect your routing mode. Run setup and Claude Code as the same OS user. Do not copy the settings or helper to another computer: their local paths and credentials belong to this installation.

Claude Code's personal configuration directory can also be customized through CLAUDE_CONFIG_DIR; that is distinct from the bridge's XDG_CONFIG_HOME. Bridge enrolment targets the default user settings path when it cannot write managed settings. If you use a custom Claude Code directory, use the explicit --settings launch and verify routing rather than assuming enrolment changed that directory. See Claude Code settings and precedence.

Select Gemini or another gateway model

Use an exact model ID provided by your administrator with --model. For example, if enabled:

claude --model gemini-3.8-flash
claude --model vertex-gemini-3.8-flash

For per-session routing, include the --settings argument from the previous section in either command.

The interactive /model menu is a convenience, not a complete inventory of gateway access. If a model is absent, run dynapps-bridge sync, restart Claude Code, and select its exact ID at launch. A missing picker entry alone does not mean the gateway cannot serve that model.

Do not append context-window suffixes or set a larger context limit unless your administrator confirms support for that model and route. Start a fresh session when checking a different provider so previous conversation state does not complicate the test. See Claude Code model configuration for the client-side controls.

What happens automatically after sign-in

Signing in to the bridge — interactively, with a connect code, or through the installer's --pat — sets the whole reporting chain up without a further command from you:

  1. A device credential is issued at login. The bridge registers this installation with the gateway and stores the credential in its own metadata directory, mode 0600. Every hook event and gateway request it makes from then on is attributed to that device. The bridge only enrols over an https:// gateway or a loopback http://localhost / http://127.0.0.1 address, because the credential is a bearer token.
  2. Skills are granted by marketplace reach. When the bridge fetches its manifest, the gateway grants you every published skill that any marketplace you can reach contains. There is no per-user grant to request.
  3. The latest skill revision is published each minute. An inventory job publishes the newest configured revision of every skill and keeps the history, so dynapps-bridge sync always brings the current version and earlier revisions remain attributable in reports.
  4. The device is visible to administrators. It appears on the Devices page with the account it belongs to, and can be revoked there.

Every Claude Code hook the bridge installs sends an x-systemprompt-host: claude-code header, so the gateway records which client produced each event; the same header stamps requests from other enrolled clients with their own names.

For operators: no manual device-enroll, publish, or grant step is needed any more. Login enrols the device, the manifest fetch grants skills, and the inventory job publishes revisions. dynapps-bridge device-enroll --token-file <path> remains as a manual override for a device credential an administrator issued out of band.

Verify model routing and tools separately

  1. Run dynapps-bridge whoami and dynapps-bridge doctor. Confirm your account and resolve relevant proxy or authentication failures.
  2. Launch Claude Code using your chosen mode and ask: Reply with DYNAPPS_CONNECTED. Do not use tools.
  3. Find that request in the gateway's History, or have your administrator confirm its time, account, and model. This is the routing check.
  4. Run claude plugin list to inspect installed plugins. In a new session, ask Claude Code to use a specific read-only tool that your organization provides. Confirm both its result and the corresponding gateway activity.

A billing label in Claude Code is not proof of which gateway handled a request. Likewise, a model response does not prove that MCP tools or plugins work.

Troubleshooting

Claude Code asks for a different account or ignores routing. Check for conflicting environment variables such as ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or provider-selection flags in your shell configuration. Do not print their values into support logs. Settings and organization policies can take precedence; ask IT before changing managed configuration.

Connection refused. Start the bridge app or proxy service. Repeat enrolment if the generated profile points at an obsolete local port, then reselect your routing mode.

Model not found or not allowed. Confirm the exact model ID and account entitlement with your administrator. Do not infer availability from the picker alone.

Tools are missing. Run dynapps-bridge sync, resolve its errors, and restart Claude Code. Check plugin installation and tool authorization separately from inference.

Disconnect Claude Code

dynapps-bridge uninstall --host claude-code

In PowerShell, use & $Bridge uninstall --host claude-code.

This removes bridge-managed persistent routing for Claude Code. It leaves the standalone settings file and does not sign you out of the bridge or disconnect Cowork. Stop passing the standalone file if you no longer want gateway sessions.