Tunnel through barriers, instantly

Expose localhost to the internet. One command. Zero config.
_{Open source - Self-hostable - Enterprise security - Free forever}

pip install instanton && instanton --port 8000

That's it. You now have a public HTTPS URL. No signup. No config files.

Quick Start - Features - Python SDK - Deployment - Configuration

The Problem

You're building something awesome on localhost:8000. Now you need to:

• Share it with a client
• Test webhooks from Stripe/GitHub
• Demo to your team
• Debug a mobile app

The old way: Port forwarding, firewall rules, dynamic DNS, SSL certificates, nginx configs...

The Instanton way:

instanton --port 8000

  Instanton v1.0.0

  Tunnel established!

  Public URL:  https://abc123.instanton.tech
  Forwarding:  https://abc123.instanton.tech -> http://localhost:8000

  Press Ctrl+C to stop

Quick Start

Installation

pip install instanton

HTTP Tunnel

# Basic - expose port 8000
instanton --port 8000

# Custom subdomain
instanton --port 8000 --subdomain myapp

# With traffic inspector
instanton --port 8000 --inspect

TCP Tunnel (Databases, SSH)

# PostgreSQL
instanton tcp 5432

# MySQL
instanton tcp 3306

# SSH
instanton tcp 22

UDP Tunnel (Gaming, VoIP, DNS)

# Game server
instanton udp 27015

# DNS
instanton udp 53

Python SDK

import instanton

# Async context manager
async with instanton.forward(8000) as tunnel:
    print(f"Public URL: {tunnel.url}")
    # Your app is now accessible at tunnel.url
    await your_app.run()

# Sync API
tunnel = instanton.forward_sync(8000)
print(tunnel.url)

Long-Running APIs (AI, Streaming)

# No timeout - perfect for AI inference, video streaming
instanton --port 8000 --no-request-timeout

Features

Scalability

Instanton is designed to handle thousands of concurrent users:

• Unique subdomain generation: 12-character hex subdomains with 48 bits of entropy
  • Probability of collision for 10,000 tunnels: < 0.00002%
• Efficient port allocation: TCP (10000-19999), UDP (20000-29999)
• Fast tunnel lookups: O(1) dictionary operations
• Memory efficient: Minimal per-connection overhead

Zero Trust Security

╔═══════════════════════════════════════════════════════════════════════════════╗
║                         ZERO TRUST ARCHITECTURE                                ║
║                        "Never Trust, Always Verify"                            ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║                                                                               ║
║   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐   ║
║   │   IDENTITY  │───▶│   DEVICE    │───▶│    RISK     │───▶│   ACCESS    │   ║
║   │   VERIFY    │    │   POSTURE   │    │   SCORE     │    │  DECISION   │   ║
║   └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘   ║
║        Who?             What?             How risky?         Allow/Deny       ║
║                                                                               ║
╚═══════════════════════════════════════════════════════════════════════════════╝

                              TRUST LEVELS & ACCESS RIGHTS
    ╔═══════════════════════════════════════════════════════════════════════════╗
    ║                                                                           ║
    ║   UNTRUSTED ──▶ LOW ──▶ MEDIUM ──▶ HIGH ──▶ VERIFIED                     ║
    ║       │          │         │         │          │                         ║
    ║       ▼          ▼         ▼         ▼          ▼                         ║
    ║    ┌──────┐  ┌───────┐  ┌───────┐  ┌───────┐  ┌───────┐                  ║
    ║    │BLOCK │  │Limited│  │Standard│ │Extended│ │ Full  │                  ║
    ║    │  ✗   │  │Access │  │ Access │ │ Access │ │Access │                  ║
    ║    └──────┘  └───────┘  └───────┘  └───────┘  └───────┘                  ║
    ║                                                                           ║
    ╚═══════════════════════════════════════════════════════════════════════════╝

Architecture

┌─────────────────────────────────────────────────────────────────────────────────┐
│                            INSTANTON ARCHITECTURE                               │
└─────────────────────────────────────────────────────────────────────────────────┘

  ┌───────────────────┐                                    ┌───────────────────┐
  │   YOUR LOCAL APP  │                                    │  PUBLIC INTERNET  │
  │                   │                                    │                   │
  │  localhost:8000   │                                    │  Users worldwide  │
  │  FastAPI/Flask    │                                    │  Webhooks (Stripe)│
  │  Django/Express   │                                    │  Mobile apps      │
  └─────────┬─────────┘                                    └─────────▲─────────┘
            │                                                        │
            │ HTTP                                              HTTPS│
            ▼                                                        │
  ┌───────────────────┐         QUIC/HTTP3            ┌──────────────┴──────────┐
  │  INSTANTON CLIENT │◀═══════════════════════════════▶│   INSTANTON RELAY     │
  │                   │      (0-RTT, multiplexed)      │                        │
  │  • LZ4/Zstd       │                                │  • TLS 1.3 Termination │
  │  • Connection Pool│                                │  • Subdomain Routing   │
  │  • Zero-copy      │                                │  • Load Balancing (9)  │
  │  • Auto-reconnect │                                │  • DDoS Protection     │
  └───────────────────┘                                └────────────────────────┘

  ┌─────────────────────────────────────────────────────────────────────────────┐
  │                              DATA FLOW                                       │
  │                                                                             │
  │    User Request ──▶ abc123.instanton.tech ──▶ Relay ──▶ Client ──▶ App     │
  │    App Response ◀── abc123.instanton.tech ◀── Relay ◀── Client ◀── App     │
  │                                                                             │
  └─────────────────────────────────────────────────────────────────────────────┘

