NPM / CLI

Run the OpenBotAuth Proxy using npm or npx.

Quick Start

# Run without installing (recommended)
npx @openbotauth/proxy

# Or install globally
npm install -g @openbotauth/proxy
openbotauth-proxy

Requirements: Node.js >= 18.0.0

Installation Methods

npx (No Install)

Run directly without installing:

npx @openbotauth/proxy

Global Install

# npm
npm install -g @openbotauth/proxy

# pnpm
pnpm add -g @openbotauth/proxy

# yarn
yarn global add @openbotauth/proxy

After global install, run with:

openbotauth-proxy
# or
oba-proxy

Local Install

Add to your project:

npm install @openbotauth/proxy

Then run via npm scripts in package.json:

{
  "scripts": {
    "proxy": "openbotauth-proxy"
  }
}

Configuration

All configuration is via environment variables:

Variable

Default

Description

PORT

8088

Proxy listen port

UPSTREAM_URL

http://localhost:8080

Backend server URL

OBA_VERIFIER_URL

https://verifier.openbotauth.org/verify

Verifier service endpoint

OBA_MODE

observe

observe or require-verified

OBA_TIMEOUT_MS

5000

Verifier request timeout (ms)

OBA_PROTECTED_PATHS

/protected

Comma-separated paths requiring verification

Usage Examples

Basic Usage

Proxy requests from port 8088 to localhost:8080:

npx @openbotauth/proxy

Custom Backend

Proxy to a different backend:

UPSTREAM_URL=http://localhost:3000 npx @openbotauth/proxy

Custom Port

Run on a different port:

PORT=9000 npx @openbotauth/proxy

Require Verification

Enforce verification on all paths:

OBA_MODE=require-verified npx @openbotauth/proxy

Protected Paths Only

Require verification only on specific paths:

OBA_MODE=require-verified \
OBA_PROTECTED_PATHS=/api,/content,/premium \
npx @openbotauth/proxy

Full Configuration

PORT=8088 \
UPSTREAM_URL=http://localhost:3000 \
OBA_VERIFIER_URL=https://verifier.openbotauth.org/verify \
OBA_MODE=require-verified \
OBA_TIMEOUT_MS=3000 \
OBA_PROTECTED_PATHS=/api/v1,/protected \
npx @openbotauth/proxy

Process Managers

PM2

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'oba-proxy',
    script: 'npx',
    args: '@openbotauth/proxy',
    env: {
      PORT: 8088,
      UPSTREAM_URL: 'http://localhost:3000',
      OBA_MODE: 'observe'
    }
  }]
};

pm2 start ecosystem.config.js

systemd

# /etc/systemd/system/oba-proxy.service
[Unit]
Description=OpenBotAuth Proxy
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/oba-proxy
Environment=PORT=8088
Environment=UPSTREAM_URL=http://localhost:3000
Environment=OBA_MODE=observe
ExecStart=/usr/bin/npx @openbotauth/proxy
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl enable oba-proxy
sudo systemctl start oba-proxy

Programmatic Usage

You can also use the proxy programmatically in your Node.js application:

import { createProxyServer } from '@openbotauth/proxy';

const server = createProxyServer({
  port: 8088,
  upstream: 'http://localhost:3000',
  verifierUrl: 'https://verifier.openbotauth.org/verify',
  mode: 'observe',
  timeoutMs: 5000,
  protectedPaths: ['/api', '/protected']
});

server.listen();

Health Check

Verify the proxy is running:

curl http://localhost:8088/.well-known/health

Response:

{
  "status": "ok",
  "service": "openbotauth-proxy",
  "upstream": "http://localhost:8080",
  "verifier": "https://verifier.openbotauth.org/verify",
  "mode": "observe"
}

Logging

The proxy logs to stdout:

[OBA] Proxy started on port 8088
[OBA] Upstream: http://localhost:3000
[OBA] Mode: observe
[OBA] GET /api/content -> verified (agent: MyBot)
[OBA] GET /public -> unsigned

Troubleshooting

Proxy won't start

Check that the port is available:

lsof -i :8088

Verification always fails

Check the verifier URL is accessible
Verify the bot is sending correct RFC 9421 headers
Check clock synchronization (signatures expire)

Timeout errors

Increase the timeout:

OBA_TIMEOUT_MS=10000 npx @openbotauth/proxy

Backend not receiving requests

Verify UPSTREAM_URL is correct
Check backend is running and accessible
Test direct connection to backend