openapi-studio-proxy

Self-hosted execution proxy for OpenAPI Studio — bypass CORS restrictions when testing APIs, with full timing and size metrics.

Quick Start

npx openapi-studio-proxy --token <your-proxy-token>

Generate a proxy token at openapistudio.app/settings?tab=proxyTokens.

Installation

# Run directly (no install)
npx openapi-studio-proxy --port 8787 --token <token>

# Or install globally
npm install -g openapi-studio-proxy
openapi-studio-proxy --port 8787 --token <token>

Options

| Flag | Env Var | Default | Description | |------|---------|---------|-------------| | --port, -p | PROXY_PORT | 8787 | Port to listen on | | --token, -t | PROXY_TOKEN | — | Proxy token from OpenAPI Studio (required) | | --local | — | — | Local mode: validates against http://localhost:4321 | | --dev | — | — | Dev mode: validates against https://dev.openapistudio.com | | --studio-url | OPENAPI_STUDIO_URL | https://openapistudio.app | Custom Studio URL (overrides mode default) | | --allowed-origins | — | Studio + localhost | Comma-separated allowed CORS origins |

Modes

The proxy supports three modes that control which OpenAPI Studio instance it authenticates against.

Production (default)

npx openapi-studio-proxy --token proxy_abc123...

Validates tokens against https://openapistudio.app. Strict TLS — all HTTPS targets must have valid certificates.

Local

npx openapi-studio-proxy --local --token proxy_abc123...

Validates tokens against your local dev server at http://localhost:4321. Run this alongside pnpm dev when developing OpenAPI Studio locally.

• TLS verification disabled — self-signed certs and non-HTTPS targets are accepted
• Extra CORS origins allowed: localhost:4321, localhost:3000, localhost:8788 (+ 127.0.0.1 variants)

Dev / Staging

npx openapi-studio-proxy --dev --token proxy_abc123...

Validates tokens against the staging environment at https://dev.openapistudio.com.

• TLS verification disabled — same relaxed SSL behavior as --local

Custom Studio URL

Use --studio-url to point at any OpenAPI Studio instance. This overrides the URL set by --local or --dev, while keeping the mode's TLS behavior:

# Custom URL with strict TLS (production mode)
npx openapi-studio-proxy --token proxy_abc123... --studio-url https://studio.internal.corp

# Custom URL with relaxed TLS (local mode)
npx openapi-studio-proxy --local --token proxy_abc123... --studio-url http://192.168.1.50:4321

# Custom URL with relaxed TLS (dev mode)
npx openapi-studio-proxy --dev --token proxy_abc123... --studio-url https://staging.example.com

Mode comparison

| | Production | --local | --dev | |---|---|---|---| | Studio URL | https://openapistudio.app | http://localhost:4321 | https://dev.openapistudio.com | | TLS verification | Strict | Disabled | Disabled | | Self-signed certs | Rejected | Accepted | Accepted | | HTTP targets | Allowed | Allowed | Allowed | | Token validation | Required | Required | Required | | /health response | "mode": "production" | "mode": "local" | "mode": "dev" |

Token Management

Proxy tokens are managed in the OpenAPI Studio web UI:

1. Go to Settings > Proxy Tokens (openapistudio.app/settings?tab=proxyTokens)
2. Click Create Token — choose a name and expiry period
3. Copy the token (shown only once) or the ready-to-run setup command
4. Start the proxy with your token

From the same page you can:

• Rotate a token (revokes the old one and issues a new one)
• Revoke a token (proxy disconnects within 5 minutes)
• View usage stats: request count, last used, last IP

Plan limits apply: Free (2 tokens / 30 days), Shipper (10 / 365 days), Fleet (unlimited).

Real-Time Status

Once your proxy is running, OpenAPI Studio tracks its status in real time:

• Heartbeat: The proxy pings Studio every 5 minutes with its URL, version, and uptime
• Online indicator: A green pulse dot appears next to your proxy in Settings and the executor panel
• Cross-tab sync: Status updates propagate via Firebase Firestore — all open tabs and devices see changes instantly
• Executor dropdown: When you select "Private Proxy" mode, a dropdown shows all your proxies with live status (online/offline/unknown)

