drip/README.md

# Drip - Fast Tunnels to Localhost

Self-hosted tunneling solution. Expose your localhost to the internet securely.

[中文文档](README_CN.md)

[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go)](https://golang.org/)
[![License](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](LICENSE)
[![TLS](https://img.shields.io/badge/TLS-1.3-green.svg)](https://tools.ietf.org/html/rfc8446)

## Why?

**Control your data.** No third-party servers means your traffic stays between your client and your server.

**No limits.** Run as many tunnels as you need, use as much bandwidth as your server can handle.

**Actually free.** Use your own domain, no paid tiers or feature restrictions.

| Feature | Drip | ngrok Free |
|---------|------|------------|
| Privacy | Your infrastructure | Third-party servers |
| Domain | Your domain | 1 static subdomain |
| Bandwidth | Unlimited | 1 GB/month |
| Active Endpoints | Unlimited | 1 endpoint |
| Tunnels per Agent | Unlimited | Up to 3 |
| Requests | Unlimited | 20,000/month |
| Interstitial Page | None | Yes (removable with header) |
| Open Source | ✓ | ✗ |

## Quick Install

### Client (macOS/Linux)

```bash
bash <(curl -sL https://raw.githubusercontent.com/Gouryella/drip/refs/heads/main/scripts/install.sh)
```

### Server (Linux)

```bash
bash <(curl -sL https://raw.githubusercontent.com/Gouryella/drip/refs/heads/main/scripts/install-server.sh)
```

## Usage

### Basic Tunnels

```bash
# Expose local HTTP server
drip http 3000

# Expose local HTTPS server
drip https 443

# Pick your subdomain
drip http 3000 --subdomain myapp
# → https://myapp.your-domain.com

# Expose TCP service (database, SSH, etc.)
drip tcp 5432
```

### Forward to Any Address

Not just localhost - forward to any device on your network:

```bash
# Forward to another machine on LAN
drip http 8080 --address 192.168.1.100

# Forward to Docker container
drip http 3000 --address 172.17.0.2

# Forward to specific interface
drip http 3000 --address 10.0.0.5
```

### Daemon Mode

Run tunnels in the background:

```bash
# Start tunnel as daemon
drip daemon start http 3000
drip daemon start https 8443 --subdomain api

# Manage daemons
drip daemon list
drip daemon stop http-3000
drip daemon logs http-3000
```

## Server Deployment

### Prerequisites

- A domain with DNS pointing to your server (A record)
- Wildcard DNS for subdomains: `*.tunnel.example.com -> YOUR_IP`
- SSL certificate (wildcard recommended)

### Option 1: Direct (Recommended)

Drip server handles TLS directly on port 443:

```bash
# Get wildcard certificate
sudo certbot certonly --manual --preferred-challenges dns \
  -d "*.tunnel.example.com" -d "tunnel.example.com"

# Start server
drip-server \
  --port 443 \
  --domain tunnel.example.com \
  --tls-cert /etc/letsencrypt/live/tunnel.example.com/fullchain.pem \
  --tls-key /etc/letsencrypt/live/tunnel.example.com/privkey.pem \
  --token YOUR_SECRET_TOKEN
```

### Option 2: Behind Nginx

Run Drip on port 8443, let Nginx handle SSL termination:

```nginx
server {
    listen 443 ssl http2;
    server_name *.tunnel.example.com;

    ssl_certificate /etc/letsencrypt/live/tunnel.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/tunnel.example.com/privkey.pem;

    location / {
        proxy_pass https://127.0.0.1:8443;
        proxy_ssl_verify off;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
    }
}
```

### Systemd Service

The install script creates `/etc/systemd/system/drip-server.service` automatically. Manage with:

```bash
sudo systemctl start drip-server
sudo systemctl enable drip-server
sudo journalctl -u drip-server -f
```

## Features

**Security**
- TLS 1.3 encryption for all connections
- Token-based authentication
- No legacy protocol support

**Flexibility**
- HTTP, HTTPS, and TCP tunnels
- Forward to localhost or any LAN address
- Custom subdomains or auto-generated
- Daemon mode for persistent tunnels

**Performance**
- Binary protocol with msgpack encoding
- Connection pooling and reuse
- Minimal overhead between client and server

**Simplicity**
- One-line installation
- Save config once, use everywhere
- Real-time connection stats

## Architecture

```
┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│   Internet  │ ──────> │    Server    │ <────── │   Client    │
│   User      │  HTTPS  │    (Drip)    │ TLS 1.3 │  localhost  │
└─────────────┘         └──────────────┘         └─────────────┘
```

## Common Use Cases

**Development & Testing**
```bash
# Show local dev site to client
drip http 3000

# Test webhooks from services like Stripe
drip http 8000 --subdomain webhooks
```

**Home Server Access**
```bash
# Access home NAS remotely
drip http 5000 --address 192.168.1.50

# Remote into home network
drip tcp 22
```

**Docker & Containers**
```bash
# Expose containerized app
drip http 8080 --address 172.17.0.3

# Database access for debugging
drip tcp 5432 --address db-container
```

## Command Reference

```bash
# HTTP tunnel
drip http <port> [flags]
  --subdomain, -n    Custom subdomain
  --address, -a      Target address (default: 127.0.0.1)
  --server           Server address
  --token            Auth token

# HTTPS tunnel
drip https <port> [flags]

# TCP tunnel
drip tcp <port> [flags]

# Daemon commands
drip daemon start <type> <port> [flags]
drip daemon list
drip daemon stop <name>
drip daemon logs <name>

# Configuration
drip config init
drip config show
```

## License

BSD 3-Clause License - see [LICENSE](LICENSE) for details