Skip to content
Back to search

rustunnel

Self-hosted, secure tunnel server in Rust. Expose local HTTP/HTTPS/TCP/UDP services to the public internet via TLS-encrypted WebSocket. Open-source, pay-as-you-go managed option, MCP server for AI agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/joaoh82--rustunnel/badge.svg)](/listings/joaoh82--rustunnel)

HTML

<a href="/listings/joaoh82--rustunnel"><img src="/api/listings/joaoh82--rustunnel/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Once you have a token, run the setup wizard:

rustunnel setup
# Region [auto / eu / us / ap / self-hosted] (default: auto): (press Enter)
#   Selecting nearest region… eu 12ms · us 143ms · ap 311ms · → eu (Helsinki, FI) 12ms
#   Server set to: eu.edge.rustunnel.com:4040
# Auth token: <paste your token>

Then expose a local service:

# HTTP tunnel — auto-selects the nearest region
rustunnel http 3000

# Connect to a specific region
rustunnel http 3000 --region eu

# Custom subdomain
rustunnel http 3000 --subdomain myapp

# TCP tunnel — e.g. expose a local database
rustunnel tcp 5432

# UDP tunnel — e.g. expose a game server
rustunnel udp 27015

# P2P tunnel — expose a service to another rustunnel client
rustunnel p2p 27015 --name my-game --secret "shared-secret"

# P2P tunnel — connect to a peer's service
rustunnel p2p 8000 --target my-game --secret "shared-secret"

The client prints the public URL as soon as the tunnel is established:

  Selecting nearest region… eu 12ms · us 143ms · ap 311ms → eu (Helsinki, FI) 12ms
