Documentation

Install Claude Code, Codex & Gemini CLI

Install Claude Code, Codex, or Gemini CLI with npm, connect your chosen client to Code By AI, and run a test request to verify your setup.

1. Check Node.js and npm

Use a current Node.js LTS release. Check what is already installed before downloading anything:

1
node --version
2
npm --version

If either command is missing, install Node.js first. npm is included with Node.js.

macOS with Homebrew

1
brew install node

Ubuntu / Debian

1
sudo apt update
2
sudo apt install nodejs npm

Windows

Download the current LTS installer from nodejs.org, run it, and keep the option to add Node.js to your PATH enabled. Open a new terminal after installation and run the version checks again.

If you manage several Node.js versions, use your usual version manager instead of changing the system Node.js installation.

2. Install the coding client you need

Install only the tools you actually use.

Claude Code

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

Codex

1
npm install -g @openai/codex

Gemini CLI

1
npm install -g @google/gemini-cli

Verify the installation and confirm that the CLI is available on your PATH:

1
claude --version
2
codex --version
3
gemini --version

You only need the checks for the clients you installed. A version number means the package installed correctly; it does not yet prove that the API connection works.

3. Configure Code By AI

Create a key in your Code By AI dashboard, then point the client at the gateway. Keep the key out of source control and out of shell history where possible.

For Claude Code, the two required variables are the endpoint and the token:

macOS / Linux (Bash / Zsh)

1
export ANTHROPIC_BASE_URL="https://www.codebyai.net/api/agent"
2
export ANTHROPIC_AUTH_TOKEN="sk-proj-xxxx"

Windows PowerShell

1
$env:ANTHROPIC_BASE_URL = "https://www.codebyai.net/api/agent"
2
$env:ANTHROPIC_AUTH_TOKEN = "sk-proj-xxxx"

Windows CMD

1
set "ANTHROPIC_BASE_URL=https://www.codebyai.net/api/agent"
2
set "ANTHROPIC_AUTH_TOKEN=sk-proj-xxxx"

Choose the commands for your terminal and replace sk-proj-xxxx with your real key. These variables apply only to the current terminal; run the smoke test below in the same window. To persist them, add the export lines to ~/.zshrc or ~/.bashrc on macOS / Linux, or follow the Windows configuration steps. If using ~/.claude/settings.json, follow the JSON configuration example and put the variables in its env object; do not paste shell commands into that file.

The other clients use different configuration files and variable names:

If you are not sure which variable belongs in which file, use the environment variable reference. It includes shell, settings.json, VS Code, TypeScript, Python, YAML, TOML, INI and .env examples.

4. Run the first request

For Claude Code, use print mode so the command exits after the response:

1
claude -p "Reply with exactly: setup ok"

A reply of setup ok confirms all three parts: the CLI is installed, the gateway accepts your key, and the model responded. If the command hangs or returns an authentication error, use the checks below instead of reinstalling the CLI.

Troubleshooting

node: command not found or npm: command not found. Node.js is not installed, or your terminal has not reloaded its PATH. Install Node.js, close the terminal, and try again.

claude: command not found after a global npm install. Check where npm placed global binaries:

1
npm prefix -g

Add the global executable directory to your PATH, where {prefix} means the directory printed by npm prefix -g:

  • macOS / Linux: add {prefix}/bin.
  • Windows: add {prefix} itself, without appending bin.

Open a new terminal after updating PATH, then run claude --version again. On macOS and Linux, a version manager such as nvm is usually cleaner than installing global packages with sudo.

EACCES or permission errors during npm install -g. Do not reach for sudo first. Use a Node.js version manager or a user-writable npm global prefix.

401, invalid api key, or an authentication error. Check that ANTHROPIC_AUTH_TOKEN contains your Code By AI key and that you have not also set ANTHROPIC_API_KEY. The two variables use different headers; set only one.

Requests reach Anthropic instead of Code By AI. Check ANTHROPIC_BASE_URL. It must be https://www.codebyai.net/api/agent, and it must be set in the same environment that starts the CLI. The VS Code extension panel needs claudeCode.environmentVariables, not only a shell export.

Long requests time out. Check the failure time and gateway logs. Anthropic Messages streaming uses separate startup, idle and total deadlines; non-streaming requests retain a 295-second total limit. Raising API_TIMEOUT_MS cannot extend these limits. If the request fails immediately, check the endpoint and API key.

A settings edit has no effect. Restart the CLI or run Developer: Reload Window in VS Code. Environment variables are read when the process starts.

Next steps

Once the smoke test passes, compare Claude Code pricing and choose the model that matches your workload.