Setup guides

Connect your tools to Zrelay

No universal prerequisites and no configuration maze. Pick the app you use and see only the instructions you need.

Command line

Terminal

Native coding agents that run from your shell.

CX OpenAI

Codex

Install the native CLI, add Zrelay as a custom provider, and use your environment key.

LinuxmacOSWindows

Set up Codex

CC Anthropic

Claude Code

Use the native terminal installer and a permanent Zrelay configuration.

LinuxmacOSWindows

Set up Claude Code

GB xAI

Grok Build

Install the CLI, add your API key, and configure Chat Completions.

LinuxmacOSWindows

Set up Grok Build

OC Terminal TUI

OpenCode

Connect GPT, Grok, or Claude from one global JSON provider configuration.

GPTClaudeGrok

Set up OpenCode

Visual apps

Desktop & editors

Use Zrelay from the editor or desktop app you already know.

CU Code editor

Cursor

Run Codex or Claude Code as a native extension, with a lighter API override alternative.

GPTClaudeAll systems

Set up Cursor

VS Code editor

VS Code

Use Codex or Claude Code in native panels, or add GPT, Claude, and Grok to Copilot Chat.

GPTClaudeGrok

Set up VS Code

AG VS Code fork

Antigravity

Connect GPT or Claude through native coding extensions; Antigravity itself is Gemini-only.

GPTClaudeAll systems

Set up Antigravity

ZC Desktop app

ZCode

Skip the account screen and add Zrelay as a custom model provider from Settings.

GPTClaudeGrok

Set up ZCode

CA Desktop app

Claude Desktop

Connect the desktop app through its local third-party inference gateway.

macOSWindowsAvailability varies

Set up Claude Desktop

Building directly with the API? Endpoints, authentication, curl examples, SDK usage and GPT Image setup live in the API documentation.

Open API docs

OpenAIResponses API

Set up Codex

Install the native CLI, add the Zrelay provider, then store your key. Node.js is not required.

Your system

Install Codex

Run the official installer, then open a new terminal window.

Terminal

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Add the Zrelay configuration

Create the file shown below. It keeps Zrelay separate from your normal Codex login.

Linux / macOS~/.codex/config.toml Windows%USERPROFILE%\.codex\config.toml

config.toml

model_provider = "zrelay"
model = "gpt-5.6-terra"
model_reasoning_effort = "xhigh"

[model_providers.zrelay]
name = "Zrelay"
base_url = "https://api.zrelay.net/v1"
wire_api = "responses"
env_key = "ZRELAY_API_KEY"
requires_openai_auth = false
supports_websockets = false

Save your API key

Use a persistent environment variable so Codex can read the key without changing its own login credentials.

For Bash:

Bash

echo 'export ZRELAY_API_KEY="zr_live_YOUR_API_KEY"' >> ~/.bashrc
source ~/.bashrc
echo "$ZRELAY_API_KEY"

For Zsh (the default shell on macOS):

Zsh

echo 'export ZRELAY_API_KEY="zr_live_YOUR_API_KEY"' >> ~/.zshrc
source ~/.zshrc
echo "$ZRELAY_API_KEY"

For a temporary test in the current shell only: export ZRELAY_API_KEY="zr_live_YOUR_API_KEY". It disappears when the shell closes.

Run a real request

After saving the key, open a new terminal when required and make a request through Zrelay.

Terminal

codex exec "Respond exactly with: ZRELAY_OK"

Expected output: ZRELAY_OK. If Codex or an editor extension keeps an old process alive, restart it before trying again. On Windows: Get-Process *codex* -ErrorAction SilentlyContinue | Stop-Process -Force.

Optional troubleshooting: Codex daemon If codex exec works but interactive codex reports Missing environment variable: ZRELAY_API_KEY, Codex may be reusing a daemon started before the environment variable was available.

Test without the daemon

codex --no-daemon

If Zrelay works this way, disable auto-start and stop the existing daemon, then start Codex normally:

Reset the daemon

