CGrok Client - Self-Hosted Tunneling CLI Tool

CLI client for self-hosted secure HTTPS tunneling. Expose your local servers to the internet through your own cgrok-server. Complete control, custom domains, zero vendor lock-in.

🚀 This is the client component. Install cgrok-server on your VPS/server to complete your self-hosted tunneling infrastructure.

🔥 Perfect for: Self-hosted infrastructure, custom domain tunneling, webhook testing, team collaboration, localhost sharing without third-party services

✨ Key Features

• 🔧 Advanced Configuration Management: Supports persistent config file (~/.cgrok/config.json), environment variables, and CLI arguments with hierarchical priority
• 📊 Real-Time Metrics: Track requests, average response times, success rates, and requests per minute
• 🔄 Intelligent Auto-Reconnection: Retry system with configurable exponential backoff (up to 10 attempts by default)
• 🌐 Custom Subdomains: Request specific subdomains for your tunnels (requires server support)
• 🗜️ Built-in Compression: Data compression enabled by default for optimized performance
• 🔐 Robust Authentication: Support for authentication tokens with server-side validation
• 📝 Detailed Logging: Verbose mode for debugging with timestamps and event categorization
• 🎨 Interactive UI: Interface with spinners, colors, and real-time metrics visualization
• ⚡ Optimized Performance: Built with TypeScript, optimized for low latency
• 🛡️ Error Handling: Robust error management with configurable timeouts and automatic recovery

🎯 What is CGrok?

CGrok is a complete self-hosted tunneling solution consisting of two components:

1. cgrok (this package) - CLI client you install on your development machine
2. cgrok-server - Server you deploy on your VPS/cloud

Together, they provide a 100% self-hosted alternative to ngrok, giving you:

• ✅ Full control over your infrastructure
• ✅ Custom domains (your-app.yourdomain.com)
• ✅ No usage limits or paid tiers
• ✅ Privacy - your traffic stays on your servers
• ✅ Team sharing - multiple developers, one server

🔧 Client Configuration

The cgrok client supports multiple configuration methods with the following priority order:

Priority (highest to lowest): CLI Arguments → Environment Variables → Configuration File

Note: serverUrl is required and has no default value. Configure it using cgrok --setup or set the CGROK_SERVER_URL environment variable.

Configuration File

The client stores configuration at ~/.cgrok/config.json. Server URL is required - configure it using --setup or manually edit the file:

{
  "serverUrl": "wss://tunnel.yourdomain.com/_tunnel",
  "maxReconnectAttempts": 10,
  "reconnectDelay": 1000,
  "maxReconnectDelay": 30000,
  "requestTimeout": 30000,
  "verbose": false,
  "enableCompression": true
}

Environment Variables

# Required
export CGROK_SERVER_URL="wss://tunnel.yourdomain.com/_tunnel"

# Optional
export CGROK_PORT="3000"
export CGROK_AUTH_TOKEN="your_token"
export CGROK_SUBDOMAIN="my-app"
export CGROK_VERBOSE="true"
export CGROK_ENABLE_COMPRESSION="true"
export CGROK_MAX_RECONNECT_ATTEMPTS="10"
export CGROK_RECONNECT_DELAY="1000"
export CGROK_MAX_RECONNECT_DELAY="30000"
export CGROK_REQUEST_TIMEOUT="30000"

CLI Arguments

cgrok --port 3000 \
  --server wss://tunnel.yourdomain.com/_tunnel \
  --token your_token \
  --subdomain my-app \
  --verbose

🚀 Why CGrok Client?

vs. Third-Party Services (ngrok, etc.)

| Feature | CGrok (Self-Hosted) | ngrok Free | ngrok Paid | |---------|---------------------|------------|------------| | Custom domains | ✅ Unlimited | ❌ No | ✅ Limited | | Data privacy | ✅ Your servers | ❌ Third-party | ❌ Third-party | | Cost | ✅ Free (hosting only) | ⚠️ Limited | 💰 $8-65/mo | | Request limits | ✅ None | ❌ 40/min | ⚠️ Varies | | Connection time | ✅ Unlimited | ❌ 2hrs | ✅ Unlimited | | Team sharing | ✅ Free | ❌ No | 💰 Extra cost | | Real-time metrics | ✅ Included | ❌ No | ⚠️ Limited | | Auto-reconnection | ✅ Yes (configurable) | ⚠️ Basic | ⚠️ Basic |

