CoDevDocs · 0.4.0

Installation

CoDev runs on Windows, Linux, and macOS. This guide walks you through preparing Node.js, installing and configuring CoDev, signing in with SSO, and recovering from common setup issues.

Prepare your Node.js environment

CoDev requires Node.js >= 22.21.0 (version 24+ recommended). Check your versions by running node -v and npm -v in a terminal or PowerShell. If Node.js isn't installed yet, download the installers from DataSecurity and follow the steps below for internal networks.

Windows

Download node-v24.15.0-x64.msi and install it (you may need to ask your unit's information-security or IT contact for install permissions). Open PowerShell and check with node -v and npm -v.

If node -v works but npm -v fails

Run the following in PowerShell, type A, press Enter, then close and reopen PowerShell:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Linux

Download the node-v24.15.0-linux.tar.xz binary and extract it:

tar -xzf node-v24.15.0-linux.tar.xz

Then, from the folder containing the extracted Node.js, run:

# Create the Node.js directory
sudo mkdir -p /usr/local/lib/nodejs

# Copy the extracted Node.js into it
sudo cp -ra node-v24.15.0-linux /usr/local/lib/nodejs/

Add these lines to ~/.bashrc:

export NODEJS_HOME=/usr/local/lib/nodejs/node-v24.15.0-linux/bin
export PATH=$NODEJS_HOME:$PATH

Reload your shell with source ~/.bashrc (or open a new terminal), then verify with node -v and npm -v.

Linux with nvm

If you use nvm, install the binary into nvm's versions folder:

# Create the Node.js folder inside nvm
mkdir -p ~/.nvm/versions/node/v24.15.0

# Copy the extracted Node.js into it
cp -rn ./node-v24.15.0-linux/. ~/.nvm/versions/node/v24.15.0/

Open a new terminal and run nvm use 24 to use Node.js 24. Optionally make it the default for future terminals:

nvm alias default 24

Verify with node -v and npm -v.

Install and configure

CoDev works on both external and internal networks.

Internal network: set the npm registry

On an internal-only machine, npm connects through Nexus, so you may need to point npm at the internal registry (check with your IT contact whether the Nexus connection is in place). Run:

npm config set registry http://10.60.129.132/repository/npm-proxy

Before you install

macOS only

If you've used Claude Code before, open it (claude) and run /logout first.

Windows only

If your installed Claude Code reports "is not compatible with the version of Windows you're running" — a latest-version incompatibility — remove it (you'll reinstall the stable build through CoDev in the next steps):

npm rm -g @anthropic-ai/claude-code
npm cache clean --force

Install CoDev

Install CoDev from npm:

npm i -g codev-ai

If you hit a 403 error, unset the proxy and retry without restarting your terminal. Windows PowerShell:

$env:HTTPS_PROXY = $null; $env:HTTP_PROXY = $null; $env:https_proxy = $null; $env:http_proxy = $null

Linux:

unset HTTPS_PROXY HTTP_PROXY https_proxy http_proxy

Then re-run npm i -g codev-ai. When it finishes, verify with codevhub -v.

Set up the AI tools

New users (skip to the next step if you've installed CoDev — or tools like Claude Code and OpenCode — before): run codevhub install, pick the tools to install, then press y and Enter.

Existing users (you've installed CoDev, Claude Code, or OpenCode before): run codevhub config instead, pick the tools to configure, then press y and Enter.

In both cases:

  • CLI tools: choose Claude Code or OpenCode (both recommended). Codex doesn't work with the self-hosted models yet.
  • IDE extensions/plugins: both Claude Code and Continue work on VS Code and JetBrains (specifically PyCharm, IDEA, GoLand).

JetBrains plugins

JetBrains plugins are rated noticeably lower than the VS Code extensions — many are still in beta and/or haven't been updated in a long time.

Then wait for CoDev to auto-install the AI tools. CLI installs can take a while on the internal network. If an extension's auto-install fails (for example, on the internal network), you can install it by hand later (the files are in the DataSecurity link above); Claude Code and Continue are still auto-configured to the self-hosted models.

Sign in with SSO

On an environment with a browser, it opens automatically so you can sign in. If it doesn't open — or you're on a headless machine — copy the URL from the terminal (just press C) and paste it into another browser. After signing in, copy the code shown and paste it back into the terminal, then press Enter.

If you see "Login failed"

This requires Node.js >= 22.21.0. First remove *.viettel.vn from NO_PROXY, then add the proxy environment variables for your OS.

Windows: search for Edit environment variables for your account (not Edit the system environment variables — the two look almost identical). Under User variables, click New… and add:

  • HTTP_PROXY = <PROXY-IP>:<PROXY-PORT>
  • HTTPS_PROXY = <PROXY-IP>:<PROXY-PORT>
  • NODE_USE_SYSTEM_CA = 1
  • NODE_USE_ENV_PROXY = 1

Then restart PowerShell.

Linux: add this line to the end of ~/.bashrc or ~/.zshrc:

export HTTP_PROXY=<PROXY-IP>:<PROXY-PORT> HTTPS_PROXY=<PROXY-IP>:<PROXY-PORT> http_proxy=<PROXY-IP>:<PROXY-PORT> https_proxy=<PROXY-IP>:<PROXY-PORT> NODE_USE_SYSTEM_CA=1 NODE_USE_ENV_PROXY=1

Then run source ~/.bashrc (or source ~/.zshrc, or open a new terminal). If it still fails, see Troubleshooting below.

Choose a default model

If you already have a valid API key saved on your machine, choose Reuse existing API Key. If that option doesn't appear, choose Get a new API Key.

Then choose your default model:

  • MiniMax M2.7 (on VTNet infrastructure), or
  • GLM 4.7-cc (the commercial build, deployed on VAI infrastructure).

Why pick a default model?

OpenCode lets you switch models freely inside the CLI, but Claude Code and Codex don't — they only let you replace the proprietary Anthropic/OpenAI model with a single one. See the Quickstart for details.

Troubleshooting

If you still can't sign in on an internal machine after adding the proxy environment variables above, you can disable TLS verification as a last resort.

Last resort only

Disabling TLS verification is always bad practice. Only use this as a final option, and only on an internal network that sits behind a proxy.

First remove the previous CoDev install:

codevhub remove
npm rm -g codev-ai

Windows: open Edit environment variables for your account (not Edit the system environment variables — the two look almost identical). Under User variables, delete NODE_USE_SYSTEM_CA and NODE_USE_ENV_PROXY if present, then click New… and add NODE_TLS_REJECT_UNAUTHORIZED with the value 0. Restart PowerShell.

Linux: edit ~/.bashrc or ~/.zshrc, delete NODE_USE_SYSTEM_CA=1 and NODE_USE_ENV_PROXY=1 (if present), then add this line at the end:

export NODE_TLS_REJECT_UNAUTHORIZED=0

Run source ~/.bashrc (or source ~/.zshrc).

Finally, run codevhub install again.