If the proxy stops or the token is revoked, the status flips to offline within 10 minutes.

Endpoints

GET /health

Returns proxy status:

{
  "status": "ok",
  "version": "1.3.0",
  "mode": "production",
  "uptime": 3600,
  "user": "your-username"
}

In --local or --dev mode, the response also includes studioUrl:

{
  "status": "ok",
  "version": "1.3.0",
  "mode": "local",
  "uptime": 120,
  "user": "dev-user",
  "studioUrl": "http://localhost:4321"
}

POST /execute

Proxies an HTTP request to any target API.

Headers: Authorization: Bearer <token>

Request body:

{
  "url": "https://api.example.com/users",
  "method": "GET",
  "headers": { "Accept": "application/json" },
  "body": null
}

Response: Full response with timing breakdown and size metrics:

{
  "id": "abc123",
  "status": 200,
  "statusText": "OK",
  "headers": { "content-type": "application/json" },
  "body": "{...}",
  "durationMs": 142.5,
  "sizeBytes": 1024,
  "timing": {
    "prepareMs": 0.1,
    "dnsLookupMs": 12.3,
    "tcpHandshakeMs": 15.2,
    "sslHandshakeMs": 22.1,
    "waitingMs": 85.4,
    "downloadingMs": 7.2,
    "totalMs": 142.5
  },
  "sizes": {
    "requestHeaders": 256,
    "requestBody": 0,
    "responseHeaders": 512,
    "responseBody": 1024,
    "responseBodyUncompressed": 1024
  }
}

Deployment

Docker (recommended for servers)

# Pull from GitHub Container Registry
docker pull ghcr.io/omazyai/openapi-studio-proxy:latest

# Run
docker run -d \
  --name openapi-proxy \
  -p 8787:8787 \
  -e PROXY_TOKEN=proxy_abc123... \
  ghcr.io/omazyai/openapi-studio-proxy:latest

Docker Compose

services:
  proxy:
    image: ghcr.io/omazyai/openapi-studio-proxy:latest
    ports:
      - "8787:8787"
    environment:
      - PROXY_TOKEN=proxy_abc123...
    restart: unless-stopped

PM2 (persistent process)

npm install -g openapi-studio-proxy
pm2 start openapi-studio-proxy -- --port 8787 --token proxy_abc123...
pm2 save

Systemd

[Unit]
Description=OpenAPI Studio Proxy
After=network.target

[Service]
ExecStart=/usr/bin/openapi-studio-proxy --port 8787 --token proxy_abc123...
Restart=always
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Publishing (maintainers)

npm

cd packages/openapi-studio-proxy
npm login
npm publish

After publishing, npx openapi-studio-proxy works globally.

Docker image (automated)

Docker images are built and pushed automatically by GitHub Actions on tagged releases:

git tag proxy-v1.3.0
git push origin proxy-v1.3.0

This triggers the proxy-docker.yml workflow which builds and pushes to ghcr.io/omazyai/openapi-studio-proxy with tags: 1.3.0, 1.3, 1, latest.

After the first push, set the package to Public in GitHub Package Settings.

How It Works

Browser (OpenAPI Studio)
  │
  ├─ Browser Fetch (default) ──→ Target API    (may CORS block)
  ├─ Cloud Proxy ($9/mo)     ──→ /api/execute ──→ Target API
  └─ Self-Hosted Proxy (free) ──→ localhost:8787 ──→ Target API
       │
       openapi-studio-proxy (your machine or server)
       ├─ Validates token on startup
       ├─ Heartbeats every 5 min (reports URL, version, IP)
       └─ Forwards requests server-side (no CORS)

The proxy validates your token against OpenAPI Studio on startup, then forwards API requests server-side — avoiding browser CORS restrictions entirely. Responses include detailed timing metrics (DNS lookup, TCP/SSL handshake, TTFB, download) and size breakdowns.

Superadmin Dashboard

System administrators can monitor all proxy tokens across all users at /admin/proxy:

• Total tokens, active proxies (24h), total requests, unique users
• Token table with search by name, email, URL
• Revoke any token (proxy disconnects within 5 minutes)

License

MIT