DEV Community: nestt

v2hub: an ecosystem for developers

nestt — Thu, 10 Sep 2026 10:56:07 +0000

In previous posts I talked about v2hub — an ecosystem for managing VPN subscriptions — and about how I ended up building it. Back then the service was simple: a user has a token, and they use that token to manage their own subscriptions. Through v2hub-cli, through v2hub-panel, through the bot — didn't matter which, the point was the same: a user only ever had the subscriptions they created themselves.

That worked well, and it still does. But then people started showing up who wanted to build their own service on top of v2hub, or integrate it into a product they already had. It quickly became clear that the current feature set wasn't enough for that.

Because now there isn't just one owner — there are two: the end user, who wants a working VPN, and the developer, who wants to offer that VPN as part of their own service. And you can't just hand the user's token to the developer — that's the user's personal key, not something you trade around.

Sure, you could pass your own personal token so a third-party service creates subscriptions on your behalf. But that's awkward for everyone involved: for the user (the service could just delete a subscription they still need), and for the developer (they'd have to store a separate token per user).

So v2hub got providers.

What exactly is a provider

A provider is a separate account type that can, with the user's consent, manage that user's subscriptions. A provider doesn't have subscriptions of its own — if it needs any, it just uses a regular user API-Token for that. Technically, a provider token is the same API-Token a regular user has, just flagged differently on the server side. So a provider keeps using the same v2hub library, the same methods, just with one extra parameter: who it's currently acting on behalf of.

If a call used to look like this:

async with AsyncVPNClient(base_url, api_token) as client:
    sub = await client.create_subscription("my-vpn")

Now a provider can do the same thing, but for a specific user:

async with AsyncVPNClient(base_url, provider_api_token) as client:
    sub = await client.create_subscription(
        "welcome-vpn",
        as_provider_for_user_id=98765,
    )

One provider, one token — and it can manage subscriptions for any number of users who've agreed to it.

Consent isn't a formality — it's its own flow

I deliberately didn't make it so a provider could just grab a user_id and start managing that user's subscription right away. That would've been a hole the size of the API itself. Instead, there's a full authorization lifecycle:

The provider requests access to a user.
If the user already exists in the system, a pending request immediately shows up for them — visible through v2hub-cli, the panel, or the bot. The provider, in turn, gets a connection link it can hand to the user directly.
What if the user doesn't exist yet? Just creating a new user from whatever user_id was passed in would be a bad idea — that ID might not correspond to anyone real. So in that case the server returns an HMAC-signed invite link in the form conn_{hmac}_{provider_name}, which the bot wraps into a deep link to itself (t.me/v2hubot?start=...). The user follows the link, the server verifies the signature, and only then, on the user's behalf, confirms both account creation and the connection request.
The user approves or rejects the request.
Only after approval can the provider do anything with subscriptions — and only with the ones it created itself. Subscriptions the user created on their own are off-limits to the provider. Every provider gets its own isolated space to manage subscriptions in, and it can't step outside of it.

There's one detail I want to call out specifically, because it was a deliberate design choice: revoking access is not the same as deleting it. If a user changes their mind and revokes a provider, every subscription that provider created stops being visible to the user, but nothing actually gets deleted — those subscriptions keep existing, the provider just can't touch them anymore. Only the provider itself can fully delete a connection. The one exception: if the provider never created any subscriptions for that user in the first place, the connection is deleted automatically, with no extra steps needed.

The point of this split is simple: a user can disconnect a provider and reconnect later, whenever they want. The provider doesn't have to recreate anything — everything becomes available again the moment the user reconnects.

What about limits

A single user can connect a limited number of providers — five by default. Past that, connecting one more means revoking one of the existing ones first. This exists so users don't end up dragging every provider under the sun into their account, and to cut down on request spam.

This limit doesn't affect a provider's ability to send a connection request, though — the request still gets created and sits in pending, the user just physically can't approve it until they free up a slot.

Why this matters for developers

If you're building your own Telegram bot that sells VPN access, or you want to simplify and improve a product you already have — you no longer need to stand up your own backend for aggregating configs, storing subscriptions, and resolving nested references. That logic already exists in v2hub, and you get access to it as a provider:

create a subscription for a user the moment they pay for access;
add or remove sources as needed (say, one of your servers goes down — quietly swap the source, and the user won't even notice);
hand the user a ready-made public subscription link they paste into their VPN client once and never touch again.

Meanwhile, you don't have to store anything on your end besides a mapping of "our internal client ID → their user_id in v2hub." All the heavy lifting — aggregation, caching, resolution, access control — stays on v2hub's side.

Someone will point out: Marzban and 3x-ui already do this, they can build subscriptions too. True — but only out of what was created inside them. If some of your servers run Marzban, some run 3x-ui, and a couple you set up manually with hand-written configs, there's no way to combine them using those tools as-is — you'd have to bolt together some workaround to tie them all together (the same "extended faucet" problem from my previous post). v2hub removes that problem entirely: build a single subscription out of configs from any servers, any protocols, all at once. You can even keep a separate subscription per server and then merge them all into one through v2hub — that's supported too.

Why this matters for end users

You'd think this is purely a developer-facing feature, but here's the thing: users used to have to remember which VPN came from which service, what that service was even called, and where to go find it. Now every service they use is in one place. They can switch providers daily if they want — all they have to do is open v2hub once, and every one of their subscriptions is right there.

It's a win for the services themselves, too: the easier it is for a user to manage everything through one account, the more likely they are to stick around and come back — instead of giving up and going to deal with yet another separate dashboard somewhere else.

Components, if you want to poke at providers yourself:

Core (API): v2hub-api
Library: v2hub on PyPI
Docs: v2hub.dev
Panel: panel.v2hub.link
Bot: t.me/v2hubot

P.S. As always, happy to hear any feedback or suggestions.

[Boost]

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

nestt for v2hub

Jul 28

How I Ended Up Building V2Hub

#opensource #python #fastapi #vpn

3 min read

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

[Boost]

nestt — Mon, 27 Jul 2026 16:52:13 +0000

nestt for v2hub

Jul 27

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

#opensource #python #vpn #fastapi

4 min read

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: nestt

v2hub: an ecosystem for developers

What exactly is a provider

Consent isn't a formality — it's its own flow

What about limits

Why this matters for developers

Why this matters for end users

[Boost]

How I Ended Up Building V2Hub

How I Ended Up Building V2Hub

What good is an API without a nice client?

Auth without the pain

And then it grew a bit too much

[Boost]

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

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

Why this exists

The components

The core — v2hub-api

Panel, CLI, bot

Python libraries on PyPI

Who this might be useful for

Links