Self-Host the rustunnel Tunnel Server on Ubuntu (systemd, TLS, PostgreSQL)

This guide walks through how to self-host the rustunnel tunnel server in production. rustunnel is open-source under AGPL, so you can run the same server we run on the managed cloud — on any VPS with a public IP and a wildcard DNS record. The example commands use Ubuntu 22.04, systemd, Let’s Encrypt TLS via Certbot, and PostgreSQL, but the same recipe works on any major cloud provider including Hetzner, DigitalOcean, Linode, and AWS Lightsail. For a Docker-based deployment, see the Docker Deployment guide instead.

Requirements

To build

Requirement	Version	Notes
Rust toolchain	1.76+	Install via rustup
`pkg-config`	any	Required by `reqwest` (TLS)
`libssl-dev`	any	`apt install libssl-dev`
Node.js + npm	18+	Only needed to rebuild the dashboard UI

To run

Requirement	Notes
Linux (Ubuntu 22.04+)	systemd service included
Public IP + DNS	Wildcard DNS `*.tunnel.yourdomain.com → server IP` required for HTTP tunnels
TLS certificate	PEM format — Let’s Encrypt recommended
PostgreSQL	Stores API tokens and tunnel audit log

Step 1 — Install dependencies

apt update && apt install -y \
  pkg-config libssl-dev curl git \
  certbot python3-certbot-dns-cloudflare

Install Rust (as the build user, not root):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Step 2 — Build release binaries

git clone https://github.com/joaoh82/rustunnel.git
cd rustunnel
cargo build --release -p rustunnel-server -p rustunnel-client

Binaries will be at:

target/release/rustunnel-server
target/release/rustunnel

Step 3 — Create system user and directories

useradd --system --no-create-home --shell /usr/sbin/nologin rustunnel

mkdir -p /etc/rustunnel /var/lib/rustunnel
chown rustunnel:rustunnel /var/lib/rustunnel
chmod 750 /var/lib/rustunnel

Step 4 — Install the server binary

install -Dm755 target/release/rustunnel-server /usr/local/bin/rustunnel-server

# Optionally install the client system-wide
install -Dm755 target/release/rustunnel /usr/local/bin/rustunnel

Or use the Makefile shortcut (runs build + install + systemd setup):

sudo make deploy

Step 5 — Set up PostgreSQL

rustunnel requires PostgreSQL for shared state (tokens, tunnel history, audit log).

apt install -y postgresql postgresql-contrib

# Start and enable the service
systemctl enable --now postgresql

Create a dedicated database and user:

sudo -u postgres psql <<'SQL'
CREATE USER rustunnel WITH PASSWORD 'CHANGE_ME';
CREATE DATABASE rustunnel OWNER rustunnel;
GRANT ALL PRIVILEGES ON DATABASE rustunnel TO rustunnel;
SQL

For managed PostgreSQL (e.g. AWS RDS, DigitalOcean Managed Databases, Supabase) skip the apt install step and just note down your connection URL for the config in the next step.

Schema migrations run automatically when the server starts — no manual SQL needed.

Step 6 — Create the server config file

Create /etc/rustunnel/server.toml. Generate a strong admin token first:

openssl rand -hex 32

# /etc/rustunnel/server.toml

[server]
# Primary domain — must match your wildcard DNS record.
domain       = "edge.rustunnel.com"

# Ports for incoming tunnel traffic.
http_port    = 80
https_port   = 443

# Control-plane WebSocket port — clients connect here.
control_port = 4040

# Dashboard UI and REST API port.
dashboard_port = 8443

# Allowed CORS origin for the dashboard UI.
# Set to the URL where you serve the dashboard (e.g. http://localhost:3000 for local dev).
dashboard_origin = "http://localhost:3000"

# ── TLS ─────────────────────────────────────────────────────────────────────
[tls]
# Paths written by Certbot (see step 7).
cert_path = "/etc/letsencrypt/live/edge.rustunnel.com/fullchain.pem"
key_path  = "/etc/letsencrypt/live/edge.rustunnel.com/privkey.pem"

# Set acme_enabled = true only if you want rustunnel to manage certs itself.
# When using Certbot (recommended), leave this false.
acme_enabled = false

# ── Auth ─────────────────────────────────────────────────────────────────────
[auth]
# Strong random secret — used as the admin token and for client auth.
# Generate with: openssl rand -hex 32
admin_token  = "your-admin-token-here"
require_auth = true

# ── Database ─────────────────────────────────────────────────────────────────
[database]
# PostgreSQL connection URL — the database and user must exist before starting
# the server (see step 5 above). Schema migrations run automatically on first start.
url = "postgresql://rustunnel:CHANGE_ME@localhost:5432/rustunnel"

# Per-region SQLite file for captured HTTP request bodies.
# The directory must be writable by the rustunnel user.
captured_path = "/var/lib/rustunnel/captured.db"

# ── Logging ──────────────────────────────────────────────────────────────────
[logging]
level  = "info"
format = "json"

