Skip to main content
Before deploying rs-tunnel, ensure you have the following prerequisites in place.

​
System Requirements

Node.js 20+

rs-tunnel requires Node.js version 20 or higher for modern JavaScript features and optimal performance.

pnpm 10

Package manager for monorepo workspace management. Version 10.0.0 or higher is required.

Docker

Required for running PostgreSQL database locally or in production.

PostgreSQL 16+

Database for storing users, tunnels, leases, and metrics. Recommended via Docker using postgres:16-alpine.
1

Install Node.js 20+

Download and install Node.js from nodejs.org or use a version manager like nvm:
nvm install 20
nvm use 20
Verify installation:
node --version
# Should output v20.x.x or higher
2

Install pnpm 10

Install pnpm globally:
npm install -g pnpm@10
Or enable via corepack:
corepack enable
corepack prepare [email protected] --activate
Verify installation:
pnpm --version
# Should output 10.0.0 or higher
3

Install Docker

Install Docker Desktop or Docker Engine:Verify installation:
docker --version
docker compose version

​
Slack App Configuration

rs-tunnel uses Slack OpenID Connect for authentication. You must create and configure a Slack app.
Only users with emails matching ALLOWED_EMAIL_DOMAIN and from the ALLOWED_SLACK_TEAM_ID workspace will be able to authenticate.
1

Create a Slack App

  1. Go to api.slack.com/apps
  2. Click Create New App
  3. Choose From scratch
  4. Enter app name (e.g., “rs-tunnel”)
  5. Select your workspace
2

Enable Sign in with Slack

  1. Navigate to OAuth & Permissions
  2. Under Redirect URLs, add: 
    http://localhost:8080/v1/auth/slack/callback
    For production, use your actual API base URL: 
    https://api.yourdomain.com/v1/auth/slack/callback
  3. Scroll to Scopes and add:
    • openid
    • profile
    • email
3

Get Client Credentials

  1. Go to Basic Information
  2. Copy Client ID → This is your SLACK_CLIENT_ID
  3. Copy Client Secret → This is your SLACK_CLIENT_SECRET
  4. Note your Slack Team ID (starts with T)
To find your Slack Team ID:
  1. Open Slack in a browser
  2. The URL will be https://app.slack.com/client/T123456789/...
  3. T123456789 is your team ID

​
Cloudflare Account Setup

rs-tunnel manages Cloudflare Tunnels and DNS records programmatically.
1

Cloudflare Account

Create a Cloudflare account at cloudflare.com if you don’t have one.
2

Add a Domain

  1. Add your domain to Cloudflare
  2. Update your domain’s nameservers to Cloudflare’s nameservers
  3. Wait for DNS propagation (usually 5-30 minutes)
3

Get Account and Zone IDs

  1. Go to your domain overview in Cloudflare dashboard
  2. Scroll down to API section on the right sidebar
  3. Copy Zone ID → This is your CLOUDFLARE_ZONE_ID
  4. Copy Account ID → This is your CLOUDFLARE_ACCOUNT_ID
4

Create API Token

You need a token with specific permissions:
  1. Go to My Profile → API Tokens
  2. Click Create Token
  3. Use Custom token template
  4. Add these permissions:
    • Zone → DNS → Edit
    • Account → Cloudflare Tunnel → Edit
  5. Set Zone Resources:
    • Include → Specific zone → Select your domain
  6. Set Account Resources:
    • Include → Your account
  7. Click Continue to summary → Create Token
  8. Copy the token → This is your CLOUDFLARE_API_TOKEN
Store your Cloudflare API token securely. It will only be shown once. The API requires least-privilege access (Tunnel + DNS only).

​
Security Requirements

All provider secrets (Cloudflare API token, Slack secrets, JWT secrets) must only exist in the API runtime environment. The CLI never holds these credentials.

​
Generate JWT Secrets

You need strong random secrets for JWT signing: 
# Generate JWT_SECRET (minimum 16 characters)
openssl rand -base64 32

# Generate REFRESH_TOKEN_SECRET (minimum 16 characters)
openssl rand -base64 32
Never commit secrets to version control. Use environment variables or a secrets manager.

​
Access Policy Requirements

rs-tunnel enforces strict access controls:
  1. Email Domain Restriction: Only emails ending in ALLOWED_EMAIL_DOMAIN can authenticate
  2. Slack Workspace Restriction: Only users from ALLOWED_SLACK_TEAM_ID workspace can authenticate
  3. Max Active Tunnels: Each user is limited to MAX_ACTIVE_TUNNELS (default: 5) concurrent tunnels
For single-organization deployments, set [email protected] and ALLOWED_SLACK_TEAM_ID to your workspace’s team ID.

​
Network Requirements

  • Port 8080: API server (configurable via PORT)
  • Port 5432: PostgreSQL (if running locally)
  • Outbound HTTPS: API needs access to:
    • slack.com for OAuth
    • api.cloudflare.com for tunnel/DNS management
  • Inbound HTTPS: Your API base URL must be accessible by CLI clients

​
Next Steps

Environment Variables

Configure all required environment variables

Docker Setup

Set up PostgreSQL and API containers

Build docs developers (and LLMs) love

Get started for freeTalk to us