Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ouim.me/llms.txt

Use this file to discover all available pages before exploring further.

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

1

Clone the repository

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

Install dependencies

npm install
3

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.
4

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
5

Verify it is running

curl "http://localhost:3000/health?token=YOUR_MCP_SECRET"
Expected response: {"status":"ok",...}

​
Start options

npm start
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.
1

Install PM2 globally

npm install -g pm2
2

Start Reacher with PM2

pm2 start index.js --name reacher
3

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

1

Pull the latest code

git pull
2

Install any new dependencies

npm install
3

Restart the server

pm2 restart reacher

​
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.