bifrost-proxy

module
v0.0.0-...-54f22b9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 24, 2026 License: MIT

README

Bifrost Proxy

Go Version Build Status

Bifrost is a production-grade proxy system designed for high-performance traffic routing, deep inspection, and seamless tunnel integration. It bridges your local environment with remote networks through WireGuard, OpenVPN, and intelligent domain-based routing.

📚 Full documentation: https://bifrost.docs.renner.dev/

✨ Key Features

🛡️ Secure Tunnels & Protocols
  • Multi-Protocol Support: HTTP, HTTPS (CONNECT), and SOCKS5.
  • VPN Integration: Native WireGuard (userspace) and OpenVPN support.
  • TUN Mode: Full-system traffic capture with advanced split-tunneling (App, Domain, and CIDR rules).
🚀 Management & Automation
  • Auto-Updates: Built-in GitHub-based update mechanism with channel support (stable/prerelease).
  • Service Management: Native system service installation for Windows (SCM), macOS (launchd), and Linux (systemd).
  • System Proxy: OS-level proxy configuration on Windows (registry/WinINET), macOS (networksetup), and Linux/GNOME (gsettings). On unsupported desktops it returns ErrNotSupported rather than silently succeeding.
🔍 Reliability & Observability
  • Intelligent Routing: Route traffic through different backends based on sophisticated domain patterns.
  • Health Checks: TCP, HTTP, and Ping-based health monitoring with automatic failover.
  • Rich Analytics: Prometheus metrics, structured JSON logging, and interactive Web UI.

🏗️ Architecture

The Bifrost ecosystem consists of a Server for central routing and a Client for local traffic handling.

graph TD
    subgraph "Local Environment"
        App[Browser / Application] --> Client[Bifrost Client]
    end

    subgraph "Bifrost Client"
        Client --> Debug[Traffic Debugger]
        Debug --> Router[Router / Matcher]
    end

    Router -- "Direct Action" --> Internet[Public Internet]
    Router -- "Server Action" --> Server[Bifrost Server]

    subgraph "Bifrost Server"
        Server --> SRouter[Server Router]
        SRouter --> WG[WireGuard Tunnel]
        SRouter --> OVP[OpenVPN Tunnel]
        SRouter --> Fwd[Forward Proxy]
        SRouter --> SDirect[Direct Connection]
    end

    WG --> TInternet[Target Internet]
    OVP --> TInternet
    Fwd --> TInternet
    SDirect --> TInternet

💻 Dashboard & Interface

Bifrost ships two dashboards, both embedded into their binary at build time by the make build targets — there is no separate web server to run:

Dashboard Source Served by Sections
Server web/server bifrost-server (API listener) Dashboard, Backends, Request Log, Clients, Cache, Mesh, Config, Config Generator, Setup Guide
Client web/client bifrost-client (API listener) Traffic, Routes, Cache, VPN, Mesh, Settings, Logs

Both are React + TypeScript single-page apps built with Vite and styled with Tailwind CSS. They support a dark and a light theme: the theme follows your operating system preference by default and can be switched from the header, with the choice stored in localStorage and applied before the first paint.

Server dashboard, dark theme

Client routing rules, light theme

Beyond the browser dashboards there are dedicated frontends in this repository:

  • desktop/ — Wails-based desktop app (Windows, macOS, Linux) with tray integration.
  • mobile/ — React Native / Expo app (iOS, Android).
  • openwrt/ — packaging for running the client on OpenWrt routers.

[!NOTE] UI appearance may vary based on platform and version.

🏁 Quick Start

Requirements for building from source: Go (see go.mod for the minimum version), Node.js with npm and make — the dashboards are compiled by Vite and then embedded into the binaries via go:embed, so the Make targets below run npm install && npm run build for you before go build. Prebuilt nightly archives are also published on the Releases page.

1. Server Setup
# Build the server (also builds + embeds the server dashboard)
make build-server

# Start from a copy of the example configuration
cp configs/server-config.example.yaml server-config.yaml
./bin/bifrost-server -c server-config.yaml
2. Client Setup
# Build the client (also builds + embeds the client dashboard)
make build-client

# Generate a client configuration
./bin/bifrost-client config init --server your-server:7080

# Validate it, then run
./bin/bifrost-client validate -c client-config.yaml
./bin/bifrost-client -c client-config.yaml