# Optional: append-only audit log (JSON-lines).
# Records auth attempts, tunnel registrations, token creation/deletion.
# Omit or comment out to disable.
audit_log_path = "/var/lib/rustunnel/audit.log"

# ── Limits ───────────────────────────────────────────────────────────────────
[limits]
max_tunnels_per_session    = 10
max_connections_per_tunnel = 100
rate_limit_rps             = 100
ip_rate_limit_rps          = 100
request_body_max_bytes     = 10485760   # 10 MB

# Inclusive port range reserved for TCP tunnels.
tcp_port_range = [20000, 20099]

Secure the file:

chown root:rustunnel /etc/rustunnel/server.toml
chmod 640 /etc/rustunnel/server.toml

Step 7 — TLS certificates (Let’s Encrypt + Cloudflare)

Both the bare domain and the wildcard are required. The wildcard (*.edge.rustunnel.com) is what makes HTTP subdomain tunnels work. Create the Cloudflare credentials file:

cat > /etc/letsencrypt/cloudflare.ini <<'EOF'
# Cloudflare API token with DNS:Edit permission for the zone.
dns_cloudflare_api_token = YOUR_CLOUDFLARE_API_TOKEN
EOF

chmod 600 /etc/letsencrypt/cloudflare.ini

Request the certificate:

certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini \
  -d "edge.rustunnel.com" \
  -d "*.edge.rustunnel.com" \
  --agree-tos \
  --email your@email.com

Certbot writes the PEM files to:

/etc/letsencrypt/live/edge.rustunnel.com/fullchain.pem
/etc/letsencrypt/live/edge.rustunnel.com/privkey.pem

Certbot installs a systemd timer for automatic renewal. rustunnel reads TLS certificates from disk at startup, so it must be restarted after each renewal. Add a deploy hook to do this automatically:

cat > /etc/letsencrypt/renewal-hooks/deploy/restart-rustunnel.sh <<'EOF'
#!/bin/sh
systemctl restart rustunnel.service
EOF
chmod +x /etc/letsencrypt/renewal-hooks/deploy/restart-rustunnel.sh

Allow the rustunnel service user to read the certificates:

