Skip to main content

Quick Start

Get up and running with gTunnel in minutes! This guide will walk you through installing and setting up a basic HTTP tunnel.

Installation​

Run our automated installation script:

curl -sSL https://raw.githubusercontent.com/B-AJ-Amar/gTunnel/main/scripts/install.sh | bash

This installs the client component only (default). For specific components:

# Client only (default)
curl -sSL https://raw.githubusercontent.com/B-AJ-Amar/gTunnel/main/scripts/install.sh | bash

# Server only  
curl -sSL https://raw.githubusercontent.com/B-AJ-Amar/gTunnel/main/scripts/install.sh | bash -s server

# Both client and server
curl -sSL https://raw.githubusercontent.com/B-AJ-Amar/gTunnel/main/scripts/install.sh | bash -s both

Manual Installation​

Download the latest release from GitHub Releases:

# Download and extract (replace VERSION with latest)
wget https://github.com/B-AJ-Amar/gTunnel/releases/download/v0.0.0/gtunnel-client_linux_amd64.tar.gz
tar -xzf gtunnel-client_linux_amd64.tar.gz
sudo mv gtc /usr/local/bin/

Basic Usage​

1. Start the Server​

First, start a gTunnel server:

gts start --bind-address 0.0.0.0:7205

The server will start and display:

🚀 gTunnel Server started on 0.0.0.0:7205

2. Start Your Local Service​

In another terminal, start the service you want to expose. For example, a simple HTTP server:

# Python
python -m http.server 3000

# Node.js  
npx serve -p 3000

# Go
cd your-app && go run main.go

3. Connect the Client​

Connect your local service to the gTunnel server:

gtc connect -u localhost:7205 3000

You'll see output like:

✅ Connected to gTunnel server
🌐 Your service is now accessible at: http://localhost:7205/tunnel/abc123

4. Access Your Service​

Your local service is now accessible through the tunnel! Open the provided URL in your browser or share it with others.

Docker Usage​

Using Docker Compose​

Create a docker-compose.yml:

version: '3.8'
services:
  gtunnel-server:
    image: ghcr.io/b-aj-amar/gtunnel-server:latest
    ports:
      - "7205:7205"
    command: ["start", "--bind-address", "0.0.0.0:7205"]

  gtunnel-client:
    image: ghcr.io/b-aj-amar/gtunnel-client:latest
    depends_on:
      - gtunnel-server
    environment:
      - GTUNNEL_SERVER_URL=http://gtunnel-server:7205
      - GTUNNEL_TARGET_HOST=your-app
      - GTUNNEL_TARGET_PORT=3000

Run with:

docker-compose up

Individual Docker Containers​

# Start server
docker run -p 7205:7205 ghcr.io/b-aj-amar/gtunnel-server:latest start --bind-address 0.0.0.0:7205

# Start client
docker run ghcr.io/b-aj-amar/gtunnel-client:latest connect -u host.docker.internal:7205 3000

Common Use Cases​

Expose Local Development Server​

Perfect for sharing your work-in-progress with team members:

# Start your dev server
npm run dev  # Usually runs on localhost:3000

# Tunnel it
gtc connect -u your-server:7205 3000

Testing Webhooks​

Test webhooks locally during development:

# Your webhook endpoint
gtc connect -u tunnel.yourcompany.com:7205 4000

Remote Access to Services​

Access services running on remote machines:

# On remote machine
gtc connect -u tunnel-server:7205 8080

Next Steps​

Need Help?​

Ready to dive deeper? Explore our comprehensive documentation for advanced features and configuration options.