Installation

Nexus can be installed using several methods depending on your environment and requirements. Choose the installation method that best suits your needs.

Quick Install

The fastest way to get started with Nexus is using our installation script:

curl -fsSL https://nexusrouter.com/install | bash

This script will:

  • Detect your operating system and architecture
  • Download the appropriate binary
  • Install it to ~/.nexus/bin
  • Make it executable

Supported Platforms

  • Linux (x86_64, aarch64)
  • macOS (Intel, Apple Silicon)
  • Windows (via WSL)

Docker Installation

Nexus is available as a Docker image for containerized deployments.

docker pull ghcr.io/grafbase/nexus:stable

Pull a Specific Version

docker pull ghcr.io/grafbase/nexus:0.2.0

Pull the Latest Development Build

docker pull ghcr.io/grafbase/nexus:latest

Note: The stable tag points to the latest released version, while latest follows the main branch and may include unreleased features.

Running with Docker

Basic usage:

docker run -p 8000:8000 \
  -v $(pwd)/nexus.toml:/etc/nexus.toml \
  ghcr.io/grafbase/nexus:stable

With environment variables:

docker run -p 8000:8000 \
  -v $(pwd)/nexus.toml:/etc/nexus.toml \
  -e GITHUB_TOKEN=${GITHUB_TOKEN} \
  -e OPENAI_API_KEY=${OPENAI_API_KEY} \
  ghcr.io/grafbase/nexus:stable

Docker Compose

Create a compose.yaml file:

services:
  nexus:
    image: ghcr.io/grafbase/nexus:stable
    ports:
      - "8000:8000"
    volumes:
      - ./nexus.toml:/etc/nexus.toml
      # Mount additional directories if using STDIO servers
      - /path/to/mcp-servers:/opt/mcp-servers
    environment:
      - GITHUB_TOKEN=${GITHUB_TOKEN}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

Then run:

docker compose up -d

Helm

The Nexus Helm chart simplifies deployment with Kubernetes. The GitHub Container Registry hosts the chart with Open Container Initiative (OCI) compliance and is available here:

https://ghcr.io/grafbase/helm-charts/nexus

Deploying

The chart includes default installation configuration for quick setup with minimal configuration. While functional and easy to start with, tune this setup to accommodate real use cases.

Follow these steps to install the default configuration and customize settings for:

  1. Number of replicas
  2. Auto-scaling
  3. Compute resources
  4. External configuration

Setup

Complete these prerequisites before deploying:

  1. Kubernetes Cluster: Get access to a Kubernetes cluster. Set up a local cluster like kind if needed.
  2. helm: Install Helm. Get started here.
  3. kubectl: Install kubectl and point it to your cluster. Get started here.

Basic deployment

Install the Nexus chart:

helm install test oci://ghcr.io/grafbase/helm-charts/nexus --version <version>

Verify Nexus operation:

kubectl get pods

Look for a running pod named test-nexus.

Customize deployment

Use a Helm values file to customize your deployment:

# 1. number of desired replicas running
replicaCount: 2

# 2. auto-scaling behaviour
autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 70

# 3. compute resources
resources:
  limits:
    cpu: 2
    memory: 2Gi
  requests:
    cpu: 1
    memory: 1Gi

# 4. external configuration from cluster configmaps
nexus:
  externalConfig: true
  args:
    - --config
    - /etc/nexus/config/config.toml
volumes:
  - name: configuration
    configMap:
      name: nexus-configuration
volumeMounts:
  - name: configuration
    mountPath: /etc/nexus/config

This configuration:

  1. Maintains 2 gateway replicas
  2. Sets auto-scaling between 2 and 10 instances, scaling up at 70% CPU or memory usage
  3. Allocates 1-2 CPU and 1-2GB memory per replica
  4. Uses cluster configmaps for configuration and mounting them in the specified paths

View all customizable values with:

helm show values oci://ghcr.io/grafbase/helm-charts/nexus --version <version>

To apply customizations:

  1. Save your settings to a file
  2. Run:
helm upgrade test oci://ghcr.io/grafbase/helm-charts/nexus --version <version> -f custom-values.yaml

Verify the deployment:

helm list

kubectl get pods

Build from Source

For advanced users who want to build Nexus from source:

Prerequisites

  • Latest stable Rust
  • Git

Build Steps

  1. Clone the repository:
git clone https://github.com/grafbase/nexus
cd nexus
  1. Build the release binary:
cargo build --release -p nexus

  1. The binary will be available at target/release/nexus

  2. (Optional) Install to system path:

mkdir -p ~/.nexus/bin
sudo cp target/release/nexus ~/.nexus/bin
sudo chmod +x ~/.nexus/bin/nexus

Verifying Installation

After installation, verify Nexus is working:

nexus --version

You should see output like:

nexus 0.2.0

Running Nexus

Basic Usage

Start Nexus with default settings:

nexus

This will:

  • Look for nexus.toml in the current directory
  • Start the server on http://127.0.0.1:8000
  • Enable the health endpoint at /health

Command Line Options

Usage: nexus [OPTIONS]

Options:
  -l, --listen-address <LISTEN_ADDRESS>
          IP address on which the server will listen for incomming connections. Default: 127.0.0.1:6000

          [env: NEXUS_LISTEN_ADDRESS=]

  -c, --config <CONFIG>
          Path to the TOML configuration file

          [env: NEXUS_CONFIG_PATH=]
          [default: ./nexus.toml]

      --log <LOG_LEVEL>
          Set the logging level, this applies to all spans, logs and trace events

          [env: NEXUS_LOG=]
          [default: info]

          Possible values:
          - off:   Disable logging
          - error: Only log errors
          - warn:  Log errors, and warnings
          - info:  Log errors, warnings, and info messages
          - debug: Log errors, warnings, info, and debug messages
          - trace: Log errors, warnings, info, debug, and trace messages

      --log-style <LOG_STYLE>
          Set the style of log output

          [env: NEXUS_LOG_STYLE=]
          [default: color]

          Possible values:
          - color: Colorized text, used as the default with TTY output
          - text:  Standard text, used as the default with non-TTY output
          - json:  JSON objects

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Environment Variables

Nexus supports the following environment variables:

  • NEXUS_LISTEN_ADDRESS: Set the address and port to listen on (default: 127.0.0.1:8000)
  • NEXUS_CONFIG_PATH: Alternative way to specify config file path
  • NEXUS_LOG: Set logging level (debug, info, warn, error)
  • NEXUS_LOG_STYLE: Set the style of log output (color, text, json)

Configuration File

Nexus requires a configuration file (default: nexus.toml). Create a basic configuration:

# Add your first MCP server
[mcp.servers.example]
cmd = ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

See the Server Configuration and MCP Configuration sections for detailed configuration options.

Troubleshooting

Docker Network Issues

If Docker containers can't reach Nexus:

  1. Use host.docker.internal instead of localhost on macOS/Windows
  2. Use the container name in Docker Compose networks
  3. Ensure proper port mapping with -p 8000:8000
© Grafbase, Inc.