Skip to main content
Contributions are welcome! rustunnel is open-source under the AGPLv3 license. Whether it’s a bug fix, a new feature, or improved documentation, we appreciate your help.

​
Before you start

For larger changes or new features, open an issue first to discuss the approach. This avoids duplicate effort and ensures the change is aligned with the project direction. For small fixes (typos, docs, minor bugs) you can go straight to a pull request.

​
Getting started

1

Fork and clone

Fork the repository on GitHub, then clone your fork:
git clone https://github.com/<your-username>/rustunnel.git
cd rustunnel
2

Install dependencies

You need:
ToolVersionNotes
Rust toolchain1.76+Install via rustup
pkg-configanyRequired by reqwest (TLS)
libssl-devanyOn Debian/Ubuntu: apt install libssl-dev
Node.js + npm18+Only needed to rebuild the dashboard UI
DockeranyRequired to run the test database
3

Install git hooks

Run this once after cloning to activate the pre-push quality gate:
make install-hooks
Every git push will automatically run cargo fmt checks and cargo clippy before the push is allowed.
4

Create a feature branch

Branch off main with a descriptive name:
git checkout -b fix/heartbeat-timeout
# or
git checkout -b feat/tcp-region-selection

​
Local development

​
Build

# Debug build (fast compile)
cargo build --workspace

# Or via Make
make build

​
Run the server locally

Generate a self-signed certificate for local testing: 
mkdir -p /tmp/rustunnel-dev

openssl req -x509 -newkey rsa:2048 \
  -keyout /tmp/rustunnel-dev/key.pem \
  -out    /tmp/rustunnel-dev/cert.pem \
  -days 365 -nodes \
  -subj "/CN=localhost"
Start the server with the checked-in local config: 
cargo run -p rustunnel-server -- --config deploy/local/server.toml

​
Run the client locally

With the server running, expose a local service: 
# HTTP tunnel
cargo run -p rustunnel-client -- http 3000 \
  --server localhost:4040 \
  --token dev-secret-change-me \
  --insecure

# TCP tunnel
cargo run -p rustunnel-client -- tcp 5432 \
  --server localhost:4040 \
  --token dev-secret-change-me \
  --insecure
--insecure skips TLS verification — required when using the self-signed cert. Never use it against a production server.

​
Running tests

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. 
# Start the local PostgreSQL container (persists across reboots)
make db-start

# Full suite: unit + integration
make test

# With output visible
TEST_DATABASE_URL=postgres://rustunnel:test@localhost:5432/rustunnel_test \
  cargo test --workspace -- --nocapture

# Run a single test
TEST_DATABASE_URL=postgres://rustunnel:test@localhost:5432/rustunnel_test \
  cargo test <test_name> -p <crate_name>

# Stop PostgreSQL when done
make db-stop

​
Code quality

Before opening a PR, make sure these pass: 
# Format check
cargo fmt --all -- --check

# Lint (zero warnings policy)
cargo clippy --workspace --all-targets -- -D warnings

# Both at once
make check
CI runs the same checks on every push and pull request.

​
Opening a pull request

  1. Push your branch to your fork and open a PR against main.
  2. Write a clear description of what changed and why.
  3. Make sure CI is green — format, Clippy, and all tests.
  4. A maintainer will review and merge.

​
PR guidelines

  • Keep PRs focused — one logical change per PR. Avoid bundling unrelated fixes.
  • Add or update tests for any new behaviour. The integration test suite in tests/integration/ is the right place for end-to-end scenarios.
  • Follow existing code style — cargo fmt is enforced by CI.
  • Update documentation if you change user-facing behaviour (flags, config keys, API endpoints).

​
Project structure

PathPurpose
crates/rustunnel-protocol/Shared ControlFrame types and serialization
crates/rustunnel-server/Server: control plane, HTTP/TCP edges, dashboard, TLS
crates/rustunnel-client/CLI client with auto-reconnect and local port forwarding
crates/rustunnel-mcp/MCP server for AI agent integration
dashboard-ui/Next.js dashboard frontend
deploy/Dockerfiles, compose files, systemd unit, config templates
tests/integration/End-to-end tests (real server + real PostgreSQL)
docs/Public documentation source

​
Useful make targets

TargetDescription
make buildDebug build of all workspace crates
make releaseOptimized release build
make checkcargo fmt check + cargo clippy
make testFull test suite (requires make db-start)
make db-startStart the local PostgreSQL container
make db-stopStop the local PostgreSQL container
make install-hooksInstall the pre-push git hook
make docker-buildBuild the server Docker image

​
License

By contributing you agree that your work will be licensed under the GNU AGPLv3 License.

​
Contact

João Henrique Machado Silva