codex features disable daemon_auto_start
codex app-server daemon stop
pkill -f 'app-server daemon pid-update-loop' || true
codex

Verify the daemon feature state with:

Check daemon state

codex features list | grep daemon

This concerns how Codex inherits environment variables; it does not indicate a problem with your Zrelay API key or provider configuration.

AnthropicMessages API

Set up Claude Code

The native installer needs no Node.js and keeps itself updated. A permanent settings file is the simplest way to connect it to Zrelay.

Your system

Install Claude Code

Run the native installer, then open a new terminal window.

Terminal

curl -fsSL https://claude.ai/install.sh | bash

Prefer npm?

npm installation requires Node.js 18 or newer.

npm install -g @anthropic-ai/claude-code

Connect Claude Code to Zrelay

Create the settings file for your system and replace zr_live_YOUR_API_KEY with your Zrelay key.

File~/.claude/settings.json

settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.zrelay.net",
    "ANTHROPIC_AUTH_TOKEN": "zr_live_YOUR_API_KEY",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

Use temporary environment variables instead

Terminal

export ANTHROPIC_BASE_URL=https://api.zrelay.net
export ANTHROPIC_AUTH_TOKEN=zr_live_YOUR_API_KEY
claude

Add the two exports to ~/.zshrc or ~/.bashrc to keep them between sessions.

Verify and launch

Check the installed version, then start Claude Code normally.

Terminal

claude --version
claude

Terminal TUIJSON config

Set up OpenCode

Add Zrelay as a provider in OpenCode's global JSON config. GPT and Grok share one OpenAI-compatible block; Claude uses the native Anthropic provider.

Choose a model family

One provider block

GPT and Grok

Both model families use the OpenAI-compatible provider in OpenCode.

Open the global config

Create or edit this file. OpenCode also accepts the .jsonc extension if you want comments.

File~/.config/opencode/opencode.json

Add the Zrelay provider

Replace zr_live_YOUR_API_KEY with your Zrelay key. The model IDs must match the names you want to select in OpenCode.

opencode.json

{
  "provider": {
    "zrelay": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Zrelay",
      "options": {
        "baseURL": "https://api.zrelay.net/v1",
        "apiKey": "zr_live_YOUR_API_KEY"
      },
      "models": {
        "gpt-5.5": { "name": "GPT-5.5" },
        "grok-4.5": { "name": "Grok 4.5" }
      }
    }
  },
  "$schema": "https://opencode.ai/config.json"
}

Restart and choose a model

Restart OpenCode, then select a Zrelay GPT or Grok model from the model picker. They use the same provider block.

VS Code forkGPT + Claude

Set up Antigravity

Antigravity ships with Gemini models and does not offer a native bring-your-own-key option. Because it is a VS Code fork, you can still use GPT or Claude through their native coding extensions.

There is no Antigravity API key or model override to configure. Install the extension for the model family you want, then configure that extension in your home directory.

Choose a model family

Recommended

Codex extension

Codex runs in its own Antigravity panel using OpenAI's native agent.

Install the Codex extension

Open Extensions with Cmd/Ctrl + Shift + X, search for OpenAI Codex, and click Install.

Point Codex at Zrelay

Create this file in your home directory. Edit it in Antigravity instead of a basic text editor.

Linux / macOS~/.codex/config.toml Windows%USERPROFILE%\.codex\config.toml

config.toml

model_provider = "zrelay"
model = "gpt-5.6-terra"
model_reasoning_effort = "xhigh"

[model_providers.zrelay]
name = "Zrelay"
base_url = "https://api.zrelay.net/v1"
wire_api = "responses"
env_key = "ZRELAY_API_KEY"
requires_openai_auth = false
supports_websockets = false

Reload and start coding

Reload Antigravity, open the Codex panel from the sidebar, and start a session.

Code editorGPT + Claude + Grok

Set up VS Code

Choose a model family. Native extensions are the simplest route for agent work; Copilot Custom Endpoint is available when you want models directly in Chat.

Choose a model family

Recommended

Codex extension

