Installation

This page covers every way to install OpalServe, along with verification steps and common troubleshooting solutions.

Requirements

Requirement	Minimum Version	Recommended
Node.js	20.0.0	22.x LTS
npm	9.0.0	10.x
pnpm	8.0.0 (optional)	9.x

OpalServe relies on native Node.js APIs introduced in v20: fetch, crypto.subtle, navigator, and ES module support. Earlier versions will fail at startup.

npm (Recommended)

npm install -g opalserve

This installs the opalserve and opalserve-discover binaries globally.

pnpm

pnpm add -g opalserve

yarn

yarn global add opalserve

npx (No Install)

Run OpalServe commands without a global install:

npx opalserve init
npx opalserve start
npx opalserve tools search "read file"

When to use npx

This is convenient for trying OpalServe out or for CI/CD scripts. For daily use, a global install is faster since it skips the package resolution step each time.

As a Project Dependency

Install OpalServe as a local dependency to use the library API programmatically:

npm install opalserve

Then import it in your code:

import { OpalServeRegistry, KnowledgeBase, UsageTracker } from 'opalserve';

const registry = await OpalServeRegistry.create({
  mode: 'local',
  servers: [{
    name: 'my-server',
    transport: {
      type: 'stdio',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '.'],
    },
  }],
});

await registry.start();

See the Library API reference for the full programmatic interface.

From Source

Clone the repository and build from source:

git clone https://github.com/adityaidev/opalserve.git
cd opalserve
pnpm install
pnpm build

# Link globally for CLI access
pnpm link --global

# Or run in dev mode with hot reload
pnpm dev

Contributing

If you are building from source to contribute, see the Contributing Guide for development workflow, code style, and PR guidelines.

Docker

docker pull ghcr.io/adityaidev/opalserve:latest

docker run -d \
  --name opalserve \
  -p 3456:3456 \
  -v opalserve-data:/data \
  ghcr.io/adityaidev/opalserve:latest

For team server deployments, pass configuration via environment variables:

docker run -d \
  --name opalserve \
  -p 3456:3456 \
  -e OPALSERVE_MODE=team-server \
  -e OPALSERVE_JWT_SECRET=your-secret-here \
  -e OPALSERVE_PORT=3456 \
  -v opalserve-data:/data \
  ghcr.io/adityaidev/opalserve:latest

Verify Installation

After installing, verify that OpalServe is working:

# Check version
opalserve --version
# 3.0.0

# Show help
opalserve --help

# Run the setup wizard
opalserve init

You should see the OpalServe banner and version number. If the command is not found, see Troubleshooting below.

Troubleshooting

command not found: opalserve

The global node_modules/.bin directory is not in your PATH.

npm — find the global bin directory and add it:

npm config get prefix
# Add the output + /bin to your PATH
# e.g., export PATH="$PATH:$(npm config get prefix)/bin"

pnpm — run:

pnpm setup
# Then restart your shell

ERR_MODULE_NOT_FOUND or ESM errors

Make sure you are running Node.js 20 or later:

node --version
# Must be v20.0.0 or higher

If you have multiple Node.js versions, use nvm or fnm to switch:

nvm install 22
nvm use 22

EACCES: permission denied on global install

Do not use sudo with npm. Instead, fix npm permissions:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$PATH:$HOME/.npm-global/bin"
# Add the export line to your shell profile (~/.bashrc, ~/.zshrc)

Port already in use

If port 3456 is taken, specify a different port:

opalserve start --port 8080

Or set the environment variable:

export OPALSERVE_PORT=8080
opalserve start

SQLite native module errors

OpalServe uses better-sqlite3 which requires a native build step. If the install fails:

# Ensure build tools are available
# macOS:
xcode-select --install

# Ubuntu/Debian:
sudo apt-get install build-essential python3

# Windows:
npm install --global windows-build-tools

# Then retry
npm install -g opalserve