Deployment

Docker

# Run the relay server
docker run -d \
  --name instanton-server \
  -p 443:443 \
  -p 4443:4443 \
  -e INSTANTON_DOMAIN=tunnel.example.com \
  -v ./certs:/app/certs:ro \
  ghcr.io/drruin/instanton-server:latest

Docker Compose

version: '3.8'
services:
  instanton:
    image: ghcr.io/drruin/instanton-server:latest
    ports:
      - "443:443"
      - "4443:4443"
    environment:
      - INSTANTON_DOMAIN=tunnel.example.com
    volumes:
      - ./certs:/app/certs:ro
    command:
      - instanton-server
      - --domain
      - tunnel.example.com
      - --cert
      - /app/certs/cert.pem
      - --key
      - /app/certs/key.pem
    restart: unless-stopped

Kubernetes (Helm)

# Add the Helm repository
helm repo add instanton https://drruin.github.io/instanton
helm repo update

# Install
helm install instanton instanton/instanton-server \
  --set domain=tunnel.example.com \
  --set ingress.enabled=true

Configuration

CLI Options

instanton --help

Options:
  --port INTEGER          Local port to expose [required]
  --subdomain TEXT        Request specific subdomain
  --server TEXT           Relay server address
  --auth-token TEXT       Authentication token
  --timeout INTEGER       Connection timeout (seconds) [default: 30]
  --idle-timeout INTEGER  Idle timeout (seconds) [default: 300]
  --no-request-timeout    Disable request timeout (for long-running APIs)
  --inspect               Enable traffic inspector at localhost:4040
  --quic / --no-quic      Use QUIC transport [default: enabled]
  --verbose               Enable verbose logging
  --version               Show version
  --help                  Show this message

Environment Variables

export INSTANTON_SERVER=relay.example.com
export INSTANTON_AUTH_TOKEN=your-token
export INSTANTON_DOMAIN=tunnel.example.com
export INSTANTON_LOG_LEVEL=info

Config File (instanton.yaml)

server: relay.example.com
auth_token: ${INSTANTON_AUTH_TOKEN}

tunnels:
  web:
    port: 8000
    subdomain: myapp

  api:
    port: 3000
    subdomain: api
    no_request_timeout: true

  db:
    type: tcp
    port: 5432

Error Handling

Instanton provides clear, actionable error messages:

┌─────────────────────────────────────────────────────────────────────┐
│  ⚠️  Error: CONNECTION_TIMEOUT                                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Connection to instanton.tech timed out after 30.0s.                │
│                                                                     │
│  Please check your network connection and server address.           │
│                                                                     │
│  Suggestions:                                                       │
│    • Verify your internet connection                                │
│    • Check if the server address is correct                         │
│    • Try increasing the timeout with --timeout 60                   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Common error codes:

• CONNECTION_TIMEOUT - Server not reachable
• SUBDOMAIN_TAKEN - Requested subdomain in use
• SERVER_FULL - Server at capacity
• LOCAL_SERVICE_ERROR - Local service not running

Testing

# Clone the repository
git clone https://github.com/DrRuin/instanton.git
cd instanton

# Install development dependencies
pip install -e ".[dev]"

# Run all tests (1258+)
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=instanton --cov-report=html

# Run specific test categories
pytest tests/test_protocol.py -v
pytest tests/test_scalability.py -v
pytest tests/test_exceptions.py -v

Contributing

We welcome contributions!

# Fork and clone
git clone https://github.com/YOUR_USERNAME/instanton.git
cd instanton

# Create a branch
git checkout -b feature/amazing-feature

# Make your changes, then test
pytest tests/ -v
ruff check src/
ruff format src/

# Commit and push
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

# Open a Pull Request

Roadmap

• HTTP/HTTPS tunnels
• TCP/UDP tunnels
• QUIC/HTTP3 transport
• Zero Trust security
• 9 load balancing algorithms
• DDoS protection
• Traffic inspector
• Prometheus metrics
• OpenTelemetry tracing
• Docker & Kubernetes
• Helm charts
• Python SDK
• Comprehensive error handling
• SAML authentication
• Web dashboard

License

MIT License - see LICENSE for details.

_{Life's too short for port forwarding and firewall configs.}