Freedom VPN

English · 繁體中文

Project website · 專案網站 · Delivery guide

Your nodes. Your VPN service.

Freedom VPN is an open-source platform for teams building a membership-based VPN on their own infrastructure. It brings subscriptions, devices, usage and Ubuntu exit nodes across locations into one place, using self-hosted NetBird and its official apps for VPN connections.

• Members review subscriptions, manage devices and track usage in the portal, then connect through the official NetBird app.
• Administrators manage membership and decide which exits are available to each member group.
• Operators enroll and maintain nodes through shared deployment, update and recovery workflows.

NetBird provides the overlay network and connection coordination. Freedom VPN adds the membership, accounting, policy and node management around it.

What it does

Area	Capabilities
Membership and devices	Connect subscriptions to service access, manage device allowances, suspend members and revoke devices
Exits across locations	Enroll Ubuntu nodes, assign member groups, check readiness and choose when to publish or disable exits
Usage and fair use	View usage across a member's devices and exits, with configurable fair-use speed adjustments
Exit isolation	Apply Internet-only forwarding rules at the node to separate member traffic from the host, private networks and other members
DNS and domain policies	Manage domain block and allow lists and malicious-domain protection through the service's DNS resolvers
Updates and recovery	Assign target releases, track signed updates and health checks, and recover from update failures with rollback and restore guides

Connect with the official app

For a configured service, your operator supplies the member portal and NetBird management URLs. The portal manages your account; the app handles the VPN connection.

1. Sign in to the member portal. Confirm active service access, your device allowance and the exits available to you.
2. Set up NetBird. Install the official app version listed in the member guide, set its Management URL to your operator's address, and sign in with the same identity used in the portal.
3. Check device authorization. Return to the portal's device list and wait for the device to show authorized. Authorization is automatic when identity, membership and device allowance checks pass; contact the operator if it stays pending.
4. Choose an exit. Manually select an available exit in NetBird to send traffic through it. Use the portal to review usage and fair-use status.

See the member guide for platform-specific setup and DNS settings, and the version matrix for app versions.

How it fits together

flowchart LR
    Portal[Admin and member portal] --> Central[Freedom VPN API and worker]
    Central --> DB[(PostgreSQL)]
    Central -. API synchronization .-> NetBird[Self-hosted NetBird]
    NetBird -. Connection coordination .-> App[Official NetBird app]
    NetBird -. Connection coordination .-> Exit[Ubuntu exit node]
    Central -. Signed policy and leases .-> Exit
    Exit -. Usage and observations .-> Central
    App == WireGuard tunnel: direct or relay ==> Exit
    Exit == Member traffic ==> Internet[Internet]

The control plane manages identity, configuration and accounting; ordinary member traffic travels through the selected exit. Each exit runs the node agent and updater, with nftables and traffic control for enforcement. The product specification (Traditional Chinese) describes the full architecture.

Start here

Task	Guide
Explore the service and its current scope	Delivery guide · 交付導覽
Run the isolated development stack	Dev-stack bring-up and teardown
Prepare a deployment	Deployment and configuration calibration
Operate members and nodes	Operator guide
Connect a member device	Member guide (Traditional Chinese and English)
Back up and recover	Restore drill
Develop against the API	API contracts

Project status and support

Freedom VPN is under development and validation; it is not a production-ready release. Windows, macOS, Android and iOS apps still need real-device validation. Linux lab results and arm64 cross-compilation do not establish platform or hardware support. Production identity/MFA, payment, domains/TLS, DNS lists and operating parameters also need configuration and verification. The delivery guide records the remaining work.

Server-side isolation covers traffic passing through an exit; it does not provide an OS kill switch or control a member device's local Wi-Fi/LAN. If the VPN route is lost, the device may use its ordinary Internet connection. DNS protection applies domain policies without TLS interception. See the member guide for connection and DNS limitations.

Development lab

Review the lab setup and runtime prerequisites and assigned port slots before starting. From the repository root, the documented bring-up, acceptance and cleanup sequence is:

make -f mk/e2e.mk e2e-up
make -f mk/e2e.mk e2e-test
make -f mk/e2e.mk e2e-down

The Docker lab uses test identities, payment fixtures and policy settings, and includes privileged node containers. Run teardown even when validation fails.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