Manage Client Profiles
A client profile describes how to configure one local AI client — for example Claude Code or Codex — so that it sends all model and MCP traffic through the account's Agent Gateway. From the profile, CodeNOW renders a personal setup guide and configuration files for each user.
The profile format is generic: it does not assume any particular client. You describe the steps, the files and how to verify the result.
Who can manage profiles
Profiles can be managed by:
- account Owners and Admins, and
- users with the Admin level on the Agent Gateway.
They are managed on the Local clients card, which you can reach in two ways:
- Account Settings › AGENT GATEWAY — the Local clients card below the Agent Gateway card. Account Settings are available only to account Owners and Admins.
- AI › Local clients › Manage profiles — the Manage profiles button is shown only to users who can manage profiles. Agent Gateway admins who are not account admins use this way.
Both lead to the same card and the same editor.
Creating, changing, enabling, disabling and deleting a profile is recorded in the account's activity log. Downloads by users are not recorded.
Creating a profile
On the Local clients card, click Create profile. The editor has two tabs, Editor and Preview. On the Editor tab, fill in:
| Field | Description |
|---|---|
| Name | The client's name shown to users, e.g. Claude Code. |
| Description | A short text shown on the card. |
| Link | The client's home or download page. |
| Icon | One of the built-in icons: Claude Code, Codex, Gemini CLI, Cursor, VS Code, or a generic icon. Custom images cannot be uploaded. |
| Operating systems | macOS, Linux and/or Windows. Users choose among these in the guide. |
Then define the Steps, Files, Verification and Variables described below, and click Save (or Cancel to discard the changes). The editor also shows a read-only list of the available platform variables.
If the account has no profile yet, the card shows No local client profiles yet. Create one to give users a step-by-step setup guide.
Steps
Steps form the setup guide, shown to users in the order you set. Each step has:
- a title,
- a text in Markdown (instructions, links — for example to download the client binary),
- an optional command that users can copy,
- optionally the operating system it applies to; without it, the step is shown for all systems of the profile.
Binary files (installers, executables) cannot be attached to a profile — link to them from a step.
Files
Files are text files rendered for each user from a template, for example a client configuration (JSON, TOML, YAML) or a sign-in script. Each file has:
| Field | Description |
|---|---|
| Name | The file name offered for download. |
| Target path | Where the user should put the file, e.g. ~/.claude/settings.json. It can contain variables. |
| Template | The file content with variables. |
| Format | Auto (from file extension) (default), JSON, TOML, YAML, Shell, PowerShell or Text. It controls escaping; a chosen format overrides the file extension. |
| Executable | Mark scripts that must be made executable. The flag is kept in the ZIP archive. |
| Operating system | Optional; without it, the file is offered for all systems of the profile. |
Users can download each file separately or all files as a ZIP archive.
Files must not contain tokens, passwords or other secrets — and no variable ever carries a token. To authenticate, provide a script that signs the user in with the device authorization flow and passes the obtained token to the client. Use the oidcIssuer and oidcClientId variables for it.
Sign-in scripts are yours: CodeNOW does not provide them. Your profile decides whether a script keeps a token on the user's computer and how users sign out, so describe both in the steps.
Verification
Describe how users check that the setup works — a Markdown text and an optional command, e.g. a call that lists MCP tools through the gateway. It is shown as the last step of the guide.
Variables
File templates, target paths, step texts and commands, and the verification can use variables. They are filled in for each user when the guide is shown or the files are downloaded.
Platform variables
| Variable | Value |
|---|---|
gatewayUrl | The Agent Gateway URL, https://agent-gateway.<data plane host> (without a trailing slash) |
oidcIssuer | The CodeNOW sign-in issuer (realm URL) |
oidcClientId | The gateway's sign-in client, <account>-<dataplane>-agent-gateway (device grant and PKCE enabled) |
accountId | The account ID |
accountName | The account name |
username | The user's username |
os | The operating system selected in the guide: macos, linux or windows |
mcpCodenowUrl | The gateway's endpoint for the MCP servers managed by CodeNOW, {{gatewayUrl}}/mcp/codenow (see MCP endpoints) |
mcpExternalUrl | The gateway's endpoint for the MCP servers your organization registers directly in its Agent Gateway, {{gatewayUrl}}/mcp/external. It is always filled in, even if none are registered. |
Custom variables
You can define your own variables on the profile as key and value pairs — for example model names or model endpoints, which CodeNOW does not provide as platform variables yet. A key starts with a letter, contains only letters, digits and _, has at most 50 characters and cannot be the name of a platform variable. Custom variables are used in the same way as platform variables.
Template syntax
Templates use a small subset of Mustache. A short summary is also shown in the editor under Files.
| Syntax | Result |
|---|---|
{{gatewayUrl}} | The value, escaped for the format of the file |
{{{gatewayUrl}}} or {{&gatewayUrl}} | The raw value, without escaping |
{{#anyVariable}}…{{/anyVariable}} | Rendered when the variable is not empty ({{^anyVariable}}…{{/anyVariable}} when it is empty) |
{{! comment }} | Removed from the output |
Example — .mcp.json for Claude Code with both MCP endpoints of the gateway:
{
"mcpServers": {
"codenow": { "type": "http", "url": "{{mcpCodenowUrl}}" },
"external": { "type": "http", "url": "{{mcpExternalUrl}}" }
}
}
Escaping
Values are escaped so that they cannot break the file. Escaping assumes that you put the variable inside a string literal of the target format — write "{{gatewayUrl}}" in JSON, TOML and YAML, and '{{gatewayUrl}}' in shell and PowerShell scripts.
| Format | Escaping |
|---|---|
| JSON, TOML, YAML | As in a double-quoted string (", \ and control characters) |
| Shell | As in a single-quoted string (' becomes '\'') |
| PowerShell | As in a single-quoted string (' becomes '') |
| Text | None |
The format of a file is its Format setting or, with Auto (from file extension), follows from the file name: .json / .jsonc → JSON, .toml → TOML, .yaml / .yml → YAML, .sh / .bash / .zsh → Shell, .ps1 → PowerShell, anything else → Text. Step texts, the verification text and target paths are Text; commands are PowerShell in Windows steps and Shell otherwise.
Validation
Templates are checked when you save the profile, not when a user downloads the files. A profile that uses an unknown variable or has a syntax error cannot be saved; the message names the field and the line, for example:
- Unknown variable 'foo' in files[0].template (line 3)
- Unclosed section 'model' in steps[0].markdown (line 1)
The field is one of files[i].template, files[i].targetPath, steps[i].markdown, steps[i].command or verification.markdown (counted from 0).
Limits
| Item | Limit |
|---|---|
| Steps | 50 |
| Files | 20 |
| File template | 64 KiB |
| Step text | 16 KiB |
| Command | 4 KiB |
| Custom variables | 50 |
Preview
The Preview tab of the editor shows the setup guide exactly as users will see it, rendered from the current, unsaved state of the profile and filled in with your own values (your username, the account, its gateway and MCP endpoints). The operating system switch offers the systems checked on the profile and shows only the steps and files for the selected system. Each file can be downloaded with its Download button, so you can test the whole setup before saving and enabling the profile. Download all (.zip) is not available in the preview — the ZIP archive is built only for saved profiles and is offered to users in AI › Local clients.
The preview works even when the account has no usable Agent Gateway: it then shows the placeholder <agent-gateway-not-installed> instead of gatewayUrl, mcpCodenowUrl and mcpExternalUrl and reports the gateway status.
Changing, disabling and deleting a profile
Every saved change increases the profile's version and updates the last change date shown to users. Users who already set up the client are not notified; they see the new version on the card and can download the files again.
Each profile on the Local clients card has an Enabled switch and the Export, Edit and Delete actions. Only enabled profiles are shown to users; disabling a profile hides it. Delete removes the profile permanently.
If someone else saved the profile after you opened it, saving fails with This profile was changed by someone else since you opened it. Click Reload to load the current version, then apply your changes again.
Exporting and importing a profile
- Export on a profile downloads it as a JSON file named
<name>.json. - Import profile in the header of the Local clients card creates a new profile from such a file. The imported profile is created disabled — check it in the preview, then enable it.
Use export and import to copy a profile to another account or to keep a backup of it.
Not available yet
- Ready-made starter profiles (for example for Claude Code or Codex).
- One-command installation (
curl … | sh). - Registering models in the gateway from the portal.
- Different profiles for different teams.