vs. Other Self-Hosted Solutions

• ⚡ High Performance - Optimized for low latency tunneling
• 🎯 Simpler than Cloudflare Tunnel - No complex setup
• 🛠️ More flexible than localtunnel - Custom subdomains + authentication
• 📦 Lighter than traefik - Specifically for development tunneling
• 📊 Built-in metrics - Real-time tracking without additional tools
• 🔄 Smart reconnection - Configurable exponential backoff

⚡ Quick Start (5 minutes)

Prerequisites

You need a server running cgrok-server. If you don't have one:

Option A: Quick Deploy (Recommended)

# On your VPS (Ubuntu/Debian)
npx cgrok-server setup --domain tunnel.yourdomain.com

Option B: Manual Setup See cgrok-server installation guide

Install Client

# Install globally
npm install -g @crisego/cgrok

# Or with Yarn
yarn global add @crisego/cgrok

# Or with pnpm
pnpm add -g @crisego/cgrok

Connect to Your Server

# First, configure your client (required)
cgrok --setup

# Then start tunnel with just the port
cgrok --port 3000

# Or specify server URL directly
cgrok --port 3000 --server wss://tunnel.yourdomain.com/_tunnel

# Or use environment variable
export CGROK_SERVER_URL=wss://tunnel.yourdomain.com/_tunnel
cgrok --port 3000

# With custom subdomain
cgrok --port 3000 --subdomain my-app

# With verbose mode for debugging
cgrok --port 3000 --verbose

# With all options
cgrok --port 3000 \
  --server wss://tunnel.yourdomain.com/_tunnel \
  --token your_secret_token \
  --subdomain my-app \
  --verbose

Access Your App

🌐 Your app is available at: https://abc123.tunnel.yourdomain.com
📊 Real-time metrics updating every 5 seconds
✨ Auto-reconnection enabled

That's it! Your local app is now accessible on your custom domain. 🎉

📊 Metrics and Monitoring

The cgrok client includes a real-time metrics system that shows you:

• Total Requests: Cumulative counter of all requests
• Successful/Failed Requests: Breakdown of successful responses vs errors
• Success Rate: Percentage of successful requests
• Average Response Time: Mean latency of requests
• Requests per Minute: Real-time traffic rate
• Last Request: Timestamp of the last processed request

The UI automatically updates every 5 seconds showing these metrics in an attractive visual format.

🏗️ Architecture

Flow:

1. cgrok client connects to cgrok-server via WebSocket (WSS)
2. Server assigns subdomain (e.g., abc123.tunnel.yourdomain.com)
3. Internet requests hit cgrok-server
4. Server forwards to cgrok client through the WebSocket
5. Client proxies to localhost:3000
6. Response flows back through the same path

Connection Features:

• 🔄 Auto-reconnection with exponential backoff
• 📊 Real-time performance metrics
• 🗜️ Data compression to reduce latency
• 🔐 Token authentication
• ⏱️ Configurable timeouts per request

📋 Complete Setup Guide

1. Server Setup (One-Time)

First, deploy cgrok-server on your VPS:

# SSH into your server
ssh [email protected]

# Install cgrok-server
npm install -g @crisego/cgrok-server

# Setup with your domain
cgrok-server setup --domain tunnel.yourdomain.com

# Start server
cgrok-server start

See cgrok-server documentation for details.

2. DNS Configuration

Point your domain to your server:

# A Record
*.tunnel.yourdomain.com → YOUR_SERVER_IP

# Or specific subdomain
tunnel.yourdomain.com → YOUR_SERVER_IP

3. Client Installation & Usage

Method 1: Configuration File (Recommended)

# Install client
npm install -g @crisego/cgrok

# Run setup to configure server URL and other options
cgrok --setup

# Or manually create/edit ~/.cgrok/config.json
nano ~/.cgrok/config.json

# Required configuration:
{
  "serverUrl": "wss://tunnel.yourdomain.com/_tunnel",
  "verbose": true,
  "enableCompression": true,
  "maxReconnectAttempts": 10,
  "reconnectDelay": 1000,
  "requestTimeout": 30000
}

