Skip to main content

​
API Domain Configuration

rs-tunnel needs to know where your API server is hosted. There are three ways to configure this, in order of precedence:

​
1. Command-Line Flag (Highest Priority)

Specify the API domain for a single command using --domain: 
rs-tunnel login --email [email protected] --domain https://api.your-company.com
The --domain flag is Infisical-style: it applies immediately to the current command AND is saved to your local config for future commands.

​
2. Environment Variable

Set a global API domain for all commands in your shell session: 
export RS_TUNNEL_API_URL=https://api.your-company.com
rs-tunnel login --email [email protected]
Legacy alias: RS_TUNNEL_API_BASE_URL is also supported for backward compatibility, but RS_TUNNEL_API_URL is recommended.

​
3. Local Configuration File

The CLI stores the API domain in ~/.rs-tunnel/config.json: 
{
  "apiBaseUrl": "https://api.your-company.com"
}
This file is created automatically:
  • When you use the --domain flag
  • When you’re prompted interactively on first run
For most users, setting the domain once with --domain or via environment variable is sufficient. The CLI remembers it for future commands.

​
Interactive Configuration

On first run without any configured domain, the CLI prompts you: 
rs-tunnel login --email [email protected]
Output: 
No API domain configured for rs-tunnel.
Enter your API domain (press Enter for http://localhost:8080):
Your input is validated and saved to ~/.rs-tunnel/config.json.
Interactive prompts only work in TTY environments. For non-interactive environments (CI/CD, scripts), always use --domain or RS_TUNNEL_API_URL.

​
Configuration Precedence

When multiple configuration sources exist, rs-tunnel uses this order:
  1. --domain flag (command-line argument)
  2. RS_TUNNEL_API_URL (environment variable)
  3. RS_TUNNEL_API_BASE_URL (legacy environment variable)
  4. ~/.rs-tunnel/config.json (local file)
  5. Default: http://localhost:8080
Use rs-tunnel doctor to see which API URL is currently active.

​
Configuration File Structure

The full ~/.rs-tunnel/config.json structure: 
{
  "apiBaseUrl": "https://api.your-company.com"
}
File location: ~/.rs-tunnel/config.json
Permissions: 0600 (owner read/write only)
The config file is created automatically by the CLI. You typically don’t need to edit it manually.

​
Environment Variables

rs-tunnel recognizes these environment variables:

​
Client-Side (CLI)

RS_TUNNEL_API_URL

Purpose: API server base URL
Example: https://api.your-company.com
Default: http://localhost:8080
Recommended: Use this for all new configurations

RS_TUNNEL_API_BASE_URL

Purpose: Legacy alias for RS_TUNNEL_API_URL
Status: Supported for backward compatibility
Recommendation: Migrate to RS_TUNNEL_API_URL

​
Server-Side (API)

These are configured on the API server, not the CLI:

ALLOWED_EMAIL_DOMAIN

Restricts logins to specific email domain
Example: @example.com

ALLOWED_SLACK_TEAM_ID

Restricts logins to specific Slack workspace
Example: T01234567

MAX_ACTIVE_TUNNELS

Maximum tunnels per user
Default: 5

HEARTBEAT_INTERVAL_SEC

How often CLI sends heartbeats
Default: 20 seconds
Server-side variables are set in the API deployment environment. CLI users cannot override them.

​
Credential Storage

Authentication credentials are stored separately from configuration: If the optional keytar dependency is installed:
  • Service: rs-tunnel
  • Account: default
  • Storage: System credential manager (Keychain, Secret Service, Credential Vault)

​
Fallback Encryption

Without keytar:
  • Encrypted data: ~/.rs-tunnel/session.enc (permissions: 0600)
  • Encryption key: ~/.rs-tunnel/session.key (permissions: 0600)
  • Algorithm: AES-256-GCM
For best security, install keytar:
npm install -g @ripeseed/rs-tunnel keytar

​
Self-Hosted Deployments

For organizations running their own rs-tunnel API:

​
Initial Setup

# Set API domain globally
export RS_TUNNEL_API_URL=https://tunnel-api.your-company.com

# Or use --domain on first login
rs-tunnel login --email [email protected] --domain https://tunnel-api.your-company.com

​
Team Onboarding

Provide team members with:
  1. API domain URL
  2. Installation instructions:
npm install -g @ripeseed/rs-tunnel
export RS_TUNNEL_API_URL=https://tunnel-api.your-company.com
rs-tunnel login --email [email protected]
After initial configuration, team members won’t need to specify --domain for subsequent commands.

​
Configuration Directory

The ~/.rs-tunnel/ directory contains: 
~/.rs-tunnel/
├── config.json          # API domain configuration
├── session.enc          # Encrypted credentials (fallback storage)
├── session.key          # Encryption key (fallback storage)
└── bin/
    └── cloudflared      # Downloaded cloudflared binary
Directory permissions: 0700 (owner access only)
File permissions: 0600 (owner read/write only)
Do not commit ~/.rs-tunnel/ to version control. It contains sensitive credentials.

​
Examples

​
Development Environment

# Point to local API during development
export RS_TUNNEL_API_URL=http://localhost:8080
rs-tunnel login --email [email protected]

​
Production Environment

# Point to production API
export RS_TUNNEL_API_URL=https://api.tunnel.example.com
rs-tunnel login --email [email protected]

​
Switching Between Environments

# Use local API
RS_TUNNEL_API_URL=http://localhost:8080 rs-tunnel list

# Use production API
RS_TUNNEL_API_URL=https://api.example.com rs-tunnel list

​
Persistent Configuration

# Add to ~/.bashrc or ~/.zshrc
echo 'export RS_TUNNEL_API_URL=https://api.your-company.com' >> ~/.bashrc
source ~/.bashrc

# Now all commands use your company's API
rs-tunnel login --email [email protected]
rs-tunnel up --port 3000

​
Verify Configuration

Check which API domain is active: 
rs-tunnel doctor
Output shows active configuration: 
OS: linux x64 (supported)
API (https://api.your-company.com): reachable
Auth session: present ([email protected])
cloudflared: found at /home/user/.rs-tunnel/bin/cloudflared (2024.12.0)

​
Next Steps

Troubleshooting

Solve common configuration issues

Creating Tunnels

Start using rs-tunnel

Build docs developers (and LLMs) love

Get started for freeTalk to us