Codex runs in its own VS Code panel using OpenAI's native agent.

Install the Codex extension

Open Extensions with Cmd/Ctrl + Shift + X, search for OpenAI Codex, and click Install.

Point Codex at Zrelay

Create this file in your home directory. Edit it in VS Code instead of a basic text editor.

Linux / macOS~/.codex/config.toml Windows%USERPROFILE%\.codex\config.toml

config.toml

model_provider = "zrelay"
model = "gpt-5.6-terra"
model_reasoning_effort = "xhigh"

[model_providers.zrelay]
name = "Zrelay"
base_url = "https://api.zrelay.net/v1"
wire_api = "responses"
env_key = "ZRELAY_API_KEY"
requires_openai_auth = false
supports_websockets = false

Reload and start coding

Reload VS Code, open the Codex panel from the sidebar, and start a session.

Alternative: GitHub Copilot Custom Endpoint

Add GPT models to Copilot Chat through VS Code's built-in Custom Endpoint flow.

Open Manage Language ModelsIn the Chat view, open the model picker, click the gear icon, and choose Manage Language Models. You can also run Chat: Manage Language Models.
Add a Custom EndpointChoose Add Models → Custom Endpoint, enter a group name and display name, add your Zrelay key, and choose Responses as the API type.
Edit chatLanguageModels.jsonReplace the generated entry with the configuration below, then save the file.

chatLanguageModels.json

[
  {
    "name": "Zrelay (GPT)",
    "vendor": "customendpoint",
    "apiKey": "zr_live_YOUR_API_KEY",
    "apiType": "responses",
    "models": [
      {
        "id": "gpt-5.5",
        "name": "GPT-5.5",
        "url": "https://api.zrelay.net/v1/responses",
        "toolCalling": true,
        "vision": false,
        "maxInputTokens": 272000,
        "maxOutputTokens": 128000
      }
    ]
  }
]

Keep the key local and do not commit chatLanguageModels.json to a repository.

Recommended

Claude Code extension

Claude Code runs in its own VS Code panel using Anthropic's native agent.

Install the Claude Code extension

Open Extensions with Cmd/Ctrl + Shift + X, search for Claude Code, and click Install. The extension manages the runtime for you.

Point Claude Code at Zrelay

Create or edit the settings file for your system and replace zr_live_YOUR_API_KEY with your Zrelay key.

Linux / macOS~/.claude/settings.json Windows%USERPROFILE%\.claude\settings.json

settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.zrelay.net",
    "ANTHROPIC_AUTH_TOKEN": "zr_live_YOUR_API_KEY",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

Reload and choose a model

Reload VS Code, open the Claude Code panel from the sidebar, and select a model such as claude-sonnet-5.

Alternative: GitHub Copilot Custom Endpoint

Add Claude models to Copilot Chat through the Claude-compatible Messages API through Zrelay.

Open Manage Language ModelsIn the Chat view, open the model picker, click the gear icon, and choose Manage Language Models. You can also run Chat: Manage Language Models.
Add a Custom EndpointChoose Add Models → Custom Endpoint, enter a group name and display name, add your Zrelay key, and choose Messages as the API type.
Edit chatLanguageModels.jsonReplace the generated entry with the configuration below, then save the file.

chatLanguageModels.json

[
  {
    "name": "Zrelay (Claude)",
    "vendor": "customendpoint",
    "apiKey": "zr_live_YOUR_API_KEY",
    "apiType": "messages",
    "models": [
      {
        "id": "claude-sonnet-5",
        "name": "Claude Sonnet 5",
        "url": "https://api.zrelay.net/v1/messages",
        "toolCalling": true,
        "vision": true,
        "maxInputTokens": 1000000,
        "maxOutputTokens": 128000
      }
    ]
  }
]

Keep the key local and do not commit chatLanguageModels.json to a repository.

Code editorGPT + Claude

Set up Cursor

Choose the model family you want to use. The native Codex and Claude Code extensions are recommended because their agent tools work without a format adapter.

Choose a model family

