instanton 0.6.5

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

flowchart LR
    subgraph ZeroTrust["ZERO TRUST ARCHITECTURE"]
        direction LR
        A["🔐 Identity<br/>Verify"] --> B["💻 Device<br/>Posture"]
        B --> C["⚠️ Risk<br/>Score"]
        C --> D["✅ Access<br/>Decision"]
    end

flowchart TB
    subgraph TrustLevels["Trust Levels & Access Rights"]
        direction LR
        U["UNTRUSTED"] --> L["LOW"]
        L --> M["MEDIUM"]
        M --> H["HIGH"]
        H --> V["VERIFIED"]
    end

    U -.-> UB["🚫 Block"]
    L -.-> LA["Limited Access"]
    M -.-> SA["Standard Access"]
    H -.-> EA["Extended Access"]
    V -.-> FA["✅ Full 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

flowchart LR
    subgraph Client["🖥️ Client"]
        direction TB
        C1["Local Service<br/>localhost:8000"]
    end

    subgraph Features["⚡ Optimizations"]
        direction TB
        F1["LZ4 Compression"]
        F2["Connection Pool"]
        F3["Zero-copy Buffers"]
        F4["uvloop (Linux)"]
    end

    subgraph Relay["🌐 Relay Server"]
        direction TB
        R1["TLS Termination"]
        R2["Subdomain Routing"]
        R3["Load Balancing"]
    end

    subgraph Internet["🌍 Internet"]
        direction TB
        I1["Public Users<br/>abc123.instanton.tech"]
    end

    C1 <-->|"QUIC/HTTP3<br/>(0-RTT, multiplexed)"| Relay
    Relay <-->|"HTTPS<br/>(pooled)"| Internet

    Features -.-> C1

---

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:

flowchart TB
    subgraph ErrorBox["⚠️ Error: CONNECTION_TIMEOUT"]
        direction TB
        E1["Connection to instanton.tech timed out after 30.0s."]
        E2["Please check your network connection and server address."]
    end

    style ErrorBox fill:#fee2e2,stroke:#dc2626,color:#991b1b

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! See CONTRIBUTING.md for guidelines.

# 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
• Terraform provider
• VS Code extension

---

License

MIT License - see LICENSE for details.

---

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