instanton 0.8.0

Tunnel through barriers, instantly - expose local services to the internet

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

Performance 5ms latency overhead 1.2 Gbps throughput 6,500 connections/sec 250ms cold start HTTP/3 with QUIC support 0-RTT connection resumption LZ4/Zstd compression Zero-copy buffer pooling	Security Zero Trust architecture TLS 1.3 with certificate pinning mTLS (mutual TLS) support JWT, OAuth2, OIDC, API Keys DDoS protection & rate limiting Bot detection & IP reputation Geo-blocking & firewall rules Input sanitization (XSS, SQLi)	Observability Real-time traffic inspector Request/response replay Prometheus metrics OpenTelemetry tracing Structured logging Health checks & probes Circuit breaker patterns P99 latency tracking
Load Balancing 9 algorithms: Round-robin Weighted round-robin Least connections Weighted least connections Random / Weighted random IP hash Consistent hash ring Least response time	Protocols HTTP/1.1, HTTP/2, HTTP/3 WebSocket (full duplex) gRPC (with frame interception) TCP (raw passthrough) UDP (via QUIC datagrams) Auto protocol detection Streaming support Chunked transfer	Developer Experience One command to start Native Python SDK Async & sync APIs Rich CLI with colors Auto subdomain from project YAML config support Detailed error messages Comprehensive documentation

---

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 │                  ║
    ║    └──────┘  └───────┘  └───────┘  └───────┘  └───────┘                  ║
    ║                                                                           ║
    ╚═══════════════════════════════════════════════════════════════════════════╝

TLS 1.3 ECDHE + AES-GCM ChaCha20-Poly1305 Certificate pinning Perfect forward secrecy

DDoS Protection Rate limiting (3 algorithms) Bot detection IP reputation scoring Geo-blocking Slowloris mitigation

Authentication JWT (HS256, RS256) OAuth2 / OIDC mTLS certificates API keys (Argon2) Basic auth

---

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.}