How I Ended Up Building V2Hub

nestt — Tue, 28 Jul 2026 06:11:56 +0000

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:

Core API: v2hub-api
Web panel: panel.v2hub.link
Telegram bot: t.me/v2hubot
Libraries on PyPI: v2hub and v2hub-admin
CLI: v2hub-cli

V2Hub — An Ecosystem for Managing VPN Subscriptions (V2Ray/Xray/VLESS/VMess/Trojan/Hysteria2)

nestt — Mon, 27 Jul 2026 16:21:05 +0000

Why this exists

If you've ever handed out VPN configs or small subscription links to friends or clients manually, you know the pain: one provider goes down, another changes its address, a third needs to be temporarily hidden — and the end user is supposed to keep using a single, unchanging subscription URL that always resolves to the current list of servers. V2Hub is an attempt to solve this end-to-end: not just a proxy aggregator, but a full ecosystem — API, web panel, CLI, Telegram bot, and admin tooling.

One clarification up front: this project does not generate VPN configs. If you're looking for how to set up a VPN server from scratch, check out vless.wiki. V2Hub is purely about managing subscriptions and configs you already have — aggregating them, hiding sources, annotating them, resolving nested references, and serving it all as one link.

The components

Repo	Try it live	Role
v2hub-api	v2hub.link	Core — FastAPI service that aggregates and resolves subscriptions
v2hub-core	PyPI	Python library with core methods for managing subscriptions
v2hub-admin	PyPI	Add-on module providing admin functionality (HMAC auth, user CRUD)
v2hub-cli	PyPI	Terminal client built with Typer and Rich
v2hub-panel	panel.v2hub.link	Web panel for managing subscriptions (FastAPI + vanilla JS)
v2hub-bot	Telegram Bot	Telegram bot for self-service subscription access

The core — v2hub-api

This is the most fleshed-out piece, so it's worth going into some detail.

Multi-source aggregation. A subscription can pull configs from three kinds of sources at once: raw URIs (vless://, vmess://, trojan://, ss://, etc.), external subscription URLs from another provider, and internal references to other subscriptions inside the same system.

Recursive resolution. If subscription A references subscription B, which references C, everything gets flattened into a single list by the time it reaches the client. There's circular-reference detection built in, plus a configurable nesting depth limit (max_depth, default 3).

Per-source fine-tuning. Any source inside a subscription can be hidden from the resolved output (is_hidden) without deleting it, and annotated with its own comment.

Two-tier caching. Redis as a fast L1 cache, PostgreSQL as the source of truth. A Celery worker refreshes external sources on a schedule (Celery beat, every 15 minutes), so resolution is almost always served from cache. Next up: replacing the periodic worker with lazy refresh, triggered right at request time instead.

Admin-side security. Admin endpoints aren't protected by a plain token — they require an HMAC-SHA256 signature over the request (timestamp + method + path + body), plus an IP whitelist on top. There's also Redis-backed rate limiting per endpoint, with automatic IP bans once violations pile up.

Core stack: FastAPI 0.136, SQLAlchemy 2.0 (async) + asyncpg, Pydantic 2.13, Celery 5.6, Alembic for migrations, Uvicorn + Nginx.

Panel, CLI, bot

v2hub-panel is a minimal web UI for managing subscriptions and sources straight from the browser.

v2hub-cli is built on Typer and Rich — you can create subscriptions, add sources, and run admin operations right from the terminal with nicely formatted output.

v2hub-bot is a simple bot whose main job is issuing access tokens. It embeds v2hub-panel as a mini-app for extra convenience.

Python libraries on PyPI

v2hub — a library that bundles everything an end user needs to work with subscriptions.

v2hub-admin — an add-on to the core library that handles user CRUD, plus allow-lists and ban-lists.

Who this might be useful for

Anyone running a small VPN service for themselves, friends, or a small company, who wants a ready-made infrastructure with monitoring built in instead of hacking something together.
Anyone curious what a genuinely "production-ready" FastAPI project looks like end to end — migrations, async ORM, HMAC auth, observability, CI/CD — regardless of the domain (VPN is more the excuse here than the point).
Developers who want to see a working example of recursive resolution over nested entities with cycle protection — a pattern that's useful well beyond VPN tooling.
Where this is headed

If the project finds an audience and builds up a small community around it, we'll keep developing it. The long-term goal is for V2Hub to become a real alternative to Marzban API and 3x-ui for subscription management — something usable not just by hobbyists and small projects, but by full-fledged VPN companies too.

DEV Community: v2hub