Bare Node.js

Running Reacher directly with Node.js is the lightest-weight option and works well on any VPS where you already manage the process lifecycle.

Prerequisites

Node.js 18 or later (node --version to check)
npm (bundled with Node.js)
Git

Setup

Clone the repository

git clone --branch v0.1.0 https://github.com/thezem/reacher.git
cd reacher

Install dependencies

npm install

Configure environment and config files

cp .env.example .env
cp reacher.config.example.yaml reacher.config.yaml

Open .env and fill in your credentials. The required variables are:

MCP_SECRET=<random-string>        # openssl rand -hex 32
TAILSCALE_API_KEY=<your-key>
GITHUB_TOKEN=<your-token>
PROXY_ALLOWED_DOMAINS=api.github.com

See .env.example for the full list of options.

Start the server

node index.js

The server starts on port 3000 by default (or PORT from your .env).

✅ MCP Server started on http://localhost:3000
   POST http://localhost:3000/mcp
   GET  http://localhost:3000/health

Verify it is running

curl "http://localhost:3000/health?token=YOUR_MCP_SECRET"

Expected response: {"status":"ok",...}

Start options

npm start

node index.js

Both are equivalent — npm start is defined as node index.js in package.json.

Development mode with auto-reload

During development, use --watch mode so the server restarts automatically when you edit files:

npm run dev

This runs node --watch index.js (built into Node.js 18+, no extra tools needed).

Production with PM2

For a long-running production deployment, PM2 manages the process, restarts it on crash, and survives reboots.

Install PM2 globally

npm install -g pm2

Start Reacher with PM2

pm2 start index.js --name reacher

pm2 start index.js --name reacher --log ./reacher.log

Save the process list and enable startup

pm2 save
pm2 startup

Run the command that pm2 startup prints — this registers PM2 to launch on system boot.

Useful PM2 commands

pm2 status                  # show all managed processes
pm2 logs reacher            # stream live logs
pm2 logs reacher --lines 50 # last 50 log lines
pm2 restart reacher         # restart the process
pm2 stop reacher            # stop without removing
pm2 delete reacher          # stop and remove from PM2

Health check

curl "http://localhost:3000/health?token=YOUR_MCP_SECRET"

{
  "status": "ok",
  "timestamp": "2026-03-18T12:00:00.000Z",
  "dry_run": false
}

Updating

Pull the latest code

git pull

Install any new dependencies

npm install

Restart the server

pm2 restart reacher

# Stop the running process (Ctrl+C or kill), then:
node index.js

Exposing Reacher publicly

The server listens on http://localhost:3000 by default. Claude.ai requires a public HTTPS URL to connect. The standard approach on a VPS is a reverse proxy. Caddy handles HTTPS certificate provisioning automatically:

mcp.yourdomain.com {
  reverse_proxy localhost:3000
}

With Nginx, add a server block that proxies to port 3000 and configure Certbot for TLS.

Cloud platforms like EasyPanel, Railway, and Render handle HTTPS automatically if you prefer not to manage a reverse proxy yourself. See the other deployment guides for those options.

Get Started

Configuration

Tools

Deployment

Operations

Extending

Prerequisites

Setup

Start options

Development mode with auto-reload

Production with PM2

Useful PM2 commands

Health check

Updating

Exposing Reacher publicly

​Prerequisites

​Setup

​Start options

​Development mode with auto-reload

​Production with PM2

​Useful PM2 commands

​Health check

​Updating

​Exposing Reacher publicly

Prerequisites

Setup

Start options

Development mode with auto-reload

Production with PM2

Useful PM2 commands

Health check

Updating

Exposing Reacher publicly