configs/ contains ready-made examples for the server, the client, Docker and OpenWrt. Both dashboards are disabled or bound to localhost by default — see the web_ui and api sections of those examples for the listen addresses.

🧑‍💻 Working on the Dashboards

make web-install       # install npm dependencies for both dashboards
make web-dev           # Vite dev server for the server dashboard
make web-dev-client    # Vite dev server for the client dashboard
make web-build         # production build of both dashboards

The dev servers proxy /api to a locally running Bifrost, so start the matching binary first. go build ./... only succeeds once the dashboards have been built at least once — make build (or make web-build) takes care of that.

🛠️ Installation & Services

Install Bifrost as a system service to ensure it runs in the background.

# Install as service
sudo bifrost-client service install --config /path/to/config.yaml

# Check status
bifrost-client service status

📖 Documentation

The full documentation site is at https://bifrost.docs.renner.dev/. The sources live in docs/:

The rendered version of these docs is at https://bifrost.docs.renner.dev/.

🧰 Tech Stack

Layer Technology
Server & client Go 1.25 (Cobra CLI, userspace WireGuard, OpenVPN, TUN)
Web UIs React 19, TypeScript, Vite, Tailwind CSS (embedded into the binaries)
Desktop app Wails (Go + web frontend)
Mobile app React Native / Expo
Observability Prometheus metrics, structured JSON logs
Build & release Make, GoReleaser, Docker, GitHub Actions
Docs site Astro Starlight (docs/)

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

Directories

Path Synopsis
cmd
client command
Package main provides the Bifrost client entry point.
 Package main provides the Bifrost client entry point.
server command
Package main provides the Bifrost server entry point.
 Package main provides the Bifrost server entry point.
internal
accesscontrol
Package accesscontrol provides IP-based access control for Bifrost.
 Package accesscontrol provides IP-based access control for Bifrost.
accesslog
Package accesslog provides access logging for Bifrost.
 Package accesslog provides access logging for Bifrost.
api/apitoken
Package apitoken handles the `?token=` API credential that browsers are forced to use for transports which cannot carry an Authorization header.
 Package apitoken handles the `?token=` API credential that browsers are forced to use for transports which cannot carry an Authorization header.
api/client
Package client provides the REST API for Bifrost client.
 Package client provides the REST API for Bifrost client.
api/server
Package server provides cache management API handlers.
 Package server provides cache management API handlers.
auth
Package auth provides authentication for Bifrost.
 Package auth provides authentication for Bifrost.
auth/mfa
Package mfa provides multi-factor authentication wrapper for Bifrost.
 Package mfa provides multi-factor authentication wrapper for Bifrost.
auth/negotiate
Package negotiate provides HTTP Negotiate (SPNEGO/Kerberos/NTLM) authentication handling.
 Package negotiate provides HTTP Negotiate (SPNEGO/Kerberos/NTLM) authentication handling.
auth/plugin/apikey
Package apikey provides API key authentication for Bifrost.
 Package apikey provides API key authentication for Bifrost.
auth/plugin/hotp
Package hotp provides HMAC-based One-Time Password (HOTP) authentication for Bifrost.
 Package hotp provides HMAC-based One-Time Password (HOTP) authentication for Bifrost.
auth/plugin/jwt
Package jwt provides JWT token authentication for Bifrost.
 Package jwt provides JWT token authentication for Bifrost.
auth/plugin/kerberos
Package kerberos provides Kerberos/SPNEGO authentication for Bifrost.
 Package kerberos provides Kerberos/SPNEGO authentication for Bifrost.
auth/plugin/ldap
Package ldap provides LDAP/Active Directory authentication.
 Package ldap provides LDAP/Active Directory authentication.
auth/plugin/mtls
Package mtls provides mutual TLS (client certificate) authentication for Bifrost.
 Package mtls provides mutual TLS (client certificate) authentication for Bifrost.
auth/plugin/native
Package native provides username/password authentication with bcrypt hashes.
 Package native provides username/password authentication with bcrypt hashes.
auth/plugin/none
Package none provides the "none" authentication plugin which allows all requests.
 Package none provides the "none" authentication plugin which allows all requests.
auth/plugin/ntlm
Package ntlm provides NTLM/Negotiate authentication for Bifrost.
 Package ntlm provides NTLM/Negotiate authentication for Bifrost.