Recommended

Codex extension

Codex runs in its own Cursor panel using OpenAI's native agent.

Install the Codex extension

Open Extensions with Cmd/Ctrl + Shift + X, search for OpenAI Codex, and click Install.

Point Codex at Zrelay

Create this file in your home directory. You can edit it directly in Cursor.

Linux / macOS~/.codex/config.toml Windows%USERPROFILE%\.codex\config.toml

config.toml

model_provider = "zrelay"
model = "gpt-5.6-terra"
model_reasoning_effort = "xhigh"

[model_providers.zrelay]
name = "Zrelay"
base_url = "https://api.zrelay.net/v1"
wire_api = "responses"
env_key = "ZRELAY_API_KEY"
requires_openai_auth = false
supports_websockets = false

Reload Cursor

Reload the editor, open the Codex panel from the sidebar, and start a session.

Alternative: Cursor's native OpenAI override

Plain chat works, but Agent mode may be unreliable. Cursor can send a non-standard tool format. Zrelay serves the standard OpenAI endpoint, so tool calls are not guaranteed through this route.

Open model settingsOpen Cursor Settings → Models, then expand API Keys.
Add your key and endpointEnable OpenAI API Key, paste your Zrelay key, enable Override OpenAI Base URL, and use the endpoint below. Then click Verify.

Base URLhttps://api.zrelay.net/v1

Add a GPT modelIn the Models list, click + Add model and enter a model id such as gpt-5.5.

Grok can use the same OpenAI-compatible base URL in Cursor, but it is served through Chat Completions. Use grok-4.5 as the model id; do not switch this route to the Responses API.

Recommended

Claude Code extension

Claude Code runs in its own Cursor panel using Anthropic's native agent.

Install the Claude Code extension

Open Extensions with Cmd/Ctrl + Shift + X, search for Claude Code, and click Install. The extension manages its runtime for you.

Point Claude Code at Zrelay

Create or edit the settings file for your system and replace zr_live_YOUR_API_KEY with your Zrelay key.

Linux / macOS~/.claude/settings.json Windows%USERPROFILE%\.claude\settings.json

settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.zrelay.net",
    "ANTHROPIC_AUTH_TOKEN": "zr_live_YOUR_API_KEY",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

Reload and choose a model

Reload Cursor, open the Claude Code panel from the sidebar, and select a model such as claude-sonnet-5.

Alternative: Cursor's native OpenAI override

Do not enable Cursor's native Anthropic API Key. It enables an Anthropic base URL override that conflicts with this setup. Configure Claude through the OpenAI API Key slot instead.

Plain chat works, but Agent mode may be unreliable. The same tool-calling limitation as the GPT override applies.

Set the OpenAI-compatible endpointIn Cursor Settings → Models → API Keys, enable OpenAI API Key and paste your Zrelay key. Enable Override OpenAI Base URL, enter the endpoint below, and click Verify.

Base URLhttps://api.zrelay.net/v1

Add a Claude modelIn the Models list, click + Add model and enter a model id such as claude-sonnet-5.

Desktop appCustom provider

Set up ZCode

Use ZCode without connecting a Z.ai account. Skip the login screen, add Zrelay from Model settings, then choose the API format that matches your model.

You do not need a Z.ai account for this setup. Use the API key route, skip the account prompt, and configure Zrelay locally from the app settings.

Open ZCode without signing in

Launch ZCode, choose Use API Key, then select Skip for now to pass the login panel.

Open Model settings

Click the gear icon. Under Basics, open Model settings, then click Add provider.

Add the Zrelay provider

Fill the provider form with these values. Use the base URL only; the API format determines the final route.

NameZrelay

Base URLhttps://api.zrelay.net/v1

API keyzr_live_YOUR_API_KEY

Choose the API format

Select the format supported by the model family you want to use:

GPTResponses (/responses)

ClaudeAnthropic messages (/v1/messages)

GrokChat completions (/chat/completions)

Use one provider per API format when mixing families. Create separate ZCode providers if you want GPT, Claude, and Grok at the same time, because each provider entry has one API format.