# Now run normally
cgrok

Method 2: Environment Variables

# Configure in your .bashrc or .zshrc
export CGROK_SERVER_URL=wss://tunnel.yourdomain.com/_tunnel
export CGROK_AUTH_TOKEN=your_secret_token
export CGROK_SUBDOMAIN=my-app
export CGROK_VERBOSE=true

# Run
cgrok --port 3000

Method 3: CLI Arguments

cgrok --port 3000 \
  --server wss://tunnel.yourdomain.com/_tunnel \
  --token your_secret_token \
  --subdomain my-app \
  --verbose

🎯 Use Cases

Development Teams

# Developer 1 (Backend API)
cgrok --port 8000 --subdomain api

# Developer 2 (Frontend)
cgrok --port 3000 --subdomain app

# Developer 3 (Testing)
cgrok --port 4000 --subdomain staging

Everyone shares: tunnel.yourcompany.com

Webhook Development

# Expose webhook endpoint
cgrok --port 3000 --verbose

# Use in Stripe/GitHub/Slack webhooks
# https://abc123.tunnel.yourdomain.com/webhooks

# See real-time logs with --verbose

Client Demos

# Show work to client
cgrok --port 8080 --subdomain client-demo

# Share: https://client-demo.tunnel.yourdomain.com

IoT & Home Lab

# Expose local devices
cgrok --port 8123 --subdomain home-assistant

# Secure remote access to your local network

API Testing

# Test local API with external services
cgrok --port 5000 --subdomain api-test --verbose

# View real-time performance metrics
# Debugging with detailed logs

🔧 Advanced Configuration Options

Auto-Reconnection

The client includes a smart reconnection system:

{
  "maxReconnectAttempts": 10,      // Maximum attempts
  "reconnectDelay": 1000,          // Initial delay (ms)
  "maxReconnectDelay": 30000       // Maximum delay (ms)
}

Behavior:

• Exponential backoff: 1s → 2s → 4s → 8s → 16s → 30s (max)
• Automatic counter reset on successful connection
• Detailed logs of each attempt in verbose mode

Timeouts and Performance

{
  "requestTimeout": 30000,          // Timeout per request (ms)
  "enableCompression": true         // Data compression
}

Logging and Debugging

# Verbose mode for debugging
cgrok --port 3000 --verbose

# Logs include:
# - Timestamps for each event
# - Connection metrics
# - Details of each request
# - Errors with stack traces
# - Reconnection status

# Access home server from anywhere
cgrok --port 8080 --token secure_token

# Monitor home automation
cgrok --port 1880 --subdomain homeassistant

📖 Complete Usage Guide

Command Line Options

Usage: cgrok --port PORT [options]

Required:
  --port PORT       Local port to tunnel (e.g., 3000, 8080)

Server Connection:
  --server URL      Server URL (required, no default)
                    Format: wss://tunnel.yourdomain.com/_tunnel
  --token TOKEN     Authentication token (if server requires)

Customization:
  --subdomain NAME  Custom subdomain (requires server support)
                    Example: --subdomain myapp
                    Results in: https://myapp.tunnel.yourdomain.com

Setup & Configuration:
  --setup           Run interactive configuration setup
  -v, --verbose     Enable detailed logging
  -h, --help        Show this help message

Examples:
  # First time setup
  cgrok --setup

  # Basic usage (after setup)
  cgrok --port 3000

  # With custom server
  cgrok --port 8080 --server wss://tunnel.example.com/_tunnel

  # With authentication
  cgrok --port 3000 --token my_secret_token

  # Custom subdomain
  cgrok --port 3000 --subdomain myapp

  # All options
  cgrok --port 8080 --server wss://tunnel.example.com/_tunnel \
        --token secret --subdomain api --verbose

Environment Variables

Create .env or export in shell:

# Server configuration
CGROK_SERVER_URL=wss://tunnel.yourdomain.com/_tunnel
CGROK_AUTH_TOKEN=your_secret_token_here
CGROK_SUBDOMAIN=your_preferred_subdomain

# Connection settings
CGROK_MAX_RECONNECT_ATTEMPTS=10
CGROK_RECONNECT_DELAY=1000
CGROK_MAX_RECONNECT_DELAY=30000
CGROK_REQUEST_TIMEOUT=30000

