krot
Self-hosted ngrok in Rust. Zero-knowledge, thread-per-core, passwordless.
krot is an open-source tunneling service: your own VPS, one Docker
container, no subscription and no trust in a third-party relay. HTTPS
traffic passes through the server encrypted end-to-end to the tunnel
client, authorization keys are SSH-style (authorized_keys), and the
apex-domain certificate is obtained and renewed by the server itself
via ACME.
Written in stable Rust on top of tokio, quinn (QUIC) and rustls.
A single binary (~7 MB, release + LTO + strip), Docker image ~85 MB on
debian-slim.
- What's inside
- Installation
- Quick start
- CLI reference
- Admin API
- Architecture
- Federated relays
- Security
- Known limitations
- Development
- Contributing
- Reporting security issues
- License
What's inside
| QUIC + TCP fallback | Primary transport is QUIC over UDP. Clients behind corporate NATs that block UDP transparently fall back to TLS 1.3 over TCP with a mini-mux. Same port, distinguished by ALPN. |
| Zero-knowledge apex TLS | The server terminates TLS only on the apex (krot.example). Connections to alice.krot.example go via SNI-passthrough — the server sees only an encrypted stream. Subdomain private keys never touch the server. |
| Thread-per-core | Every core gets an isolated tokio current-thread runtime and its own QUIC endpoint via SO_REUSEPORT. Rate limits are partitioned per-core — each worker has its own bandwidth bucket, the aggregate cap is respected. |
| Passwordless Ed25519 bootstrap | The client generates an Ed25519 key and knocks with a one-shot admin token (32 bytes of entropy, BLAKE3-hashed on disk, 10-minute TTL). The server appends the pubkey to authorized_keys. |
| ACME auto-renewal | Built-in HTTP-01 responder on port 80. Let's Encrypt certificate for the apex, renewal 30 days before expiry. Cache in data_dir/acme/, mode 0700. |
| Session resume | Client crashed? On reconnect it re-attaches to the same public_url within a 30-second grace period. Works across transports — you can drop a QUIC session and restore it over the TCP fallback. |
| Rate limiting | Per-identity token-bucket via governor plus a period quota. Fully partitioned per-core, the aggregate cap is respected. When the quota is exhausted the server sends the client retry_after_ms. |
| Passive HTTP inspector | --inspect enables a local admin UI on localhost:4040 — method, path, status, and duration of every request. |
| Login-page auth | krot http --auth user:pass serves a styled sign-in page with the krot brand mark; a successful login installs a session cookie (HttpOnly; SameSite=Lax, 8h rolling TTL). For machines — --api-key SECRET (X-API-Key / Authorization: Bearer). File/env variants for non-dev use. Constant-time compare, no secrets in logs. |
| Admin API | /admin/v1/{tunnels,keys,metrics} HTTP endpoint on 127.0.0.1:9700. Bearer-token auth, Prometheus metrics, key revocation in under 1 second. |
| Federated relays | Multi-relay setup: federation=peer1,peer2 in authorized_keys. The client publishes one tunnel on several relays, DNS/CDN handles failover. |
| Hot-reload of authorization | Key removed from authorized_keys? Active sessions get a revoke notification within <1s via the notify watcher. Same mechanism for the peer list. |
| Graceful shutdown | Ctrl+C sends a clean ServerBye to every open session, waits for ACKs, then closes the endpoint. Deadline 5 seconds. |
Installation
Four ways to get krot-server and krot-client binaries.
Prebuilt binaries (recommended)
Download from the latest release:
| Platform | Archive |
|---|---|
| Linux · x86_64 | krot-vX.Y.Z-x86_64-unknown-linux-musl.tar.gz |
| Linux · ARM64 | krot-vX.Y.Z-aarch64-unknown-linux-musl.tar.gz |
| macOS · Apple Silicon | krot-vX.Y.Z-aarch64-apple-darwin.tar.gz |
| Windows · 64-bit | krot-vX.Y.Z-x86_64-pc-windows-msvc.zip |
| Windows · 32-bit | krot-vX.Y.Z-i686-pc-windows-msvc.zip |
Each archive contains krot-server, krot (the client CLI), LICENSE-*, README.md. Verify the accompanying .sha256, extract, and move the binaries into your PATH. Intel Mac users: run the aarch64-apple-darwin build under Rosetta 2, or use cargo install --git below.
With cargo
Requires a stable Rust toolchain (get one from rustup.rs):
Binaries land in ~/.cargo/bin/ on unix or %USERPROFILE%\.cargo\bin\ on Windows.
With Docker (server only)
Multi-arch image (linux/amd64, linux/arm64).
From source
# → target/release/krot-server, target/release/krot-client
Quick start
Prerequisites: a VPS with a public IP, your own domain, wildcard DNS
*.krot.example → <VPS IP>, ports 80/443/7853 open.
1. Server
# prebuilt image from Docker Hub — recommended:
# or build locally:
# docker build -t krottunnel/krot-server:dev .
# the server prints a one-shot admin token:
|
# KROT_ADMIN_TOKEN=R54VHZ9FD0JJ44GPDZFEJZ7DV8WFB77JHYHVPFF64BF677X7WX70
Root/privileges. Defaults
--http-bind 0.0.0.0:80and--https-bind 0.0.0.0:443are privileged ports. The Docker container above runs via-p 80:80/tcp, where Docker handles the mapping. Running without Docker requires eithersudoorsetcap 'cap_net_bind_service=+ep' target/release/krot-server. For local development, remap to unprivileged ports:--http-bind 127.0.0.1:8080 --https-bind 127.0.0.1:8443.
2. Client
# → enrolled at krot.example:7853
3. Publish a local service
# → https://alice.krot.example
# → inspector: http://127.0.0.1:4040
Done. External requests to https://alice.krot.example flow through
the server, TLS-encrypted end-to-end to your client.
CLI reference
krot-server
| Flag | Default | What it does |
|---|---|---|
--domain <apex> |
— | Enables DomainMode. Without it — IpMode (TCP tunnels only, self-signed cert with pinned fingerprint). |
--acme-contact mailto:... |
— | Obtain the apex certificate via ACME (Let's Encrypt staging by default). |
--acme-production |
off | Switch to LE production. |
--tls-cert / --tls-key |
— | Alternative to ACME — bring your own PEM certificate. |
--bind |
0.0.0.0:7853 |
UDP address of the QUIC endpoint. |
--tcp-fallback-bind <addr> |
disabled | TCP+TLS listener for clients with UDP blocked. |
--http-bind / --https-bind |
0.0.0.0:80 / :443 |
Addresses for the 80/443 routers. |
--tcp-port-pool <lo-hi> |
10000-19999 |
Port pool for TCP tunnels. |
--cores N |
available_parallelism() |
Number of worker threads. The bw= cap is partitioned per-core. |
--data-dir |
/var/lib/krot |
Persistent state (identity cert, ACME cache, admin_token hash). |
--authorized-keys |
/etc/krot/authorized_keys |
SSH-style file of authorized keys. Hot-reload. |
--peer-list |
/etc/krot/peers.txt |
Static list of federated relays (one apex per line). Hot-reload. |
--admin-bind |
127.0.0.1:9700 |
Structured admin API. Empty value disables it. |
--issue-admin-token |
off | Issue a new admin token even if authorized_keys is non-empty. |
krot (client)
| Subcommand | What it does |
|---|---|
krot init --server HOST --admin-token TOKEN [--fingerprint sha256:HEX] |
Generate identity, enroll the public key. IpMode uses the pinned fingerprint; DomainMode uses a real CA. |
krot tcp <port> |
Publish a TCP service (ssh, DB, minecraft, anything) as tcp://<host>:<port>. |
krot http <port> [flags] |
Publish an HTTP service as https://<label>.<apex>. See auth flags below. |
Client auth flags (only for krot http, apply on the plain-HTTP
branch; HTTPS-passthrough remains opaque):
| Flag | Description |
|---|---|
--auth <user:pass> |
Styled login page + session cookie (HttpOnly; SameSite=Lax, 8h rolling TTL). Special paths /__krot/login and /__krot/logout are intercepted by the client. Dev only — credentials show up in ps. |
--auth-env <VAR> |
Same, but reads user:pass from an environment variable. |
--auth-file <path> |
Same, but reads user:pass from a file (single line, trims trailing newlines). |
--api-key <SECRET> / --api-key-env / --api-key-file |
Header-based auth for machines: X-API-Key: <key> or Authorization: Bearer <key>. 403 on mismatch. |
--auth-realm <string> |
Internal string, shown only in diagnostics of the API-key branch. Default "KROT Protected Tunnel". |
--name <label> |
Requested subdomain label (default: random). |
--inspect / --inspect-bind <addr> |
Local admin UI with request history. |
Automatic fallback
The client tries QUIC first, and on a transport-level failure retries via TCP fallback. Transparent to the user.
Admin API
Structured HTTP endpoint on 127.0.0.1:9700 for the operator.
Bearer-token auth.
# Exchange the enrollment admin_token for a session_token (single-use):
# → {"session_token":"XXXX","expires_at_unix":1735000000}
TOKEN=XXXX
# List tunnels
# → [{"tunnel_id":1,"kind":"http","label":"alice","state":"live","inspect":false,...}]
# List authorized keys
# Add a key (append to authorized_keys)
# Revoke: within <1s hot-reload kills active sessions of this key
# Prometheus metrics (~30 counters + gauges)
# → krot_uptime_seconds 42
# → krot_build_info{version="0.1.0"} 1
# → krot_tunnels_total 3
# → krot_handshake_auth_ok_total 12
# → krot_session_bye_total 8
# → krot_resume_reattached_total 3
# → krot_rate_limit_quota_exceeded_total 4
# → krot_transport_quic_accepted_total 20
# → krot_transport_tcp_fallback_accepted_total 5
# → krot_bytes_period_used{pubkey="AAAA..."} 1234567
JSON logging (for log-aggregation — Loki, Elastic, etc.):
KROT_LOG_FORMAT=json RUST_LOG=info
# → {"timestamp":"...","level":"INFO","fields":{"message":"..."},...}
A publicly-exposed admin API MUST sit behind a TLS reverse-proxy (nginx / caddy). The loopback default is safe.
Architecture
Workspace crates:
| Crate | Role |
|---|---|
krot-proto |
Wire types, framing, Ed25519 challenge-response, inspector prelude. |
krot-transport |
Connection/stream wrappers with two backends: QUIC and mux-over-TCP. ALPN + keep-alive. |
krot-server |
Relay: registry, auth handshake, ACME, SNI/Host routers, thread-per-core, admin API, peer registry, rate limiting. |
krot-client |
CLI + enroll flow + inspector + auto-fallback + login-page/API-key auth. |
Federated relays
One identity → multiple relays at once. Live URLs work from all of them.
Step 1 — set up the peer list on each relay:
# on relay-1 (krot.us.example):
# hot-reload picks it up immediately
Step 2 — authorized_keys with federation=:
ed25519 AAAA... subdomain=alice federation=krot.eu.example,krot.asia.example
Step 3 — the client polls the peer list and publishes on the allowed relays:
# → https://alice.krot.us.example
# → https://alice.krot.eu.example
# → https://alice.krot.asia.example
Cross-relay collision detection. On label registration, the
server consults neighboring relays:
- If a peer already has this
labelfrom the same identity → additional destination (allow, log). - If from a different identity → reject with
LABEL_UNAVAILABLE. - Peer unreachable → fail-open.
Security
| Threat | Mitigation |
|---|---|
| MITM client↔server | IpMode: SPKI SHA-256 pin via --fingerprint sha256:.... DomainMode: public CA. |
| Subdomain private-key leak | The server does not store them. The client terminates TLS itself or forwards the encrypted stream. |
| Identity theft | Identity in ~/.krot/identity mode 0600. Rotation = generate a new one, remove the old line from authorized_keys. Hot-reload kills active sessions within <1s. |
| Replay of challenge signature | Domain separator prefixed to every Ed25519 signature. |
| Admin-token bruteforce | 32 bytes of entropy + BLAKE3 constant-time compare + single-use + 10-minute TTL. |
| Login-page bruteforce | Rate-limiting the brute-force is on the operator (reverse-proxy). Wrong/missing credentials return an identical page with a generic message. Session cookie = 32 bytes of entropy from OsRng, in-memory store. |
| DoS via spoofed UDP | QUIC session tickets + per-identity bandwidth limits. Unknown identities do not take space in the rate table. |
| Frame parser panic | Bounded allocations (64 KiB frames, 8 KiB HTTP, 256 KiB mux). Property tests + fuzz targets. |
| Cross-relay label spoofing | Collision detection consults peers before allocation. Same-identity → additional destination, different → reject. |
Known limitations
- Continuous soak testing. There's
scripts/soak/for a manual two-VDS run; automated soak in CI is not wired up yet. - DomainMode multi-level subdomains (
a.b.krot.example) fail validation — only one level is supported. - IPv6-only VPS should work but is not tested in CI.
Development
# All crates, all tests.
# Style / lint checks (matches CI).
# Deep proptest sweep (default is 256 cases, bump manually):
PROPTEST_CASES=10000
# Local server + client in two terminals:
# (grab KROT_ADMIN_TOKEN and KROT_SERVER_FINGERPRINT from stdout)
Changelog: CHANGELOG.md.
CI: .github/workflows/ci.yml —
fmt/clippy/test on Linux+macOS, MSRV pin, cargo audit, 60s fuzz
smoke per target.
Contributing
Bug reports, feature requests, and patches are welcome.
Before opening a pull request:
- Run
just ci(fmt + clippy + tests). This must be green. - For user-visible changes, add a line to
CHANGELOG.mdunder a new version heading. - Keep commits focused — one logical change per commit.
New to Rust or to this codebase? The Development section above walks through running a local server + client pair; that's the fastest way to get oriented.
Reporting security issues
Please do not open a public GitHub issue for security vulnerabilities.
Use GitHub's private security advisory form to report privately. Expect a first reply within 72 hours.
Coordinated disclosure timeline: 90 days from the initial report unless mutually extended.
License
Licensed under either of
- MIT license (LICENSE-MIT)
- Apache License, Version 2.0 (LICENSE-APACHE)
at your option.
SPDX-License-Identifier: MIT OR Apache-2.0
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.