> For the complete documentation index, see [llms.txt](https://docs.openbotauth.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openbotauth.org/proxy/npm.md).

# NPM / CLI

Run the OpenBotAuth Proxy using npm or npx.

**Package:** [@openbotauth/proxy](https://www.npmjs.com/package/@openbotauth/proxy)

## Quick Start

```bash
# 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:

```bash
npx @openbotauth/proxy
```

### Global Install

```bash
# npm
npm install -g @openbotauth/proxy

# pnpm
pnpm add -g @openbotauth/proxy

# yarn
yarn global add @openbotauth/proxy
```

After global install, run with:

```bash
openbotauth-proxy
# or
oba-proxy
```

### Local Install

Add to your project:

```bash
npm install @openbotauth/proxy
```

Then run via npm scripts in `package.json`:

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

```bash
npx @openbotauth/proxy
```

### Custom Backend

Proxy to a different backend:

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

### Custom Port

Run on a different port:

```bash
PORT=9000 npx @openbotauth/proxy
```

### Require Verification

Enforce verification on all paths:

```bash
OBA_MODE=require-verified npx @openbotauth/proxy
```

### Protected Paths Only

Require verification only on specific paths:

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

### Full Configuration

```bash
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

```javascript
// 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'
    }
  }]
};
```

```bash
pm2 start ecosystem.config.js
```

### systemd

```ini
# /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
```

```bash
sudo systemctl enable oba-proxy
sudo systemctl start oba-proxy
```

## Programmatic Usage

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

```typescript
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:

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

Response:

```json
{
  "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:

```bash
lsof -i :8088
```

### Verification always fails

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

### Timeout errors

Increase the timeout:

```bash
OBA_TIMEOUT_MS=10000 npx @openbotauth/proxy
```

### Backend not receiving requests

1. Verify `UPSTREAM_URL` is correct
2. Check backend is running and accessible
3. Test direct connection to backend

## Links

* **npm:** <https://www.npmjs.com/package/@openbotauth/proxy>
* **GitHub:** <https://github.com/OpenBotAuth/openbotauth>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.openbotauth.org/proxy/npm.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.