I have been building Portlyn for weeks now.
It all started with a problem I had with my homelab setup. It was not a deal but it was annoying every time I worked on my setup.
Some of my services were behind a NAT or CGNAT. I wanted to be able to access them with domains TLS certificates and authentication without having to open up ports on my home network.
Course there are already tools that can do this. I tried a few of them. They did not really work the way I wanted them to.
So after messing around with configs and trying to get tools to work together I thought, "this should be simpler".. That is when I started building Portlyn.
The setup I wanted
I did not want anything complicated. I just wanted:
one public entry point
my private services to stay behind NAT or CGNAT
real domains and certificates
authentication for some of my routes
a tunnel that I could control
logs that would tell me what was going on
tools to keep track of
The important thing for me was not that every single piece was new. It was not.
The important thing was that all these pieces would work together in one setup that made sense to me.
The basic idea
Portlyn has two parts:
Hub: this runs on a VPS or any machine with an IP
Agent: this runs next to my private services behind NAT or CGNAT
The node connects back to the hub through WireGuard. The hub gets HTTP traffic handles TLS, authentication and routing and then sends the request through the tunnel to the right node.
My mental model of this is pretty simple:
Internet
|
v
Portlyn Hub on VPS
|
| WireGuard tunnel
v
Node behind NAT / CGNAT
|
v
Local services
This is not meant to be some kind of magic tunnel service.
You still need a VPS or another public IP for the hub. For me that is okay because I already have a VPS.
What it looks like
Here is what the route flow looks like from the hub UI:
The flow I wanted was simple on purpose:
Create a route
Point it to a service behind the tunnel
Enable authentication if the route needs it
Let the hub handle certificates and forwarding
That is the point of Portlyn. I do not want to have to think about five tools every time I want to expose one small service.
What Portlyn can do now
Portlyn has grown faster than I expected. It is definitely not a small script anymore.
Tunnel
reverse proxy with authentication for each route
WireGuard tunnel between hub and node
hub-and-spoke model
node can run behind NAT or CGNAT
userspace WireGuard path
Certificates
ACME with HTTP-01 and DNS-01
wildcard certificates
DNS-01 support for:
Cloudflare
Hetzner
Route 53
DigitalOcean
Login and access control
TOTP for admin login
passkeys for admin login
OIDC SSO
role claim mapping
GeoIP allow/block lists
CrowdSec LAPI integration
rate limits
Audit. Release safety
hash-chained audit log
HMAC-signed webhooks
webhook targets for Slack, Discord, ntfy or generic JSON
Cosign signed releases
self-update with Sigstore chain verification
Some of this might be more than people expect from a homelab tool.
But I kept thinking: if this thing is going to sit in front of my services then authentication, logs and update safety should not be something I put off until later.
The audit log was not planned to become this important
At first I just wanted routing and tunneling to work.
Once I had a tool that could change routes, authentication settings, certificates and node connections I really wanted a clear record of what was happening.
So Portlyn logs things like:
admin login
route changes
authentication policy changes
certificate changes
connection events
self-update events
Example:
Webhook events can be sent to Slack, Discord, ntfy or a generic JSON endpoint.
This is not meant to be a SIEM or anything like that. I just wanted visibility to avoid the "wait what changed?" moment.
What Portlyn is not
I want to be clear about what Portlyn's not because it is still early.
Portlyn works for my use case but it is not trying to be a mature production platform yet.
It is not scaled right now.
For now it is a hub.
It is not a mesh.
The model is hub-and-spoke only.
It is not a Cloudflare Tunnel replacement in the sense.
You still need a VPS or another public IP for the hub.
It is not a WAF.
There are rate limits GeoIP rules and CrowdSec integration. Request bodies are not inspected.
The userspace WireGuard path reaches about 80% of kernel WireGuard throughput in my tests. That is enough for my setup. It is not magic. If you want to push a 1 Gbps link through it this detail matters.
Why not just use Traefik, Caddy or Authentik?
Honestly for setups you probably should.
If you already have a Traefik plus Authentik setup and you are happy with it I am not trying to convince you to throw it
Portlyn is more for people who want one tool that combines:
proxy
+ tunnel
+ certificates
+ route-level authentication
+ basic access control
+ audit logging
+ signed releases/self-updates
The trade-off is that Portlyn is less flexible than a stack of separate tools.
That is intentional.
I wanted fewer tools to keep track of, not infinite configuration options.
Setup video
I also recorded a full setup video for people who prefer watching instead of reading.
It goes through:
installing the hub
connecting a node behind NAT or CGNAT
creating a route
enabling authentication
issuing a certificate
Repo
Portlyn is MIT licensed.
GitHub:
https://github.com/invaliduser231/Portlyn
It is still early. Feedback would be really helpful.
I am especially interested, in:
whether the hub/node architecture makes sense to people
whether the security assumptions are reasonable
how people feel about the WireGuard tunnel handling
what would make you trust or not trust this in your homelab
I know there is still stuff to polish. This is version 1. I am sure people will find rough edges.
Top comments (0)