FastGateway is a self-hosted reverse-proxy and tunnel gateway. It combines a JWT-protected management API, a React dashboard, dynamically managed HTTP/HTTPS gateways, TCP/UDP L4 forwarding, and TunnelClient-based access to private services.
Document Language: English | 简体中文
FastGateway is a single deployable control plane and proxy runtime. src/FastGateway hosts the management API and dashboard, and creates one in-process Kestrel/YARP gateway for each enabled Server configuration. TunnelClient is an independent outbound agent for private services.
┌─────────────────────────────┐
Browser / clients ──HTTP(S)/H2/H3►│ FastGateway │
│ management host │
│ JWT API + React dashboard │
└──────────────┬──────────────┘
│
┌─────────────────────────────────────────┼───────────────────────────────────────┐
▼ ▼ ▼
per-Server Kestrel + YARP Tunnel manager L4 stream manager
domain/path routes HTTP/2 CONNECT / WebSocket TCP / UDP / Both
service/cluster/static/tunnel ⇄ TunnelClient upstream pool
│ │ │
▼ ▼ ▼
HTTP services and files local services TCP/UDP services
| Path | Responsibility |
|---|---|
src/FastGateway |
Main ASP.NET Core host, JWT API, static dashboard hosting, dynamic HTTP gateways, certificates, access control, rate limiting, statistics, file storage, and tunnel management. |
src/FastGateway/Gateway |
Per-server YARP route/cluster construction and the TCP/UDP StreamProxyManager. |
src/FastGateway/Services |
Minimal API endpoint groups and configuration-backed business services. |
src/FastGateway/Middleware |
Client-IP resolution, statistics, timeout, access-control, failover, proxy-error, and abnormal-IP middleware. |
src/FastGateway/Tunnels |
Server-side tunnel registration, agent lifecycle, control channels, and per-request tunnel streams. |
src/TunnelClient |
Standalone tunnel agent. Reads tunnel.json, connects to the gateway over HTTP/2 or WebSocket, and forwards traffic to local services through YARP. |
src/Core |
Shared stream wrappers and gateway entities/enums used by the server and agent. |
src/Certes |
Vendored, Newtonsoft.Json/BouncyCastle-free, AOT-compatible ACME client used for Let's Encrypt certificates. |
web |
React 19 + TypeScript + Vite dashboard. Docker and release builds copy its dist output into src/FastGateway/wwwroot. |
PrograminitializesFastGatewayOptions, JWT authentication, background services, and the JSON-backedConfigurationService.- The configuration service loads
data/gateway.config(creating it when absent) and atomically writes changes back to disk. - Enabled
Serverrecords create independent Kestrel/YARP gateway instances. EnabledStreamForwardrecords start TCP/UDP listeners inStreamProxyManager. - Each domain route is compiled into an in-memory YARP route and cluster. A route can target one service, a service cluster, a local static-file root, or a registered tunnel node (
node_<name>). - Gateway middleware resolves the client IP, handles ACME HTTP-01 challenges and HTTPS redirects, collects statistics, applies timeouts/rate limits/blacklists, performs failover and error handling, then forwards through YARP.
- The explicit reload APIs and tunnel registration update the in-memory route provider without requiring a process restart; configuration persistence and gateway lifecycle are handled separately by the management APIs.
TunnelClient is started with -c <config-file>, registers its node with /internal/gateway/Server/register, and maintains a control connection to /internal/gateway/Server. The transport type is h2 (HTTP/2 CONNECT) or ws (WebSocket); both use the FastGateway sub-protocol. When a public request matches a tunnel route, the server allocates a tunnel ID, the agent opens the corresponding data stream, and the two sides copy bytes bidirectionally to the local service.
The backend uses ASP.NET Core Minimal APIs. The main groups are /api/v1/authorization, /server, /domain, /cert, /tunnel, /stream-forward, /black-and-white, /rate-limit, /abnormal-ip, /statistics, /qps, /filestorage, /setting, and /system. Most management groups require the JWT issued by POST /api/v1/authorization.
All paths below are relative to the application directory; in the Docker image that directory is /app.
| Path | Purpose |
|---|---|
data/gateway.config |
Persistent gateway, domain, certificate, access-control, rate-limit, setting, and L4 forwarding configuration. |
data/stats.db |
SQLite request-statistics database used by the statistics background service. |
data/keys/ |
ACME account keys cached by email for certificate renewal. |
certs/ |
Generated or uploaded PFX certificates selected by SNI. |
gateway.pfx |
Packaged fallback certificate used when no matching certificate is available. |
ip2region.xdb |
Optional offline IP geolocation database used for traffic analysis. |
- Login authorization
- Automatic HTTPS certificate application (Let's Encrypt / HTTP-01)
- Automatic HTTPS certificate renewal
- Wildcard domain certificates (Let's Encrypt / DNS-01)
- Upload custom HTTPS certificates (PFX / PEM)
- Dashboard monitoring
- Static file service
- Single service proxy
- Cluster proxy
- TCP/UDP L4 port forwarding
- TunnelClient-based private service forwarding
- Upstream health checks and request-level failover
- Traffic statistics and IP geolocation
- Request source analysis
- Support for custom rate limiting policies
- Support for black and white lists
FastGateway supports three ways to provide HTTPS certificates for your domains, all managed from the Certificate Management page:
-
Automatic (Let's Encrypt, HTTP-01) — For a normal domain (e.g.
example.com), add the domain and email, then click Apply. The gateway completes the ACME HTTP-01 challenge automatically (an enabled port-80 service is required) and renews the certificate before it expires. -
Wildcard domain (Let's Encrypt, DNS-01) — For a wildcard domain (e.g.
*.example.com), HTTP-01 cannot be used. Add the domain, then click DNS Verify: the gateway generates a_acme-challengeTXT record for you to add at your DNS provider. Once the record has propagated, click Verify & Issue to complete the challenge. Wildcard certificates issued this way are not auto-renewed — re-run the DNS verification before they expire. -
Upload your own certificate — Click Upload Certificate to use a certificate you already own. Two formats are supported:
- PFX / P12 — upload the
.pfx/.p12file together with its password (leave empty if it has none). - PEM / CRT — upload the certificate (
.pem/.crt) and its private key (.key) separately.
Uploaded certificates (including wildcard ones) are matched by SNI and do not participate in automatic renewal; upload a new file before expiry. Uploaded certificates are converted to and stored as
.pfxunder thecertsdirectory. - PFX / P12 — upload the
- .NET 10 and ASP.NET Core Minimal APIs
- Kestrel with HTTP/1.1, HTTP/2, and HTTP/3 support for configured HTTPS gateways
- YARP 2.3 for reverse proxy routing, clusters, health checks, and forwarding
- JWT Bearer authentication for the management API
- JSON file persistence for gateway configuration (
data/gateway.config) - Microsoft.Data.Sqlite for request statistics (
data/stats.db) - AspNetCoreRateLimit for configurable rate-limit policies
- Certes ACME client for Let's Encrypt HTTP-01/DNS-01 certificate workflows
- IP2Region.Net and
ip2region.xdbfor offline IP attribution
- React 19, TypeScript, and Vite
- React Router for dashboard routing and lazy-loaded pages
- Ant Design and Radix UI for controls and interaction primitives
- Tailwind CSS v4 for styling
- ECharts/Recharts for traffic and dashboard visualizations
The container uses port 8080 for the management UI/API. HTTP/HTTPS listener ports are opened by enabled Server records in the dashboard.
mkdir -p data certs
docker run -d --restart=always --name=fast-gateway \
-e PASSWORD='change-this-password' \
-e TunnelToken='change-this-tunnel-token' \
-p 8080:8080 \
-p 80:80/tcp \
-p 443:443/tcp \
-p 443:443/udp \
-v "$(pwd)/data:/app/data" \
-v "$(pwd)/certs:/app/certs" \
aidotnet/fast-gateway:latestOpen http://localhost:8080 after the container starts. If no password is supplied, the current fallback is Aa123456; replace it before exposing the management endpoint.
The checked-in docker-compose.yml builds src/FastGateway/Dockerfile, persists data and certs, and maps the management endpoint to port 8000:
docker compose -f docker-compose.yml up -d --buildIt maps 8000:8080, 80:80, and both 443/tcp and 443/udp for HTTP/3. For a pre-built multi-architecture image, use aidotnet/fast-gateway:latest as the image and remove the build section. Set PASSWORD and TunnelToken in the Compose environment for production deployments.
Download the Linux zip file, then unzip the program, and use nano to create fastgateway.service
nano /etc/systemd/system/fastgateway.serviceRemember to replace the configuration when filling in the following content:
[Unit]
Description=FastGateway
[Service]
WorkingDirectory=/opt/fastgateway
ExecStart=/opt/fastgateway/FastGateway
Restart=always
# Restart service after 10 seconds if the dotnet service crashes:
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=dotnet-fastgateway
User=root
Environment=ASPNETCORE_ENVIRONMENT=Production
[Install]
WantedBy=multi-user.targetNext, reload systemd to make the new service unit file take effect:
systemctl daemon-reloadNow you can start the service:
systemctl start fastgateway.serviceTo enable the service to start automatically at system boot, enable it:
systemctl enable fastgateway.serviceYou can check the status of the service with the following command:
systemctl status fastgateway.serviceIf you need to stop the service, you can use:
systemctl stop fastgateway.serviceIf you have made changes to the service and need to reload the configuration, you can restart the service:
systemctl restart fastgateway.serviceRequirements: .NET 10 SDK, Node.js 20+ with npm, and the native toolchain required by the target build. The default project settings enable Native AOT analysis/publishing for the main applications; use -p:PublishAot=false when producing a portable single-file artifact as the release workflow does.
# Build the .NET solution
dotnet build FastGateway.sln
# Build the dashboard
cd web
npm install
npm run build
cd ..
# Run the management host with the launch profile (http://localhost:5202)
dotnet run --project src/FastGateway/FastGateway.csproj
# Run a tunnel client; -c is required by the client entry point
dotnet run --project src/TunnelClient/TunnelClient.csproj -- -c ./src/TunnelClient/tunnel.jsonFor dashboard-only development, run npm run dev in web; Vite proxies /api to the backend at http://localhost:5202. Docker builds the dashboard in a Node 22 stage, then publishes the FastGateway Native AOT image for linux/amd64 and linux/arm64. The Release workflow publishes self-contained single-file FastGateway and TunnelClient archives for Linux, Windows, and macOS on x64 and ARM64.
Pre-built, self-contained binaries are published on the Releases page for the following platforms:
| OS | x64 | ARM64 |
|---|---|---|
| Linux | fastgateway-linux-x64.tar.gz |
fastgateway-linux-arm64.tar.gz |
| Windows | fastgateway-win-x64.zip |
fastgateway-win-arm64.zip |
| macOS | fastgateway-osx-x64.tar.gz |
fastgateway-osx-arm64.tar.gz |
The TunnelClient component is published for the same set of platforms (tunnelclient-<runtime> archives).
The Docker image aidotnet/fast-gateway is a multi-arch image supporting both linux/amd64 and linux/arm64, so docker run/docker compose automatically pulls the right variant for your host.
- ip2region.xdb for offline IP attribution