chmod 755 /etc/letsencrypt/{live,archive}
chmod 640 /etc/letsencrypt/live/edge.rustunnel.com/*.pem
chgrp rustunnel /etc/letsencrypt/live/edge.rustunnel.com/*.pem
chgrp rustunnel /etc/letsencrypt/archive/edge.rustunnel.com/*.pem
chmod 640 /etc/letsencrypt/archive/edge.rustunnel.com/*.pem

Step 8 — Set up the systemd service

install -Dm644 deploy/rustunnel.service /etc/systemd/system/rustunnel.service

systemctl daemon-reload
systemctl enable --now rustunnel.service

# Check it started
systemctl status rustunnel.service
journalctl -u rustunnel.service -f

Step 9 — Open firewall ports

ufw allow 80/tcp    comment "rustunnel HTTP edge"
ufw allow 443/tcp   comment "rustunnel HTTPS edge"
ufw allow 4040/tcp  comment "rustunnel control plane"
ufw allow 8443/tcp  comment "rustunnel dashboard"
ufw allow 9090/tcp  comment "rustunnel Prometheus metrics"
ufw allow 20000:20099/tcp comment "rustunnel TCP tunnels"

Port 9090 only needs to be open if you have an external Prometheus scraper. If Prometheus runs on the same host it reaches the metrics endpoint over the loopback network.

Step 10 — Verify the server is running

# Health check (dashboard is plain HTTP on dashboard_port)
curl http://localhost:8443/api/status

# Check bound ports
ss -tlnp | grep rustunnel-serve

# Startup logs
journalctl -u rustunnel.service --no-pager | tail -30

# Prometheus metrics
curl -s http://localhost:9090/metrics

Port 4040 is the control-plane WebSocket — clients connect here. Hitting it with plain HTTP returns HTTP/0.9, which is expected. The dashboard REST API is on dashboard_port (8443 in the config above).

Connecting a client

rustunnel http 3000 \
  --server edge.rustunnel.com:4040 \
  --token YOUR_ADMIN_TOKEN

Updating the server

Pull the latest code, rebuild, install, and restart in one command:

cd ~/rustunnel && sudo make update-server

This runs: git pull → cargo build --release → install → systemctl restart → systemctl status.

Port reference

Port	Protocol	Purpose
`80`	TCP	HTTP edge — redirects to HTTPS; ACME HTTP-01 challenge
`443`	TCP	HTTPS edge — TLS-terminated tunnel ingress
`4040`	TCP	Control-plane WebSocket — clients connect here
`8443`	TCP	Dashboard UI and REST API
`9090`	TCP	Prometheus metrics (`/metrics`)
`20000–20099`	TCP	TCP tunnel range (configurable via `tcp_port_range`)

Config file reference

Key	Type	Default	Description
`server.domain`	string	—	Base domain for tunnel URLs
`server.http_port`	u16	—	HTTP edge port
`server.https_port`	u16	—	HTTPS edge port
`server.control_port`	u16	—	WebSocket control-plane port
`server.dashboard_port`	u16	`4040`	Dashboard REST API port
`server.dashboard_origin`	string	`""`	Allowed CORS origin for the dashboard UI
`tls.cert_path`	string	—	Path to TLS certificate (PEM)
`tls.key_path`	string	—	Path to TLS private key (PEM)
`tls.acme_enabled`	bool	`false`	Enable built-in ACME renewal
`tls.acme_email`	string	`""`	Contact email for ACME
`tls.acme_staging`	bool	`false`	Use Let’s Encrypt staging CA
`tls.cloudflare_api_token`	string	`""`	Cloudflare DNS API token (prefer env var `CLOUDFLARE_API_TOKEN`)
`tls.cloudflare_zone_id`	string	`""`	Cloudflare Zone ID (prefer env var `CLOUDFLARE_ZONE_ID`)
`auth.admin_token`	string	—	Master auth token
`auth.require_auth`	bool	—	Reject unauthenticated clients
`database.url`	string	—	PostgreSQL connection URL (required)
`database.captured_path`	string	`/var/lib/rustunnel/captured.db`	Per-region SQLite file for captured HTTP request bodies
`logging.level`	string	—	`trace` / `debug` / `info` / `warn` / `error`
`logging.format`	string	—	`json` or `pretty`
`logging.audit_log_path`	string	`null`	Audit log path (JSON-lines); omit to disable
`limits.max_tunnels_per_session`	usize	—	Max tunnels per connected client
`limits.max_connections_per_tunnel`	usize	—	Max concurrent connections per tunnel
`limits.rate_limit_rps`	u32	—	Per-tunnel request rate cap (req/s)
`limits.ip_rate_limit_rps`	u32	`100`	Per-source-IP rate cap (req/s); `0` = disabled
`limits.request_body_max_bytes`	usize	—	Max proxied request body size (bytes)
`limits.tcp_port_range`	[u16, u16]	—	Inclusive `[low, high]` TCP tunnel port range
`region.id`	string	`"default"`	Region identifier (e.g. `"eu"`, `"us"`, `"ap"`)
`region.name`	string	`"Default"`	Human-readable region name shown in the dashboard
`region.location`	string	`""`	Physical location label (e.g. `"Helsinki, FI"`)

Monitoring

A Prometheus metrics endpoint is available at :9090/metrics:

rustunnel_active_sessions      # gauge: connected clients
rustunnel_active_tunnels_http  # gauge: active HTTP tunnels
rustunnel_active_tunnels_tcp   # gauge: active TCP tunnels

Start the full monitoring stack (Prometheus + Grafana):

make docker-run-monitoring
# Grafana:    http://localhost:3000  (admin / changeme)
# Prometheus: http://localhost:9090

The default Grafana password is changeme. Set GRAFANA_PASSWORD before starting the stack in production.

export GRAFANA_PASSWORD=your-strong-password
make docker-run-monitoring

Next steps

Client Guide

Configure the rustunnel CLI to connect to your self-hosted server.

Architecture

Understand the control plane, data plane, and yamux multiplexing under the hood.

Load Balancing & Health Checks

Run multiple backends behind one subdomain with automatic failover.

MCP Server

Let AI agents manage tunnels on your self-hosted server via MCP.

Getting started

Guides

Reference

Self-Host the rustunnel Tunnel Server on Ubuntu (systemd, TLS, PostgreSQL)

Requirements

To build

To run

Step 1 — Install dependencies

Step 2 — Build release binaries

Step 3 — Create system user and directories

Step 4 — Install the server binary

Step 5 — Set up PostgreSQL

Step 6 — Create the server config file

Step 7 — TLS certificates (Let’s Encrypt + Cloudflare)

Step 8 — Set up the systemd service

Step 9 — Open firewall ports

Step 10 — Verify the server is running

Connecting a client

Updating the server

Port reference

Config file reference

Monitoring

Next steps

Client Guide

Architecture

Load Balancing & Health Checks

MCP Server

​Requirements

​To build

​To run

​Step 1 — Install dependencies

​Step 2 — Build release binaries

​Step 3 — Create system user and directories

​Step 4 — Install the server binary

​Step 5 — Set up PostgreSQL

​Step 6 — Create the server config file

​Step 7 — TLS certificates (Let’s Encrypt + Cloudflare)

​Step 8 — Set up the systemd service

​Step 9 — Open firewall ports

​Step 10 — Verify the server is running

​Connecting a client

​Updating the server

​Port reference

​Config file reference

​Monitoring

​Next steps

Client Guide

Architecture

Load Balancing & Health Checks

MCP Server

Requirements

To build

To run

Step 1 — Install dependencies

Step 2 — Build release binaries

Step 3 — Create system user and directories

Step 4 — Install the server binary

Step 5 — Set up PostgreSQL

Step 6 — Create the server config file

Step 7 — TLS certificates (Let’s Encrypt + Cloudflare)

Step 8 — Set up the systemd service

Step 9 — Open firewall ports

Step 10 — Verify the server is running

Connecting a client

Updating the server

Port reference

Config file reference

Monitoring

Next steps