Quick Start

This guide assumes you have a remote WireGuard peer (e.g., a server or router) configured and accessible.

Prerequisites

You need the following information from your WireGuard network:

  1. Endpoint Address: The public IP and port of your WireGuard server (e.g., 140.30.3.182:51820).
  2. Endpoint Public Key: The public key of the remote WireGuard server.
  3. Peer Private Key: The private key onetun will use.
  4. Peer IP: The internal IP address assigned to onetun inside the WireGuard network (e.g., 192.168.4.3).

!!! warning "Important" You must register the public key corresponding to Peer Private Key on your WireGuard server/endpoint, just like any other WireGuard client.

Scenario

  • Goal: Access a private web server running at 192.168.4.2 on port 8080.
  • Local Port: We want to map this to localhost:3000.

Running onetun

Run the following command:

onetun 127.0.0.1:3000:192.168.4.2:8080 \
    --endpoint-addr 140.30.3.182:51820 \
    --endpoint-public-key 'PUB_KEY_FROM_SERVER' \
    --private-key 'YOUR_GENERATED_PRIVATE_KEY' \
    --source-peer-ip 192.168.4.3

Verification

If successful, you will see a log message indicating the tunnel is active:

INFO  onetun > Tunneling TCP [127.0.0.1:3000]->[192.168.4.2:8080] (via [140.30.3.182:51820] as peer 192.168.4.3)

Now, open your browser or use curl:

curl http://127.0.0.1:3000

You are now accessing the private resource through the user-space WireGuard tunnel!