auth/plugin/oauth
Package oauth provides OAuth/OIDC authentication for Bifrost.
 Package oauth provides OAuth/OIDC authentication for Bifrost.
auth/plugin/system
validateLinux: DEFAULT (fail-closed) implementation.
 validateLinux: DEFAULT (fail-closed) implementation.
auth/plugin/totp
Package totp provides Time-based One-Time Password (TOTP) authentication for Bifrost.
 Package totp provides Time-based One-Time Password (TOTP) authentication for Bifrost.
auth/session
Package session provides session token storage and management for Bifrost.
 Package session provides session token storage and management for Bifrost.
backend
Package backend provides backend connection handling for Bifrost.
 Package backend provides backend connection handling for Bifrost.
cache
Package cache provides HTTP caching functionality for the Bifrost proxy.
 Package cache provides HTTP caching functionality for the Bifrost proxy.
cli/client
Package client provides CLI commands for the Bifrost client.
 Package client provides CLI commands for the Bifrost client.
cli/server
Package server provides CLI commands for the Bifrost server.
 Package server provides CLI commands for the Bifrost server.
client
Package client provides the Bifrost client implementation.
 Package client provides the Bifrost client implementation.
config
Package config provides configuration loading and validation for Bifrost.
 Package config provides configuration loading and validation for Bifrost.
debug
Package debug provides traffic debugging for Bifrost client.
 Package debug provides traffic debugging for Bifrost client.
device
Package device provides a unified interface for TUN and TAP network devices.
 Package device provides a unified interface for TUN and TAP network devices.
frame
Package frame provides Ethernet frame parsing and building for TAP devices.
 Package frame provides Ethernet frame parsing and building for TAP devices.
health
Package health provides health checking functionality.
 Package health provides health checking functionality.
logging
Package logging provides structured logging for Bifrost.
 Package logging provides structured logging for Bifrost.
matcher
Package matcher provides domain pattern matching for routing rules.
 Package matcher provides domain pattern matching for routing rules.
mesh
Package mesh provides Hamachi-like mesh networking functionality.
 Package mesh provides Hamachi-like mesh networking functionality.
metrics
Package metrics provides Prometheus metrics for Bifrost.
 Package metrics provides Prometheus metrics for Bifrost.
p2p
Package p2p provides peer-to-peer connectivity with NAT traversal.
 Package p2p provides peer-to-peer connectivity with NAT traversal.
proxy
Package proxy provides proxy protocol implementations.
 Package proxy provides proxy protocol implementations.
ratelimit
Package ratelimit provides rate limiting and bandwidth throttling.
 Package ratelimit provides rate limiting and bandwidth throttling.
router
Package router provides domain-based routing for Bifrost.
 Package router provides domain-based routing for Bifrost.
server
Package server provides the Bifrost server implementation.
 Package server provides the Bifrost server implementation.
service
Package service provides cross-platform system service management.
 Package service provides cross-platform system service management.
sysproxy
tray
Package tray provides system tray integration for Bifrost client.
 Package tray provides system tray integration for Bifrost client.
updater
Package updater provides self-update functionality for Bifrost binaries.
 Package updater provides self-update functionality for Bifrost binaries.
util
Package util provides common utilities for Bifrost.
 Package util provides common utilities for Bifrost.
version
Package version provides build version information for Bifrost.
 Package version provides build version information for Bifrost.
vpn
Package vpn provides TUN-based VPN functionality with split tunneling support.
 Package vpn provides TUN-based VPN functionality with split tunneling support.
vpnprovider
Package vpnprovider provides interfaces and utilities for VPN provider integrations.
 Package vpnprovider provides interfaces and utilities for VPN provider integrations.
vpnprovider/mullvad
Package mullvad provides a VPN provider implementation for Mullvad VPN.
 Package mullvad provides a VPN provider implementation for Mullvad VPN.
vpnprovider/nordvpn
Package nordvpn implements the NordVPN provider for Bifrost Proxy.
 Package nordvpn implements the NordVPN provider for Bifrost Proxy.
vpnprovider/pia
Package pia provides a client for the Private Internet Access VPN provider API.
 Package pia provides a client for the Private Internet Access VPN provider API.
vpnprovider/protonvpn
Package protonvpn provides a VPN provider implementation for ProtonVPN.
 Package protonvpn provides a VPN provider implementation for ProtonVPN.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.