Add models and start coding

In Model list, add the exact model IDs you want, such as gpt-5.5, claude-sonnet-5, or grok-4.5. You can also leave the list blank and add models later.

Save the provider, return to the model picker, and select your Zrelay model.

AnthropicWindows & macOS

Set up Claude Desktop

Connect the desktop app through its local Anthropic-compatible gateway option.

Availability depends on your Claude app version. This option is behind Developer Mode and is not documented by Anthropic. If it does not appear in your build, use Claude Code instead.

Enable Developer Mode

Launch Claude Desktop without signing in. Open Help → Troubleshooting → Enable Developer Mode. A Developer menu will appear in the menu bar.

Open Third-Party Inference

From the menu bar, choose Developer → Configure Third-Party Inference…

Enter the gateway settings

Select Gateway (Anthropic-compatible), then enter these values and click Apply locally.

Gateway base URLhttps://api.zrelay.net

Gateway API keyzr_live_YOUR_API_KEY

Gateway auth schemebearer

Restart and choose a model

Fully quit and reopen Claude Desktop. Choose Continue with Gateway and the local configuration, then select a Claude model such as claude-sonnet-5.

xAIChat Completions

Set up Grok Build

Install the CLI, expose your Zrelay key as XAI_API_KEY, and add the supported Grok models.

Your system

Install Grok Build

Run xAI's official installer, then open a new terminal window.

Terminal

curl -fsSL https://x.ai/cli/install.sh | bash

The npm installer is also a fallback when x.ai is blocked on your network.

Set your API key

Replace zr_live_YOUR_API_KEY with your Zrelay key.

Terminal

export XAI_API_KEY=zr_live_YOUR_API_KEY

Add the export to ~/.zshrc or ~/.bashrc to keep it between sessions.

Add the Grok models

Create the configuration file for your system.

File~/.grok/config.toml

config.toml

[model.grok-4-5]
model = "grok-4.5"
base_url = "https://api.zrelay.net/v1"
env_key = "XAI_API_KEY"
api_backend = "chat_completions"

[model.grok-4-5-latest]
model = "grok-4.5"
base_url = "https://api.zrelay.net/v1"
env_key = "XAI_API_KEY"
api_backend = "chat_completions"

Keep api_backend set to chat_completions. Grok models on Zrelay use /v1/chat/completions. The Responses API is not supported for Grok.

Restart and choose a model

Fully quit and reopen your terminal. Run grok, then select grok-4-5 or grok-4-5-latest from the model picker.

Terminal

grok

Codex

Claude Code

Grok Build

OpenCode

Cursor

VS Code

Antigravity

ZCode

Claude Desktop

Install Codex

Add the Zrelay configuration

Save your API key

Run a real request

Install Claude Code

Connect Claude Code to Zrelay

Verify and launch

GPT and Grok

Open the global config

Add the Zrelay provider

Restart and choose a model

Claude

Open the global config

Add the Zrelay Anthropic provider

Restart and choose a model

Codex extension

Install the Codex extension

Point Codex at Zrelay

Reload and start coding

Claude Code extension

Install the Claude Code extension

Point Claude Code at Zrelay

Reload and choose a model

Codex extension

Install the Codex extension

Point Codex at Zrelay

Reload and start coding

Claude Code extension

Install the Claude Code extension

Point Claude Code at Zrelay

Reload and choose a model

Grok via Copilot Chat

Open Manage Language Models

Add a Grok Custom Endpoint

Save and start chatting

Codex extension

Install the Codex extension

Point Codex at Zrelay

Reload Cursor

Claude Code extension

Install the Claude Code extension

Point Claude Code at Zrelay

Reload and choose a model

Open ZCode without signing in

Open Model settings

Add the Zrelay provider

Choose the API format

Add models and start coding

Enable Developer Mode

Open Third-Party Inference

Enter the gateway settings

Restart and choose a model

Install Grok Build

Set your API key

Add the Grok models

Restart and choose a model