Install the CLI

System requirements

Before installing the Nexus CLI, ensure your system meets these requirements: macOS 12+ (Intel or Apple Silicon), Linux (kernel 5.4+, glibc 2.28+), or Windows (10 22H2+, 64-bit). You will need approximately 150MB of free disk space and a stable internet connection. No prior AI or ML experience is required.

macOS / Linux installation

The fastest way to install Nexus is via the install script. Open your terminal and run:

curl -fsSL https://nexus.run/install.sh | sh

The script detects your operating system and architecture, downloads the appropriate binary, and adds it to your PATH. After installation, verify the CLI is working:

nexus --version

You should see output similar to: Nexus CLI v0.8.0 (commit abc123)

Windows installation

On Windows, open PowerShell as Administrator and run:

irm https://nexus.run/install.ps1 | iex

This downloads the Windows binary and adds it to your system PATH. After installation, open a new PowerShell window and verify:

nexus --version

Troubleshooting: If you encounter a security policy error, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned first. For manual installation, download the binary from our releases page and add it to your PATH manually.

Package manager installation (alternative)

If you prefer package managers, Nexus is available via Homebrew on macOS:

brew install nexus/tap/nexus

And via npm (requires Node.js 18+):

npm install -g @nexus/cli

Configuration

After installation, configure the CLI with your API key. Create an account at nexus.run and retrieve your key from the dashboard. Then run:

nexus config set api-key nk_xxxxxxxxxxxx

You can also configure your default model and organization:

nexus config set model nexus-1
nexus config set org my-org

Verify your configuration is correct:

nexus config list

Installing with Docker

For teams that prefer containerized environments, Nexus is available as a Docker image. This is especially useful for CI/CD pipelines and server deployments:

docker pull nexus/agent:latest
docker run --rm nexus/agent:latest nexus --version

The Docker image bundles the CLI, the Nexus-1 model runtime, and all dependencies. For production deployments, mount a volume for persistent state:

docker run -d \\
  --name nexus-agent \\
  -v ./data:/nexus/data \\
  -e NEXUS_API_KEY=nk_xxxx \\
  nexus/agent:latest \
  nexus deploy --name prod-agent

Available tags: latest (stable), nightly (daily builds), and versioned tags like 0.8.0.

Verifying your installation

After installation, run the full verification suite to confirm everything is working correctly. The CLI includes a built-in diagnostic command:

nexus doctor

This checks: binary integrity (SHA256 hash verification), API connectivity (makes a test request to api.nexus.run), configuration file validity (parses nexus.yaml if present), disk space availability (requires 500MB+ for agent caches), and GPU availability (if applicable). Each check produces a green checkmark or red X with a suggested fix. Typical output:

[PASS] Binary integrity: nexus.exe v0.8.0 (sha256 ok)
[PASS] API connectivity: api.nexus.run reachable (12ms)
[PASS] Disk space: 14.2 GB available (500 MB required)
[WARN] GPU: No CUDA device found (CPU mode, expect slower perf)
[INFO] Configuration: no nexus.yaml found (run nexus init)

Troubleshooting common issues

Issue: "command not found" after installation. The installer adds Nexus to your PATH, but you may need to restart your terminal or run source ~/.bashrc (Linux/macOS) or open a new PowerShell window (Windows). If the issue persists, check that the installation directory (/usr/local/bin on Linux/macOS, %LOCALAPPDATA%\nexus\bin on Windows) is in your PATH.

Issue: "Permission denied" when installing. On Linux/macOS, the install script requires sudo for system-wide installation. Run curl -fsSL https://nexus.run/install.sh | sudo sh. Alternatively, install to a user directory by setting INSTALL_DIR=$HOME/.nexus/bin before running the script.

Issue: "SSL certificate verification failed." Ensure your system clock is correct and your CA certificates are up to date. On Linux: apt-get install ca-certificates (Debian/Ubuntu) or yum install ca-certificates (RHEL/Fedora). On Windows, run nexus doctor for automated diagnostics.

Issue: Homebrew installation fails. Ensure Homebrew is up to date: brew update && brew upgrade. If the Nexus tap is not found, add it manually: brew tap nexus/tap && brew install nexus/tap/nexus.

Issue: npm global install permission error. On Unix systems, avoid using sudo with npm. Instead, configure npm to use a user directory: npm config set prefix $HOME/.npm-global and add export PATH=$HOME/.npm-global/bin:$PATH to your shell profile.

IDE Integration

Nexus integrates with popular IDEs for an inline agent experience. VS Code: install the Nexus extension from the marketplace (ext install nexus.nexus-vscode). The extension adds a Nexus panel for managing agents, inline code suggestions, and PR review integration. JetBrains (IntelliJ, WebStorm, PyCharm): install from the JetBrains Marketplace. The plugin supports the same features with native IDE theme integration. Neovim: install via lazy.nvim: { "nexus/nexus.nvim", opts = {} }.

After installing the IDE extension, configure your API key in the extension settings. The extension automatically detects nexus.yaml files in your project root and loads the corresponding agent configuration.

Next steps

Once the CLI is installed and configured, proceed to Step 2: Deploy your first agent. The entire installation process should take less than 5 minutes.