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.

Pull the Latest Image

docker pull ghcr.io/grafbase/nexus:latest

Pull a Specific Version

docker pull ghcr.io/grafbase/nexus:0.2.0

Running with Docker

Basic usage:

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

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:latest

Docker Compose

Create a docker-compose.yml file:

services:
  nexus:
    image: ghcr.io/grafbase/nexus:latest
    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

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.

Next Steps

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.