# Features
CGROK_VERBOSE=false
CGROK_ENABLE_COMPRESSION=true

Configuration Priority

1. Command-line arguments (highest)
2. Environment variables
3. Configuration file
4. Note: serverUrl is required and has no default value

🔒 Security & Authentication

Token-Based Auth

If your cgrok-server requires authentication:

# Method 1: Command line
cgrok --port 3000 --token your_secret_token

# Method 2: Environment variable
export CGROK_AUTH_TOKEN=your_secret_token
cgrok --port 3000

# Method 3: .env file
echo "CGROK_AUTH_TOKEN=your_secret_token" > .env
cgrok --port 3000

Secure Practices

• ✅ Use strong tokens for production servers
• ✅ Enable HTTPS on cgrok-server (automatic with Let's Encrypt)
• ✅ Limit access with firewall rules
• ✅ Use custom subdomains for team organization
• ✅ Rotate tokens periodically
• ⚠️ Don't commit tokens to git

📊 Features

🔧 Core Tunneling

• ✅ Automatic HTTPS with custom domains
• ✅ WebSocket-based communication
• ✅ Binary content support (images, PDFs, files)
• ✅ Auto-reconnection with exponential backoff
• ✅ Compression support (gzip, deflate, brotli)

🌐 Connectivity

• ✅ Heartbeat ping/pong for connection health
• ✅ Configurable timeouts
• ✅ Automatic service detection
• ✅ Smart error handling

📈 Monitoring

• ✅ Real-time statistics (requests, errors, latency)
• ✅ Verbose logging mode
• ✅ Performance metrics
• ✅ Connection health monitoring

⚙️ Configuration

• ✅ Environment variables
• ✅ Command-line options
• ✅ Token authentication
• ✅ Custom subdomain support

🔍 Self-Hosted Benefits

Full Control

• Host on your infrastructure
• Custom SSL certificates
• Your own domain names
• No third-party dependencies

Cost Savings

• No monthly subscriptions
• Unlimited connections
• Unlimited bandwidth (server limits only)
• Free for unlimited team members

Privacy

• Your data never leaves your servers
• No analytics sent to third parties
• GDPR/HIPAA friendly
• Complete audit trail

Customization

• Modify client and server as needed
• Integrate with your tools
• Custom authentication
• Team-specific features

🚨 Troubleshooting

Connection Issues

# Test server connectivity
curl https://tunnel.yourdomain.com/health

# Check DNS
nslookup tunnel.yourdomain.com

# Verify WebSocket
wscat -c wss://tunnel.yourdomain.com/_tunnel

# Enable debug logging
cgrok --port 3000 --verbose

Common Errors

Error: Server URL is required

# Run setup to configure server URL
cgrok --setup

# Or set environment variable
export CGROK_SERVER_URL="wss://tunnel.yourdomain.com/_tunnel"

# Or pass as argument
cgrok --port 3000 --server wss://tunnel.yourdomain.com/_tunnel

Error: Connection refused

# Check if server is running
ssh user@server "systemctl status cgrok-server"

# Verify firewall allows WSS (port 443)

Error: No service on port

# Start your app first
npm run dev  # or your start command

# Then start cgrok
cgrok --port 3000

Error: Authentication failed

# Verify token matches server config
cgrok --port 3000 --token correct_token --verbose

📦 Related Packages

• cgrok-server - Server component (required)
• Coming soon: cgrok-web - Web UI for server management

🤝 Contributing

Contributions welcome! This is a community project.

# Fork and clone
git clone https://github.com/cristiangonsevi/cgrok.git
cd cgrok

# Install dependencies
npm install

# Make changes
# ...

# Test locally
npm run dev

# Build
npm run build

# Submit PR

📄 License

MIT License - see LICENSE file.

🔗 Links

• Client (this repo): github.com/cristiangonsevi/cgrok
• Server: github.com/cristiangonsevi/cgrok-server
• npm Package: npmjs.com/package/cgrok
• Issues: github.com/cristiangonsevi/cgrok/issues
• Author: Cristian Gonzalez

⭐ If CGrok helps you, please star both repos! ⭐

Made with ❤️ for the self-hosting community

Client Repo • Server Repo • Documentation