✓ tunnel open  https://abc123.eu.edge.rustunnel.com

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,174 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # rustunnel
  2. [![CI](https://github.com/joaoh82/rustunnel/actions/workflows/ci.yml/badge.svg)](https://github.com/joaoh82/rustunnel/actions/workflows/ci.yml)
  3. [![License: AGPLv3](https://img.shields.io/badge/License-AGPLv3-blue.svg)](LICENSE)
  4. [![Rust](https://img.shields.io/badge/rust-1.76%2B-orange.svg)](https://www.rust-lang.org)
  5. [![Listed on Skillselion](https://skillselion.com/badge/mcp/tool/io.github.joaoh82/rustunnel.svg)](https://skillselion.com/mcp/tool/io.github.joaoh82/rustunnel)
  6. ![rustunnel logo](images/rustunnel-logo-light.png)
  7. The open-source tunnel that scales with you. Don't pay for idle time. Secure, Rust-fast, and Pay-as-you-go.
  8. Expose local services through a public server over encrypted WebSocket connections with TLS termination, HTTP/TCP proxying, a live dashboard, Prometheus metrics, and audit logging.
  9. You can self-host or use our managed service.
  10. **Using an AI agent?** rustunnel ships an [MCP server](https://rustunnel.com/docs/guides/mcp-server): one-click setup for Cursor (then add your [API token](https://rustunnel.com)):
  11. [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=rustunnel&config=eyJjb21tYW5kIjoicnVzdHVubmVsLW1jcCIsImFyZ3MiOlsiLS1zZXJ2ZXIiLCJldS5lZGdlLnJ1c3R1bm5lbC5jb206NDA0MCIsIi0tYXBpIiwiaHR0cHM6Ly9ldS5lZGdlLnJ1c3R1bm5lbC5jb206ODQ0MyJdLCJlbnYiOnsiUlVTVFVOTkVMX1RPS0VOIjoiWU9VUl9UT0tFTiJ9fQ==)
  12. For Claude Code, Claude Desktop, Windsurf, and others, see the [agent integration guide](https://rustunnel.com/docs/guides/agent-integration) or the agent manual at [rustunnel.com/agents.md](https://rustunnel.com/agents.md).
  13. ---
  14. ## Table of Contents
  15. - [Hosted service](#hosted-service)
  16. - [Architecture overview](#architecture-overview)
  17. - [Requirements](#requirements)
  18. - [Local development setup](#local-development-setup)
  19. - [Build](#build)
  20. - [Run tests](#run-tests)
  21. - [Run the server locally](#run-the-server-locally)
  22. - [Run the client locally](#run-the-client-locally)
  23. - [Git hooks](#git-hooks)
  24. - [Production deployment (Ubuntu / systemd)](#production-deployment-ubuntu--systemd)
  25. - [1: Install dependencies](#1-install-dependencies)
  26. - [2: Build release binaries](#2-build-release-binaries)
  27. - [3: Create system user and directories](#3-create-system-user-and-directories)
  28. - [4: Install the server binary](#4-install-the-server-binary)
  29. - [5: Create the server config file](#5-create-the-server-config-file)
  30. - [6: TLS certificates (Let's Encrypt + Cloudflare)](#6-tls-certificates-lets-encrypt--cloudflare)
  31. - [7: Set up systemd service](#7-set-up-systemd-service)
  32. - [8: Open firewall ports](#8-open-firewall-ports)
  33. - [9: Verify the server is running](#9-verify-the-server-is-running)
  34. - [Updating the server](#updating-the-server)
  35. - [Docker deployment](#docker-deployment) · [full guide](docs/docker-deployment.md)
  36. - [Client configuration](#client-configuration)
  37. - [Installation](#installation)
  38. - [Setup wizard](#setup-wizard)
  39. - [Quick start (CLI flags)](#quick-start-cli-flags)
  40. - [Machine-readable output (`--json`)](#machine-readable-output---json)
  41. - [Config file](#config-file)
  42. - [Token management](#token-management)
  43. - [Port reference](#port-reference)
  44. - [Config file reference (server)](#config-file-reference-server)
  45. - [REST API](#rest-api)
  46. - [AI agent integration (MCP server)](#ai-agent-integration-mcp-server)
  47. - [OpenClaw skill](#openclaw-skill)
  48. - [Monitoring](#monitoring)
  49. - [Roadmap](#roadmap)
  50. - [Contributing](#contributing)
  51. - [License](#license)
  52. - [Contact](#contact)
  53. ---
  54. ## Hosted service
  55. You can use rustunnel without running your own server. We operate a global fleet of public edge servers that you can connect to immediately.
  56. ### Available regions
  57. | Region ID | Server | Location | Control plane | Status |
  58. |-----------|--------|----------|---------------|--------|
  59. | `eu` | `eu.edge.rustunnel.com` | Helsinki, FI | `:4040` | Live |
  60. | `us` | `us.edge.rustunnel.com` | Hillsboro, OR | `:4040` | Live |
  61. | `ap` | `ap.edge.rustunnel.com` | Singapore | `:4040` | Live |
  62. The client auto-selects the nearest region by default. Use `--region <id>` to connect to a specific one. The legacy address `edge.rustunnel.com` is a CNAME to `eu.edge.rustunnel.com` and will continue to work for backward compatibility.
  63. ### Getting an auth token
  64. Sign up for a free account at **[rustunnel.com](https://rustunnel.com)**. No waiting list, no manual approval.
  65. 1. Create an account at [rustunnel.com](https://rustunnel.com)
  66. 2. Go to **Dashboard → API Keys** and create a token
  67. 3. Copy the token. It is shown only once
  68. **Plans:**
  69. | Plan | Price | Tunnels | Subdomains | Bandwidth | TLS/HTTPS |
  70. |------|-------|---------|------------|-----------|-----------|
  71. | Hobby (free) | $0 | 2 concurrent | Random only | 1 GB/mo | ✓ |
  72. | Pay-as-you-go | $3/mo minimum, credited at $0.10/GB | No cap | Custom | $0.10/GB | ✓ |
  73. | Self-host | Free (run your own server) | Unlimited | Custom | Unmetered | ✓ |
  74. The Hobby (free) plan is a great way to get started: 2 concurrent tunnels, random subdomains only, and 1 GB/mo. Upgrade to pay-as-you-go from your dashboard whenever you need custom subdomains or more tunnels. Pay-as-you-go has no tunnel cap.
  75. ### Quick start with the hosted server
  76. Once you have a token, run the setup wizard:
  77. ```bash
  78. rustunnel setup
  79. # Region [auto / eu / us / ap / self-hosted] (default: auto): (press Enter)
  80. # Selecting nearest region… eu 12ms · us 143ms · ap 311ms · → eu (Helsinki, FI) 12ms
  81. # Server set to: eu.edge.rustunnel.com:4040
  82. # Auth token: <paste your token>
  83. ```
  84. Then expose a local service:
  85. ```bash
  86. # HTTP tunnel: auto-selects the nearest region
  87. rustunnel http 3000
  88. # Connect to a specific region
  89. rustunnel http 3000 --region eu
  90. # Custom subdomain
  91. rustunnel http 3000 --subdomain myapp
  92. # TCP tunnel: e.g. expose a local database
  93. rustunnel tcp 5432
  94. # UDP tunnel: e.g. expose a game server
  95. rustunnel udp 27015
  96. # P2P tunnel: expose a service to another rustunnel client
  97. rustunnel p2p 27015 --name my-game --secret "shared-secret"
  98. # P2P tunnel: connect to a peer's service
  99. rustunnel p2p 8000 --target my-game --secret "shared-secret"
  100. ```
  101. The client prints the public URL as soon as the tunnel is established:
  102. ```
  103. Selecting nearest region… eu 12ms · us 143ms · ap 311ms → eu (Helsinki, FI) 12ms
  104. ✓ tunnel open https://abc123.eu.edge.rustunnel.com
  105. ```
  106. ---
  107. ## Architecture overview
  108. ![rustunnel architecture](images/rustunnel_architecture.png)
  109. ```
  110. ┌──────────────────────────────────────────┐
  111. │ rustunnel-server │
  112. │ │
  113. Internet ──── :80 ─────▶│ HTTP edge (301 → HTTPS) │
  114. Internet ──── :443 ────▶│ HTTPS edge ──▶ yamux stream ──▶ client │
  115. Client ───── :4040 ────▶│ Control-plane WebSocket (TLS) │
  116. Browser ──── :8443 ────▶│ Dashboard UI + REST API │
  117. Prometheus ─ :9090 ────▶│ Metrics endpoint │
  118. Internet ── :20000+ ───▶│ TCP tunnel ports (one per TCP tunnel) │
  119. └──────────────────────────────────────────┘
  120. │ yamux multiplexed streams
  121. ▼
  122. ┌─────────────────────┐
  123. │ rustunnel client │
  124. │ (developer laptop) │
  125. └──────────┬──────────┘
  126. │ localhost
  127. ▼
  128. ┌────────────────┐
  129. │ local service │
  130. │ e.g. :3000 │
  131. └────────────────┘
  132. ```
  133. ---
  134. ## Requirements
  135. ### To build
  136. | Requirement | Version | Notes |
  137. |---|---|---|
  138. | Rust toolchain | 1.76+ | Install via [rustup](https://rustup.rs) |
  139. | `pkg-config` | any | Needed by `reqwest` (TLS) |
  140. | `libssl-dev` | any | On Debian/Ubuntu: `apt install libssl-dev` |
  141. | Node.js + npm | 18+ | Only needed to rebuild the dashboard UI |
  142. ### To run the server in production
  143. | Requirement | Notes |
  144. |---|---|
  145. | Linux (Ubuntu 22.04+) | systemd service included |
  146. | TLS certificate + private key | PEM format (Let's Encrypt recommended) |
  147. | Public IP / DNS | Wildcard DNS `*.tunnel.yourdomain.com → server IP` required for HTTP tunnels |
  148. ---
  149. ## Local development setup
  150. ### Build
  151. ```bash
  152. # Clone the repository
  153. git clone https://github.com/joaoh82/rustunnel.git
  154. cd rustunnel
  155. # Compile all workspace crates (debug mode)
  156. cargo build --workspace
  157. # Or use the Makefile shortcut
  158. make build
  159. ```
  160. ### Run tests
  161. The integration test suite spins up a real server on random ports and exercises auth, HTTP tunnels, TCP tunnels, and reconnection logic. It requires a running PostgreSQL instance.
  162. ```bash
  163. # Start the local PostgreSQL container (once per machine, persists across reboots)
  164. make db-start
  165. # Full suite (unit + integration)
  166. make test
  167. # With output visible
  168. TEST_DATABASE_URL=postgres://rustunnel:test@localhost:5432/rustunnel_test \
  169. cargo test --workspace -- --nocapture
  170. # Stop PostgreSQL when you no longer need it
  171. make db-stop
  172. ```
  173. `make db-start` runs `deploy/docker-compose.dev-deps.yml` which starts a Postgres 16 container on `localhost:5432`. The `make test` target injects `TEST_DATABASE_URL` automatically. If you run `cargo test` directly, export the variable first:
  174. ```bash
  175. export TEST_DATABASE_URL=postgres://rustunnel:test@localhost:5432/rustunnel_test
  176. ```
  177. ### Run the server locally
  178. Generate a self-signed certificate for local testing:
  179. ```bash
  180. mkdir -p /tmp/rustunnel-dev
  181. openssl req -x509 -newkey rsa:2048 -keyout /tmp/rustunnel-dev/key.pem \
  182. -out /tmp/rustunnel-dev/cert.pem -days 365 -nodes \
  183. -subj "/CN=localhost"
  184. ```
  185. A ready-made local config is checked into the repository at **`deploy/local/server.toml`**.
  186. It points to the self-signed cert paths above and has auth disabled for convenience.
  187. Start the server with it directly:
  188. ```bash
  189. cargo run -p rustunnel-server -- --config deploy/local/server.toml
  190. ```
  191. Key settings in `deploy/local/server.toml`:
  192. | Setting | Value |
  193. |---|---|
  194. | Domain | `localhost` |
  195. | HTTP edge | `:8080` |
  196. | HTTPS edge | `:8443` |
  197. | Control plane | `:4040` |
  198. | Dashboard | `:4041` |
  199. | Auth token | `dev-secret-change-me` |
  200. | Auth required | `false` |
  201. | TLS cert | `/tmp/rustunnel-dev/cert.pem` |
  202. | TLS key | `/tmp/rustunnel-dev/key.pem` |
  203. | Database | `/tmp/rustunnel-dev/rustunnel.db` |
  204. ### Run the client locally
  205. With the server running, expose a local service (e.g. something on port 3000):
  206. ```bash
  207. # HTTP tunnel
  208. cargo run -p rustunnel-client -- http 3000 \
  209. --server localhost:4040 \
  210. --token dev-secret-change-me \
  211. --insecure
  212. # TCP tunnel
  213. cargo run -p rustunnel-client -- tcp 5432 \
  214. --server localhost:4040 \
  215. --token dev-secret-change-me \
  216. --insecure
  217. ```
  218. > `--insecure` skips TLS certificate verification. Required when using a
  219. > self-signed certificate locally. Never use this flag against a production server.
  220. The client will print a public URL, for example:
  221. ```
  222. http tunnel → http://abc123.localhost:8080
  223. tcp tunnel → tcp://localhost:20000
  224. ```
  225. ### Testing the HTTP tunnel locally
  226. The tunnel URL uses a subdomain (e.g. `http://abc123.localhost:8080`).
  227. Browsers won't resolve `*.localhost` subdomains by default, so you have two options:
  228. **Option A: curl with a Host header (no setup required)**
  229. ```bash
  230. curl -v -H "Host: abc123.localhost" http://localhost:8080/
  231. ```
  232. **Option B: wildcard DNS via dnsmasq (enables browser access)**
  233. ```bash
  234. # Install and configure dnsmasq to resolve *.localhost → 127.0.0.1
  235. brew install dnsmasq
  236. echo "address=/.localhost/127.0.0.1" | sudo tee -a $(brew --prefix)/etc/dnsmasq.conf
  237. sudo brew services start dnsmasq
  238. # Tell macOS to use dnsmasq for .localhost queries
  239. sudo mkdir -p /etc/resolver
  240. echo "nameserver 127.0.0.1" | sudo tee /etc/resolver/localhost
  241. ```
  242. Then visit `http://abc123.localhost:8080` in the browser (include `:8080` since the
  243. local config uses port 8080, not port 80).
  244. ### Git hooks
  245. A pre-push hook is included in `.githooks/` that mirrors the CI check step
  246. (format check + Clippy). Run this once after cloning to activate it:
  247. ```bash
  248. make install-hooks
  249. ```
  250. From that point on, every `git push` will automatically run:
  251. ```bash
  252. cargo fmt --all -- --check
  253. cargo clippy --workspace --all-targets -- -D warnings
  254. ```
  255. If either check fails the push is aborted, keeping the remote branch green.
  256. ---
  257. ## Production deployment (Ubuntu / systemd)
  258. The steps below match a deployment where:
  259. - Domain: `edge.rustunnel.com`
  260. - Wildcard DNS: `*.edge.rustunnel.com → <server IP>`
  261. - TLS certs: Let's Encrypt via Certbot + Cloudflare DNS challenge
  262. ### 1: Install dependencies
  263. ```bash
  264. apt update && apt install -y \
  265. pkg-config libssl-dev curl git \
  266. certbot python3-certbot-dns-cloudflare
  267. ```
  268. Install Rust (as the build user, not root):
  269. ```bash
  270. curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  271. source "$HOME/.cargo/env"
  272. ```
  273. ### 2: Build release binaries
  274. ```bash
  275. git clone https://github.com/joaoh82/rustunnel.git
  276. cd rustunnel
  277. cargo build --release -p rustunnel-server -p rustunnel-client
  278. ```
  279. Binaries will be at:
  280. - `target/release/rustunnel-server`
  281. - `target/release/rustunnel`
  282. ### 3: Create system user and directories
  283. ```bash
  284. useradd --system --no-create-home --shell /usr/sbin/nologin rustunnel
  285. mkdir -p /etc/rustunnel /var/lib/rustunnel
  286. chown rustunnel:rustunnel /var/lib/rustunnel
  287. chmod 750 /var/lib/rustunnel
  288. ```
  289. ### 4: Install the server binary
  290. ```bash
  291. install -Dm755 target/release/rustunnel-server /usr/local/bin/rustunnel-server
  292. # Optionally install the client system-wide
  293. install -Dm755 target/release/rustunnel /usr/local/bin/rustunnel
  294. ```
  295. Or use the Makefile target (runs build + install + systemd setup):
  296. ```bash
  297. sudo make deploy
  298. ```
  299. ### 5: Set up PostgreSQL
  300. rustunnel requires PostgreSQL for shared state (tokens, tunnel history, audit log).
  301. ```bash
  302. apt install -y postgresql postgresql-contrib
  303. # Start and enable the service
  304. systemctl enable --now postgresql
  305. ```
  306. Create a dedicated database and user:
  307. ```bash
  308. sudo -u postgres psql <<'SQL'
  309. CREATE USER rustunnel WITH PASSWORD 'CHANGE_ME';
  310. CREATE DATABASE rustunnel OWNER rustunnel;
  311. GRANT ALL PRIVILEGES ON DATABASE rustunnel TO rustunnel;
  312. SQL
  313. ```
  314. > **Tip:** For managed PostgreSQL (e.g. AWS RDS, DigitalOcean Managed Database, Supabase) skip the
  315. > `apt install` step above and just note the connection URL for the config in the next step.
  316. Schema migrations run automatically when the server starts. No manual SQL needed.
  317. ### 6: Create the server config file
  318. Create `/etc/rustunnel/server.toml` with the content below.
  319. Replace `your-admin-token-here` with a strong random secret (e.g. `openssl rand -hex 32`).
  320. ```toml
  321. # /etc/rustunnel/server.toml
  322. [server]
  323. # Primary domain: must match your wildcard DNS record.
  324. domain = "edge.rustunnel.com"
  325. # Ports for incoming tunnel traffic (requires CAP_NET_BIND_SERVICE or root).
  326. http_port = 80
  327. https_port = 443
  328. # Control-plane WebSocket port: clients connect here.
  329. control_port = 4040
  330. # Dashboard UI and REST API port.
  331. dashboard_port = 8443
  332. # Allowed CORS origin for the dashboard UI.
  333. # Set to the URL where you serve the dashboard-ui (e.g. http://localhost:3000 for local dev).
  334. dashboard_origin = "http://localhost:3000"
  335. # ── TLS ─────────────────────────────────────────────────────────────────────
  336. [tls]
  337. # Paths written by Certbot (see step 6).
  338. cert_path = "/etc/letsencrypt/live/edge.rustunnel.com/fullchain.pem"
  339. key_path = "/etc/letsencrypt/live/edge.rustunnel.com/privkey.pem"
  340. # Set acme_enabled = true only if you want rustunnel to manage certs itself
  341. # via the ACME protocol (requires Cloudflare credentials below).
  342. # When using Certbot (recommended), leave this false.
  343. acme_enabled = false
  344. # ── Auth ─────────────────────────────────────────────────────────────────────
  345. [auth]
  346. # Strong random secret: used both as the admin token and for client auth.
  347. # Generate: openssl rand -hex 32
  348. admin_token = "your-admin-token-here"
  349. require_auth = true
  350. # Failed auth attempts per source IP per minute before rejection (0 = off).
  351. max_failed_auth_per_minute = 10
  352. # ── Database ─────────────────────────────────────────────────────────────────
  353. [database]
  354. # PostgreSQL connection URL: the database and user must exist before starting
  355. # the server (see the PostgreSQL setup step above). Schema migrations run
  356. # automatically on first start.
  357. url = "postgresql://rustunnel:CHANGE_ME@localhost:5432/rustunnel"
  358. # Per-region SQLite file for captured HTTP request bodies.
  359. # The directory must be writable by the rustunnel user.
  360. captured_path = "/var/lib/rustunnel/captured.db"
  361. # ── Logging ──────────────────────────────────────────────────────────────────
  362. [logging]
  363. level = "info"
  364. format = "json"
  365. # Optional: write an append-only audit log (JSON-lines) for auth attempts,
  366. # tunnel registrations, token creation/deletion, and admin actions.
  367. # Omit or comment out to disable.
  368. audit_log_path = "/var/lib/rustunnel/audit.log"
  369. # ── Limits ───────────────────────────────────────────────────────────────────
  370. [limits]
  371. # Maximum tunnels a single authenticated session may register.
  372. max_tunnels_per_session = 10
  373. # Maximum simultaneous proxied connections per tunnel (semaphore).
  374. max_connections_per_tunnel = 100
  375. # Per-tunnel request rate limit (requests/second).
  376. rate_limit_rps = 100
  377. # Per-source-IP rate limit (requests/second). Set to 0 to disable.
  378. ip_rate_limit_rps = 100
  379. # Maximum size of a proxied HTTP request body (bytes). Default: 10 MB.
  380. request_body_max_bytes = 10485760
  381. # Inclusive port range reserved for TCP tunnels.
  382. # Each active TCP tunnel consumes one port from this range.
  383. tcp_port_range = [20000, 20099]
  384. # Inclusive port range reserved for UDP tunnels.
  385. # Each active UDP tunnel consumes one port from this range.
  386. # Must not overlap with tcp_port_range. Set to [0, 0] to disable UDP tunnels.
  387. udp_port_range = [20100, 20199]
  388. ```
  389. Secure the file:
  390. ```bash
  391. chown root:rustunnel /etc/rustunnel/server.toml
  392. chmod 640 /etc/rustunnel/server.toml
  393. ```
  394. ### 7: TLS certificates (Let's Encrypt + Cloudflare)
  395. Create the Cloudflare credentials file:
  396. ```bash
  397. cat > /etc/letsencrypt/cloudflare.ini <<'EOF'
  398. # Cloudflare API token with DNS:Edit permission for the zone.
  399. dns_cloudflare_api_token = YOUR_CLOUDFLARE_API_TOKEN
  400. EOF
  401. chmod 600 /etc/letsencrypt/cloudflare.ini
  402. ```
  403. Request a certificate covering the bare domain and the wildcard (required for HTTP subdomain tunnels):
  404. ```bash
  405. certbot certonly \
  406. --dns-cloudflare \
  407. --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini \
  408. -d "edge.rustunnel.com" \
  409. -d "*.edge.rustunnel.com" \
  410. --agree-tos \
  411. --email your@email.com
  412. ```
  413. Certbot writes the certificate to:
  414. ```
  415. /etc/letsencrypt/live/edge.rustunnel.com/fullchain.pem
  416. /etc/letsencrypt/live/edge.rustunnel.com/privkey.pem
  417. ```
  418. These paths are already set in the config above. Certbot sets up automatic renewal via a systemd timer.
  419. rustunnel reads TLS certificates from disk at startup, so it must be restarted after each renewal.
  420. Add a Certbot deploy hook to do this automatically:
  421. ```bash
  422. cat > /etc/letsencrypt/renewal-hooks/deploy/restart-rustunnel.sh <<'EOF'
  423. #!/bin/sh
  424. systemctl restart rustunnel.service
  425. EOF
  426. chmod +x /etc/letsencrypt/renewal-hooks/deploy/restart-rustunnel.sh
  427. ```
  428. Allow the `rustunnel` service user to read the certificates:
  429. ```bash
  430. # Grant read access to the live/ and archive/ directories
  431. chmod 755 /etc/letsencrypt/{live,archive}
  432. chmod 640 /etc/letsencrypt/live/edge.rustunnel.com/*.pem
  433. chgrp rustunnel /etc/letsencrypt/live/edge.rustunnel.com/*.pem
  434. chgrp rustunnel /etc/letsencrypt/archive/edge.rustunnel.com/*.pem
  435. chmod 640 /etc/letsencrypt/archive/edge.rustunnel.com/*.pem
  436. ```
  437. ### 8: Set up systemd service
  438. ```bash
  439. # Copy the unit file from the repository
  440. install -Dm644 deploy/rustunnel.service /etc/systemd/system/rustunnel.service
  441. systemctl daemon-reload
  442. systemctl enable --now rustunnel.service
  443. # Check it started
  444. systemctl status rustunnel.service
  445. journalctl -u rustunnel.service -f
  446. ```
  447. ### 9: Open firewall ports
  448. ```bash
  449. ufw allow 80/tcp comment "rustunnel HTTP edge"
  450. ufw allow 443/tcp comment "rustunnel HTTPS edge"
  451. ufw allow 4040/tcp comment "rustunnel control plane"
  452. ufw allow 8443/tcp comment "rustunnel dashboard"
  453. ufw allow 9090/tcp comment "rustunnel Prometheus metrics"
  454. # TCP tunnel port range (must match tcp_port_range in server.toml)
  455. ufw allow 20000:20099/tcp comment "rustunnel TCP tunnels"
  456. # UDP tunnel port range (must match udp_port_range in server.toml)
  457. ufw allow 20100:20199/udp comment "rustunnel UDP tunnels"
  458. ```
  459. ### 10: Verify the server is running
  460. ```bash
  461. # Health check: use dashboard_port from server.toml (default 8443 in production)
  462. curl http://localhost:8443/api/status
  463. # Confirm which ports the process is actually bound to
  464. ss -tlnp | grep rustunnel-serve
  465. # Startup banner is visible in the logs
  466. journalctl -u rustunnel.service --no-pager | tail -30
  467. # Prometheus metrics
  468. curl -s http://localhost:9090/metrics
  469. ```
  470. > **Port reminder**: port 4040 is the control-plane WebSocket (clients connect here),
  471. > not the dashboard. Hitting it with plain HTTP returns `HTTP/0.9` which is expected.
  472. > The dashboard is on `dashboard_port`. Check your `server.toml` if unsure.
  473. ### Updating the server
  474. Pull the latest code, rebuild, install, and restart in one command:
  475. ```bash
  476. cd ~/rustunnel && sudo make update-server
  477. ```
  478. This runs `git pull` → `cargo build --release` → `install` → `systemctl restart` → `systemctl status`.
  479. ---
  480. ## Docker deployment
  481. A full Docker guide covering both local development (self-signed cert) and
  482. production VPS (Let's Encrypt) is available in
  483. [**docs/docker-deployment.md**](docs/docker-deployment.md).
  484. ### Pull the published image
  485. Multi-arch images (`linux/amd64` + `linux/arm64`) are published to GitHub
  486. Container Registry on every stable release. No build required:
  487. ```bash
  488. # Latest stable, or pin a version (e.g. :0.8.1)
  489. docker pull ghcr.io/joaoh82/rustunnel-server:latest
  490. # Run it with your server config mounted at /etc/rustunnel/server.toml
  491. docker run --rm \
  492. -p 80:80 -p 443:443 -p 4040:4040 -p 8443:8443 \
  493. -v "$PWD/deploy/server.toml:/etc/rustunnel/server.toml:ro" \
  494. ghcr.io/joaoh82/rustunnel-server:latest
  495. ```
  496. ### Quick reference (build from source)
  497. ```bash
  498. # Build the image locally (includes Next.js dashboard + Rust server)
  499. make docker-build
  500. # Build and push a multi-arch image to GHCR (maintainers; needs buildx + ghcr login)
  501. make docker-push
  502. # Local development (self-signed cert, no auth required)
  503. docker compose -f deploy/docker-compose.local.yml up
  504. # Production VPS (requires deploy/server.toml to be configured first)
  505. make docker-run
  506. # Production + Prometheus + Grafana monitoring stack
  507. make docker-run-monitoring
  508. # Tail server logs
  509. make docker-logs
  510. # Stop everything
  511. make docker-stop
  512. ```
  513. ### Files
  514. | File | Purpose |
  515. |------|---------|
  516. | `deploy/Dockerfile` | Multi-stage build: Node.js UI → Rust server → slim runtime |
  517. | `deploy/docker-compose.yml` | Production compose file |
  518. | `deploy/docker-compose.local.yml` | Local development compose file |
  519. | `deploy/server.toml` | Production server config template |
  520. | `deploy/server.local.toml` | Local development server config |
  521. | `deploy/prometheus.yml` | Prometheus scrape config |
  522. ---
  523. ## Client configuration
  524. ### Installation
  525. **Option 1: Homebrew (macOS and Linux, recommended)**
  526. ```bash
  527. brew tap joaoh82/rustunnel
  528. brew install rustunnel
  529. ```
  530. Homebrew installs pre-built binaries. No Rust toolchain required.
  531. The formula is updated automatically on every release. This installs
  532. both `rustunnel` (the CLI client) and `rustunnel-mcp` (the MCP server
  533. for AI agent integration).
  534. **Option 2: Pre-built binary**
  535. Download the archive for your platform from the
  536. [latest GitHub Release](https://github.com/joaoh82/rustunnel/releases/latest),
  537. extract it, and move the `rustunnel` binary to a directory on your `$PATH`:
  538. ```bash
  539. # Example for macOS Apple Silicon
  540. curl -L https://github.com/joaoh82/rustunnel/releases/latest/download/rustunnel-<version>-aarch64-apple-darwin.tar.gz \
  541. | tar xz
  542. sudo install -Dm755 rustunnel /usr/local/bin/rustunnel
  543. ```
  544. Available targets:
  545. | Platform | Archive |
  546. |----------|---------|
  547. | macOS Apple Silicon | `rustunnel-<version>-aarch64-apple-darwin.tar.gz` |
  548. | macOS Intel | `rustunnel-<version>-x86_64-apple-darwin.tar.gz` |
  549. | Linux x86_64 (glibc) | `rustunnel-<version>-x86_64-unknown-linux-gnu.tar.gz` |
  550. | Linux x86_64 (musl, static) | `rustunnel-<version>-x86_64-unknown-linux-musl.tar.gz` |
  551. | Linux arm64 | `rustunnel-<version>-aarch64-unknown-linux-gnu.tar.gz` |
  552. | Windows x86_64 | `rustunnel-<version>-x86_64-pc-windows-msvc.zip` |
  553. **Option 3: Build from source**
  554. Requires Rust 1.76+.
  555. ```bash
  556. git clone https://github.com/joaoh82/rustunnel.git
  557. cd rustunnel
  558. cargo build --release -p rustunnel-client
  559. sudo install -Dm755 target/release/rustunnel /usr/local/bin/rustunnel
  560. # Or via make
  561. make deploy-client
  562. ```
  563. ### Setup wizard
  564. The easiest way to create your config file is the interactive setup wizard:
  565. ```bash
  566. rustunnel setup
  567. ```
  568. It prompts for your region and auth token, then writes `~/.rustunnel/config.yml` with the correct server address and a commented `tunnels:` example section.
  569. ```
  570. rustunnel setup: create ~/.rustunnel/config.yml
  571. Region [auto / eu / us / ap / self-hosted] (default: auto):
  572. Selecting nearest region… eu 12ms · us 143ms · ap 311ms · → eu (Helsinki, FI) 12ms
  573. Server set to: eu.edge.rustunnel.com:4040
  574. Auth token (leave blank to skip): rt_live_abc123...
  575. Created: /Users/you/.rustunnel/config.yml
  576. Run `rustunnel start` to connect using this config.
  577. ```
  578. Pick a specific region (`eu`, `us`, `ap`) to connect directly, or `auto` (the default) to let the client probe all regions and pick the nearest. Choose `self-hosted` if you run your own server. The wizard will then prompt for your server address.
  579. After running setup, use `rustunnel start` to connect with all tunnels defined in the config, or use `rustunnel http <port>` / `rustunnel tcp <port>` for one-off tunnels.
  580. ### Quick start (CLI flags)
  581. ```bash
  582. # Expose a local HTTP service on port 3000 (auto-selects nearest region)
  583. rustunnel http 3000 \
  584. --token YOUR_AUTH_TOKEN
  585. # Connect to a specific region
  586. rustunnel http 3000 --region eu --token YOUR_AUTH_TOKEN
  587. # Use an explicit server address (bypasses region selection)
  588. rustunnel http 3000 \
  589. --server edge.rustunnel.com:4040 \
  590. --token YOUR_AUTH_TOKEN
  591. # Expose a local service with a custom subdomain
  592. rustunnel http 3000 \
  593. --token YOUR_AUTH_TOKEN \
  594. --subdomain myapp
  595. # Expose a local TCP service (e.g. a PostgreSQL database)
  596. rustunnel tcp 5432 \
  597. --token YOUR_AUTH_TOKEN
  598. # Disable automatic reconnection
  599. rustunnel http 3000 --no-reconnect
  600. ```
  601. ### Machine-readable output (`--json`)
  602. All tunnel-running commands (`http`, `tcp`, `udp`, `p2p`, `start`) and
  603. `token create` accept a `--json` flag. With it, stdout emits NDJSON,
  604. one JSON event object per line, instead of the human-readable startup
  605. box, which makes the CLI easy to drive from scripts and AI agents:
  606. ```bash
  607. rustunnel http 3000 --json --token YOUR_AUTH_TOKEN
  608. ```
  609. ```json
  610. {"event":"tunnel_ready","protocol":"http","public_url":"https://myapp.eu.edge.rustunnel.com","local_port":3000,"local_host":"localhost","tunnel_id":"6f9a…","name":"myapp"}
  611. ```
  612. Events:
  613. | Event | When | Fields |
  614. |-------|------|--------|
  615. | `tunnel_ready` | Tunnel registered and accepting traffic | `protocol`, `public_url`, `public_addr` (host:port, tcp/udp only), `local_port`, `local_host`, `tunnel_id`, `name` |
  616. | `reconnecting` | Connection dropped, retry scheduled | `attempt`, `reason`, `delay_secs` |
  617. | `reconnected` | Reconnect succeeded (fresh `tunnel_ready` events follow) | None |
  618. | `error` | Fatal error; process exits with code 1 | `code` (`config`/`auth`/`tunnel`/`connection`/`protocol`/`io`), `message`, `hint` |
  619. | `token_created` | `token create --json` succeeded | `token`, `name`, `id` |
  620. Diagnostics still go to stderr, so stdout stays valid NDJSON. For the
  621. `http`, `tcp`, `udp`, and `p2p` commands the auth token can also be
  622. supplied via the `RUSTUNNEL_TOKEN` environment variable instead of
  623. `--token` (`start` reads tokens from the config file).
  624. ### Config file
  625. Default location: `~/.rustunnel/config.yml`
  626. ```yaml
  627. # ~/.rustunnel/config.yml
  628. # Tunnel server address (host:control_port)
  629. server: edge.rustunnel.com:4040
  630. # Auth token (from server admin_token or a token created via the dashboard)
  631. auth_token: YOUR_AUTH_TOKEN
  632. # Region preference: auto (probe & pick nearest), or eu / us / ap.
  633. # Omit for self-hosted / single-server setups.
  634. region: auto
  635. # Named tunnels started with `rustunnel start`
  636. tunnels:
  637. web:
  638. proto: http
  639. local_port: 3000
  640. subdomain: myapp # optional: server assigns one if omitted
  641. db:
  642. proto: tcp
  643. local_port: 5432
  644. ```
  645. Start all tunnels from the config file:
  646. ```bash
  647. rustunnel start
  648. # or with an explicit path
  649. rustunnel start --config /path/to/config.yml
  650. ```
  651. ### Token management
  652. **Hosted service:** manage tokens from the [rustunnel.com](https://rustunnel.com) dashboard under **Dashboard → API Keys**. You can create, label, and revoke tokens without any CLI commands.
  653. **Self-hosted:** create additional tokens via the dashboard API:
  654. ```bash
  655. rustunnel token create \
  656. --name "ci-deploy" \
  657. --server your-server:8443 \
  658. --admin-token YOUR_ADMIN_TOKEN
  659. ```
  660. Or via `curl`:
  661. ```bash
  662. curl -s -X POST https://your-server:8443/api/tokens \
  663. -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  664. -H "Content-Type: application/json" \
  665. -d '{"label": "ci-deploy"}'
  666. ```
  667. ---
  668. ## Port reference
  669. | Port | Protocol | Purpose |
  670. |------|----------|---------|
  671. | 80 | TCP | HTTP edge: redirects to HTTPS; also ACME HTTP-01 challenge |
  672. | 443 | TCP | HTTPS edge: TLS-terminated tunnel ingress |
  673. | 4040 | TCP | Control-plane WebSocket: clients connect here |
  674. | 8443 | TCP | Dashboard UI and REST API |
  675. | 9090 | TCP | Prometheus metrics (`/metrics`) |
  676. | 20000–20099 | TCP | TCP tunnel range (configurable via `tcp_port_range`) |
  677. | 20100–20199 | UDP | UDP tunnel range (configurable via `udp_port_range`) |
  678. ---
  679. ## Config file reference (server)
  680. | Key | Type | Default | Description |
  681. |-----|------|---------|-------------|
  682. | `server.domain` | string | None | Base domain for tunnel URLs |
  683. | `server.http_port` | u16 | None | HTTP edge port |
  684. | `server.https_port` | u16 | None | HTTPS edge port |
  685. | `server.control_port` | u16 | None | WebSocket control-plane port |
  686. | `server.dashboard_port` | u16 | `4040` | Dashboard port |
  687. | `tls.cert_path` | string | None | Path to TLS certificate (PEM) |
  688. | `tls.key_path` | string | None | Path to TLS private key (PEM) |
  689. | `tls.acme_enabled` | bool | `false` | Enable built-in ACME renewal |
  690. | `tls.acme_email` | string | `""` | Contact email for ACME |
  691. | `tls.acme_staging` | bool | `false` | Use Let's Encrypt staging CA |
  692. | `tls.acme_account_dir` | string | `/var/lib/rustunnel` | ACME state directory |
  693. | `tls.cloudflare_api_token` | string | `""` | Cloudflare DNS API token (prefer env var `CLOUDFLARE_API_TOKEN`) |
  694. | `tls.cloudflare_zone_id` | string | `""` | Cloudflare Zone ID (prefer env var `CLOUDFLARE_ZONE_ID`) |
  695. | `auth.admin_token` | string | None | Master auth token |
  696. | `auth.require_auth` | bool | None | Reject unauthenticated clients |
  697. | `auth.max_failed_auth_per_minute` | int | `10` | Failed auth attempts allowed per source IP per minute before further attempts are rejected (control-plane handshake and dashboard API); `0` disables |
  698. | `database.url` | string | None | PostgreSQL connection URL (required) |
  699. | `database.captured_path` | string | `/var/lib/rustunnel/captured.db` | Per-region SQLite file for captured HTTP request bodies |
  700. | `server.dashboard_origin` | string | `""` | Allowed CORS origin for the dashboard UI (e.g. `http://localhost:3000`) |
  701. | `logging.level` | string | None | `trace` / `debug` / `info` / `warn` / `error` |
  702. | `logging.format` | string | None | `json` or `pretty` |
  703. | `logging.audit_log_path` | string | `null` | Path for audit log (JSON-lines); omit to disable |
  704. | `limits.max_tunnels_per_session` | usize | None | Max tunnels per connected client |
  705. | `limits.max_connections_per_tunnel` | usize | None | Max concurrent connections per tunnel |
  706. | `limits.rate_limit_rps` | u32 | None | Per-tunnel request rate cap (req/s) |
  707. | `limits.ip_rate_limit_rps` | u32 | `100` | Per-source-IP rate cap (req/s); `0` = disabled |
  708. | `limits.request_body_max_bytes` | usize | None | Max proxied request body size (bytes) |
  709. | `limits.tcp_port_range` | [u16, u16] | None | Inclusive `[low, high]` TCP tunnel port range |
  710. | `limits.udp_port_range` | [u16, u16] | `[0, 0]` | Inclusive `[low, high]` UDP tunnel port range; `[0, 0]` disables UDP tunnels |
  711. | `region.id` | string | `"default"` | Region identifier recorded in tunnel history (e.g. `"eu"`, `"us"`, `"ap"`) |
  712. | `region.name` | string | `"Default"` | Human-readable region name shown in the dashboard |
  713. | `region.location` | string | `""` | Physical location label (e.g. `"Helsinki, FI"`) |
  714. ---
  715. ## Monitoring
  716. A Prometheus metrics endpoint is available at `:9090/metrics`:
  717. ```
  718. rustunnel_active_sessions # gauge: connected clients
  719. rustunnel_active_tunnels_http # gauge: active HTTP tunnels
  720. rustunnel_active_tunnels_tcp # gauge: active TCP tunnels
  721. ```
  722. Start with the full monitoring stack (Prometheus + Grafana):
  723. ```bash
  724. make docker-run-monitoring
  725. # Grafana: http://localhost:3000 (admin / changeme)
  726. # Prometheus: http://localhost:9090
  727. ```
  728. > **Production note:** The default Grafana password is `changeme`. Set the `GRAFANA_PASSWORD` environment variable before starting the stack in production:
  729. > ```bash
  730. > export GRAFANA_PASSWORD=your-strong-password
  731. > make docker-run-monitoring
  732. > ```
  733. ---
  734. ## REST API
  735. The dashboard port exposes a REST API for programmatic access to tunnels, tokens, captured requests, and tunnel history. All endpoints (except the health check) require an `Authorization: Bearer <token>` header.
  736. `/api/tunnels`, `/api/groups`, and their per-tunnel sub-resources are scoped by caller: the admin token sees everything; a user-scoped API token sees only its own tunnels and groups; tunnels the caller can't see return `404`, never `403`. See [docs/api-reference.md § Visibility scope](docs/api-reference.md#visibility-scope) for the full rules.
  737. **Quick reference**
  738. | Method | Path | Description |
  739. |--------|------|-------------|
  740. | `GET` | `/api/status` | Health check (no auth) |
  741. | `GET` | `/api/tunnels` | List active tunnels |
  742. | `GET` | `/api/tunnels/:id` | Get a single tunnel |
  743. | `DELETE` | `/api/tunnels/:id` | Force-close a tunnel |
  744. | `GET` | `/api/tunnels/:id/requests` | Captured HTTP requests |
  745. | `POST` | `/api/tunnels/:id/replay/:req_id` | Fetch stored request for replay |
  746. | `GET` | `/api/tokens` | List API tokens |
  747. | `POST` | `/api/tokens` | Create an API token |
  748. | `DELETE` | `/api/tokens/:id` | Delete an API token |
  749. | `GET` | `/api/history` | Paginated tunnel history |
  750. Full request/response schemas, query parameters, and examples are in
  751. [**docs/api-reference.md**](docs/api-reference.md).
  752. A machine-readable OpenAPI 3.0 spec is served at `GET /api/openapi.json` (no auth required).
  753. ---
  754. ## AI agent integration (MCP server)
  755. rustunnel ships a `rustunnel-mcp` binary that implements the
  756. [Model Context Protocol](https://spec.modelcontextprotocol.io) over stdio,
  757. letting AI agents (Claude, GPT-4o, custom agents) open and manage tunnels
  758. without any manual intervention.
  759. **Works with any MCP harness.** For copy-paste config for Claude Code, Claude
  760. Desktop, Codex, Cursor, Windsurf, Cline, and custom agents, plus a one-command
  761. installer, see the **[Agent Integration Guide](docs/agent-integration.md)**:
  762. ```bash
  763. ./integrations/install.sh # prompts for your token, writes the config
  764. ```
  765. ### Quick setup (Claude Desktop, hosted server)
  766. ```json
  767. {
  768. "mcpServers": {
  769. "rustunnel": {
  770. "command": "rustunnel-mcp",
  771. "args": [
  772. "--server", "edge.rustunnel.com:4040",
  773. "--api", "https://edge.rustunnel.com:8443"
  774. ],
  775. "env": { "RUSTUNNEL_TOKEN": "<your-token>" }
  776. }
  777. }
  778. }
  779. ```
  780. Set `RUSTUNNEL_TOKEN` once and the agent never has to pass a token on a tool call.
  781. ### Available tools
  782. | Tool | Description |
  783. |------|-------------|
  784. | `create_tunnel` | Open a tunnel and return the public URL: HTTP/TCP/UDP, P2P, and load-balanced pools with health checks |
  785. | `list_tunnels` | List all active tunnels |
  786. | `close_tunnel` | Force-close a tunnel by ID |
  787. | `list_regions` | List available server regions |
  788. | `get_connection_info` | Return the CLI command for cloud/sandbox agents |
  789. | `get_tunnel_history` | Retrieve past tunnel activity |
  790. ### Installation
  791. **Homebrew (macOS and Linux):** installs `rustunnel-mcp` alongside the CLI:
  792. ```bash
  793. brew tap joaoh82/rustunnel
  794. brew install rustunnel
  795. ```
  796. **Build from source:**
  797. ```bash
  798. make release-mcp
  799. sudo install -m755 target/release/rustunnel-mcp /usr/local/bin/rustunnel-mcp
  800. ```
  801. Full setup guide, configuration options, and workflow examples are in
  802. [**docs/mcp-server.md**](docs/mcp-server.md).
  803. ### Claude Code plugin
  804. The easiest way to use rustunnel with [Claude Code](https://claude.com/claude-code).
  805. Install the plugin and it handles all MCP configuration automatically. Just enter
  806. your token once and start asking Claude to expose ports.
  807. ```
  808. /plugin install rustunnel
  809. ```
  810. The plugin prompts for your server address and API token at enable time, stores
  811. them securely, and starts the MCP server in the background. No `.mcp.json` editing
  812. or manual setup needed.
  813. **Plugin directory:** [`plugins/claude-code/`](plugins/claude-code/)
  814. **Documentation:** [docs/claude-plugin.md](docs/claude-plugin.md)
  815. ### OpenClaw skill
  816. rustunnel ships an [OpenClaw](https://openclaw.dev) skill that gives any
  817. OpenClaw-compatible AI agent first-class knowledge of rustunnel: config file
  818. format, authentication, tool signatures, and common workflows, without you
  819. having to explain it.
  820. **Skill file:** [`skills/rustunnel/SKILL.md`](skills/rustunnel/SKILL.md)
  821. **What it covers:**
  822. | Topic | Details |
  823. |-------|---------|
  824. | Config file | Location (`~/.rustunnel/config.yml`), format, named tunnels |
  825. | First-time setup | `rustunnel setup` wizard or manual config creation |
  826. | MCP tools | `create_tunnel`, `list_tunnels`, `close_tunnel`, `get_connection_info`, `get_tunnel_history` |
  827. | Workflows | Webhook testing, demo sharing, cloud sandbox (no subprocess), named tunnels |
  828. | Security | Token handling, file permissions, HTTPS-only transport |
  829. **To load the skill in Claude Code:**
  830. ```bash
  831. /skills load skills/rustunnel/SKILL.md
  832. ```
  833. Once loaded, you can ask the agent things like:
  834. > "Expose my local port 3000 as an HTTPS tunnel using rustunnel."
  835. > "List my active tunnels and close the one forwarding port 5432."
  836. > "Set up my rustunnel config file with my token."
  837. The skill instructs the agent to read credentials from `~/.rustunnel/config.yml`
  838. automatically, so you won't be prompted for your token on every invocation.
  839. ---
  840. ## Roadmap
  841. A detailed list of shipped features and planned future work is maintained in
  842. [**docs/ROADMAP.md**](docs/ROADMAP.md).
  843. ---
  844. ## Contributing
  845. Contributions are welcome! Please follow these steps:
  846. 1. **Fork** the repository and create a feature branch from `main`.
  847. 2. Run `make install-hooks` once after cloning to activate the pre-push quality gate.
  848. 3. Make your changes. Ensure `make check` (fmt + Clippy) and `make test` pass locally.
  849. 4. Open a **Pull Request** with a clear description of what changed and why.
  850. 5. A maintainer will review and merge once CI is green.
  851. ### Guidelines
  852. - Keep PRs focused: one logical change per PR.
  853. - Add or update tests for any new behaviour.
  854. - Follow the existing code style; `cargo fmt` is enforced by CI.
  855. - For larger changes or new features, open an issue first to discuss the approach.
  856. ---
  857. ## License
  858. This project is licensed under the **GNU AGPLv3 License**. See the [LICENSE](LICENSE) file for details.
  859. ---
  860. ## Contact
  861. **João Henrique Machado Silva**
  862. - GitHub: [@joaoh82](https://github.com/joaoh82)
  863. - Project: [github.com/joaoh82/rustunnel](https://github.com/joaoh82/rustunnel)
  864. - Issues & feature requests: [GitHub Issues](https://github.com/joaoh82/rustunnel/issues)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.