Local AI Clients

Local clients are AI tools that run on your own computer — for example Claude Code, Codex, Gemini CLI, Cursor or VS Code. CodeNOW lets you configure them so that all their traffic — calls to language models and to MCP servers — goes through your account's Agent Gateway. Because of that:

• every call is recorded by the gateway and visible in its Logs and Analytics,
• the gateway authenticates you with your own CodeNOW identity and applies its access rules,
• MCP servers, including the CodeNOW MCP server, are reached with your own CodeNOW permissions.

Which clients are offered, and how exactly they are configured, is decided by your account administrators — see Manage Client Profiles.

Prerequisites

• An Agent Gateway is installed on one of your account's data planes.
• An administrator has created and enabled at least one client profile.
• The client itself is installed on your computer (each profile links to its download page).

If the account's Agent Gateway is not ready, the setup guide shows a banner and all downloads are disabled:

Banner	Meaning
Agent Gateway is not installed for this account. Local clients can be set up once an account admin enables it in Account settings.	No Agent Gateway is installed for the account.
Agent Gateway is turned off for this account. Local clients can be set up once an account admin turns it on in Account settings.	The Agent Gateway is disabled in Account Settings.
Agent Gateway has no externally reachable URL yet, so local clients cannot connect to it.	The gateway is installed but cannot be reached from outside yet.

In all these cases, ask your account administrator.

Choosing a client

Open AI › Local clients in the main navigation. The Local clients page is available to every user of the account.

Each enabled client profile is shown as a card with its icon, name and description, its version and the date of its last change. Click Set up on a card to open its setup guide.

If no profile is enabled, the page shows No local clients are available yet. Users who can manage profiles also see a Manage profiles button, which opens the profile management.

Following the setup guide

The setup guide is a step-by-step wizard prepared for you:

1. Select your operating system with the macOS / Linux / Windows switch (only the systems the profile supports are offered). Steps, commands and files that apply to other systems are hidden.
2. Go through the steps in order. A step may contain instructions, a command to copy (Copy) and run, or a link (for example to download the client itself).
3. Download the files the guide offers. Each file shows where to put it on your computer (its target path) and whether it must be made executable. Download each file with Download, or all of them at once with Download all (.zip).
4. Sign in — see Signing in.
5. Verify the setup — the last section, Verify the setup, tells you how to check that the client works through the gateway.

Downloaded files are rendered for you: values such as the gateway URL, the sign-in client, the account and your username, and the gateway's MCP endpoints are already filled in. Files can be downloaded only from the portal, while you are signed in. Downloads are not tracked.

note

When an administrator changes a profile, its version increases. If the version shown on the card is newer than the one you set up, download the files again.

Signing in

CodeNOW guarantees that the downloaded files never contain a token or password. You sign in with your own CodeNOW account when the client first needs the gateway.

How exactly the sign-in works is part of your organization's profile — its administrators write the sign-in scripts and steps. Follow the steps of your organization's profile; they also tell you whether a token is kept on your computer and how to sign out.

Sign-in to the gateway uses the gateway's sign-in client <account>-<dataplane>-agent-gateway, which supports the device authorization flow for command-line tools (and PKCE for browser sign-in). Typically:

1. The script prints a link and a short code (or opens the link for you).
2. You open the link in a browser, sign in to CodeNOW and confirm the code.
3. The script receives a token and passes it to the client.

For details of the flow see Agent Gateway — CLIs and agents without a browser.

Verifying the setup

Run the verification described in the last step of the guide (typically a command that calls a model or lists MCP tools through the gateway). If it succeeds, your calls appear in the gateway's Logs, provided you have access to them (see Agent Gateway — Logs and Analytics).

Troubleshooting

Problem	What to do
No local clients are available yet.	No profile is enabled for the account — ask your account administrator.
A banner about the Agent Gateway, downloads are disabled	The gateway is not ready — see Prerequisites.
Your operating system is not offered	The profile does not support it — ask the administrator to extend it.
Sign-in fails or the token is rejected	Make sure you sign in with your CodeNOW account of this account; repeat the sign-in.
An MCP server is missing	MCP servers are reached through the gateway's MCP endpoints; a server your organization registers itself appears on the external endpoint. Ask your account administrator whether it is registered.

| A download fails with Agent Gateway state is temporarily unavailable; try again later. | The gateway state cannot be checked right now — try again later. | | Local AI clients are not configured on this platform (OIDC issuer missing). | The platform operator has not finished the sign-in configuration for local clients. You cannot fix this yourself — contact CodeNOW support or your platform administrator. |

If the gateway's state changes while the guide is open, a download can also fail with one of the messages from Prerequisites.