How I Ended Up Building V2Hub

#opensource #python #vpn #fastapi

Like everyone else, I started out using popular tools like Marzban and 3x-ui. And to be fair, they're genuinely convenient — as long as you want to create a config inside that tool and add it to a subscription. But here's the catch: what if you want to add a config to your subscription that wasn't created in Marzban or 3x-ui in the first place? Even if you spin up two independent servers running separate but identical Marzban instances, you can't just merge them. You end up hacking together some workaround to glue them together.

It's a bit like British bathroom taps: hot on one side, cold on the other, and you have to rig up some extension just to mix them and actually be able to wash your hands.

At some point I gave up on that whole approach and started manually setting up xray and writing configs myself. The problem is, if an IP got blocked and it was easier to just spin up a new VPS, I'd have to manually re-add all the configs into every app all over again. Tolerable when it's just you. Considerably less tolerable once you start sharing configs with friends — especially the older, less tech-savvy ones.

So I wrote a scrappy little script where I'd manually punch in all the configs, and it would spit out a subscription link — one I could just send to end users. And that's when it hit me: how many other people out there are dealing with the exact same headache? Not just managing configs, but managing subscriptions on top of that.

Originally I wanted to build a simple website where users could assemble their own subscription from a bunch of configs. But things got a little out of hand along the way — and what I ended up with instead was a standalone FastAPI service where you can build subscriptions out of individual configs and out of other subscriptions.

What good is an API without a nice client?

But what's an API without a comfortable library to actually use it? And if a user isn't going to self-host the whole API, why would they need admin tooling bundled in? So I split it into two libraries: v2hub and v2hub-admin. Both ship sync and async clients, pick your poison.

And what about people who want to use the service but don't want to touch any code at all? That's where the CLI comes in — built on Typer and Rich, so it actually looks nice while you're at it.

Auth without the pain

How do you keep spam and throwaway accounts under control without forcing users through some invasive sign-up flow — email verification, phone number, ID scan, the works? Enter Telegram. I built a bot that hands users a token they can use to access everything, and lets them reset that token whenever they want without breaking anything — because subscriptions are tied to an internal user_hash, not the token itself.

And then it grew a bit too much

Eventually the service grew to the point where it wasn't just useful for developers anymore — regular people wanted in too. Which surfaced a new problem: regular people don't really care for CLIs, client libraries, or, god forbid, raw curl requests against an API.

So the natural next step was a proper web panel — something people could just click through, no terminal required. That's how v2hub-panel came to be.

That's roughly how the V2Hub story started. Let's see where it goes from here.

If you want to poke around: