notunnel

notunnel is a lightweight port forwarding tool designed for remote development environments. It creates secure tunnels between your local machine and remote development servers, perfect for accessing web services running on remote hosts or within private networks like WireGuard overlays.

Features

• Remote Port Forwarding - Forward ports from remote development servers to your local machine
• Async Port Mapping - Support for different local and remote port configurations
• Background Mode - Run tunnels in detached mode for long-running sessions
• Live Log Streaming - Monitor tunnel activity in real-time
• Tunnel Management - List, close, and manage multiple active tunnels
• gRPC Architecture - Fast and efficient communication protocol
• WireGuard Compatible - Works seamlessly with overlay networks

Installation

From source

cargo install notunnel

Prerequisites

• Rust 1.70 or higher
• A running notunnel server on your remote development machine

Quick Start

1. Start the server on your remote machine

# On your remote development server
notunnel serve

The server will start listening on port 3000 by default.

2. Configure your client

Create a .env file on your local machine:

# Local machine configuration
NOTUNNEL_HOST=10.0.9.18        # Your remote server IP
NOTUNNEL_CLIENT_HOST=10.0.9.19  # Your local machine IP (on the same network)
NOTUNNEL_HOST_PORT=3000         # Server port

3. Open a tunnel

# Forward remote port 8090 to local port 8090
notunnel open 8090

# Forward remote port 30080 to local port 8090
notunnel open 8090:30080

# Run in background (detached mode)
notunnel open 8090 --detached

Usage

Server Mode

Start the notunnel server on your remote development machine:

notunnel serve

Environment variables:

• SERVICE_HOST - Server bind address (default: 0.0.0.0:3000)
• NOTUNNEL_HOST - Server hostname/IP for client connections
• NOTUNNEL_CLIENT_HOST - Client hostname/IP

Client Commands

Open a tunnel

Forward a port from the remote server to your local machine:

# Same port on both sides
notunnel open 8080

# Different ports (local:remote)
notunnel open 3000:8080

# Run in background
notunnel open 8080 --detached

List active tunnels

View all currently active port forwards:

notunnel list

Output:

tunnels

  - 8080:8080 @ 550e8400-e29b-41d4-a716-446655440000
  - 3000:8080 @ 6ba7b810-9dad-11d1-80b4-00c04fd430c8

Close a tunnel

Stop a specific port forward using its tunnel ID:

notunnel close --tunnel-id 550e8400-e29b-41d4-a716-446655440000

Tail tunnel logs

Monitor real-time activity for a specific tunnel:

notunnel tail --tunnel-id 550e8400-e29b-41d4-a716-446655440000

Configuration

Environment Variables

Server Configuration

Client Configuration

Example Configurations

Local Development (.env)

# For local testing
RUST_LOG=notmad=trace,notunnel=trace,info
NOTUNNEL_HOST=127.0.0.1
NOTUNNEL_HOST_PORT=3000

Remote Development (remote/.env)

# For WireGuard or private network setup
NOTUNNEL_HOST=10.0.9.18
NOTUNNEL_CLIENT_HOST=10.0.9.19
NOTUNNEL_HOST_PORT=3000

Use Cases

Web Development on Remote Servers

When developing web applications on a remote server, notunnel allows you to access the application through your local browser:

# On remote server: Start your web app on port 3000
npm run dev

# On local machine: Forward the port
notunnel open 3000

# Access in browser: http://localhost:3000

WireGuard Overlay Networks

Perfect for development environments using WireGuard VPN overlays where services bind to overlay network interfaces:

# Server listens on WireGuard interface (10.0.9.18)
notunnel serve

# Client connects through WireGuard (10.0.9.19)
notunnel open 8080

Multiple Service Forwarding

Run multiple tunnels simultaneously for microservice development:

# Forward multiple services
notunnel open 3000:3000 --detached  # Frontend
notunnel open 8080:8080 --detached  # Backend API
notunnel open 5432:5432 --detached  # PostgreSQL
notunnel open 6379:6379 --detached  # Redis

# Check all active tunnels
notunnel list

Architecture

notunnel uses a client-server architecture with gRPC for communication:

1. Server Component - Runs on the remote development machine, manages port forwarding
2. Client Component - Runs on your local machine, initiates and manages tunnels
3. gRPC Protocol - Efficient binary protocol for tunnel management
4. Proxy Layer - Powered by Pingora for high-performance packet forwarding

Development

Building from source

# Clone the repository
git clone https://git.kjuulh.io/kjuulh/notunnel
cd notunnel

# Build the project
cargo build --release

# Run tests
cargo test

Project Structure

notunnel/
├── crates/
│   └── notunnel/
│       ├── proto/           # Protocol buffer definitions
│       ├── src/
│       │   ├── cli/         # CLI command implementations
│       │   ├── grpc/        # gRPC client/server
│       │   ├── tunnels.rs   # Tunnel management
│       │   └── main.rs      # Entry point
│       └── Cargo.toml
├── remote/                   # Remote server configuration
└── README.md

Troubleshooting

Connection Issues

If you cannot connect to the server:

1. Check that the server is running: notunnel serve
2. Verify network connectivity: ping <NOTUNNEL_HOST>
3. Ensure the correct port is open: telnet <NOTUNNEL_HOST> 3000
4. Check your firewall settings

Port Already in Use

If you get a "port already in use" error:

1. List active tunnels: notunnel list
2. Close conflicting tunnel: notunnel close --tunnel-id <ID>
3. Or use a different local port: notunnel open 3001:3000

Logging

Enable detailed logging for debugging:

export RUST_LOG=notunnel=debug
notunnel open 8080

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Kasper Juul Hermansen (@kjuulh)

Links

• Repository
• Issues