🩸 BlueVein

Forget about re-pairing Bluetooth devices

Dual-boot without the headache

🚀 Quick Start - ⚡ How It Works - 🔬 Technical Details - 💬 Support

---

🎯 The Problem We Solved

Sound familiar?

🎧 You're in Windows Connected Bluetooth headphones → Works perfectly!

🔄 Reboot to Linux Headphones don't work → Need to pair again

🔁 Back to Windows Headphones don't work again → Pair again

Caution

This hell repeats EVERY time you switch between OSes.
With headphones. With mouse. With keyboard. With gamepad. With all devices.

Note

Interesting fact. You typically spend 1 to 3 minutes reconfiguring bluetooth devices when switching between OSes.
3 minutes × 3 switches per day × 250 working days = 37.5 hours per year.

BlueVein is the solution:

Pair your device once in any OS.
Switch between Windows and Linux.
BlueVein keeps the pairing keys synchronized automatically. Reconnection still depends on the Bluetooth stack in each OS; a valid bond alone cannot repair a host-side connection bug.

When either OS knows a Bluetooth device name, BlueVein also carries it in the shared record. Windows reads the BTHPORT name cache and falls back to the PnP friendly name it displays, which is often the only source for an old LE bond. Linux reads the BlueZ Name and falls back to a user Alias. Linux applies the shared name as the BlueZ Name while importing or updating the matching bond; an existing Linux Alias is preserved. A name found later is added to the existing shared record, even when its keys cannot be imported. Logs identify devices by address and name; names are optional, and older shared files and devices without a known name remain valid.

When a running BlueVein instance has already observed and synchronized a local bond, then sees that bond removed, it writes a pending-deletion marker to EFI. On the next boot of the other OS, BlueVein unpairs that device only if its bonding key fingerprints match the removed bond, then removes the shared EFI record. A newly paired device at the same address is kept and replaces the old marker. A device missing on the first snapshot after boot does not imply deletion: older bonds from the other OS can still be imported. Failed or ambiguous unpair operations leave the marker in EFI for diagnosis; they are reported after the run instead of stopping the synchronization of every other device, and the next cycle retries them. When Windows reports that it has no paired device object for the address, BlueVein removes only the leftover BTHPORT key material that would otherwise resurrect the bond. Install a version with this behavior on both operating systems before using deletion as a cross-OS cleanup mechanism.

🌟 Why BlueVein?

Feature	What it gives you
🔄 Bidirectional sync	Changes in any OS are instantly synchronized
🚀 Zero configuration	Install → Run → Forget about the problem
💾 EFI access	Uses the mounted EFI filesystem on Linux when available; otherwise fat32-raw
🛡️ Security	Works at system level with administrator privileges
📡 Real-time monitoring	Tracks changes instantly
🔍 Periodic checking	Checks for updates from the other OS every 30 seconds

🚀 Quick Start

Linux

Option 1: Arch Linux (AUR)

# Install via AUR
yay -S bluevein-bin

# Start the service
sudo systemctl enable --now bluevein

# Check status
sudo systemctl status bluevein

Option 2: NixOS module

By Flake:

{
  inputs.bluevein.url = "github:meowrch/BlueVein";

  outputs = { self, nixpkgs, bluevein, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        bluevein.nixosModules.default
        {
          services.bluevein.enable = true;

          # Optional: pin the EFI device with a stable path
          services.bluevein.efiDevice = "/dev/disk/by-uuid/A1B2-C3D4";
        }
      ];
    };
  };
}

Non-flake usage:

{
  imports = [ /path/to/BlueVein/nix/module.nix ];

  services.bluevein.enable = true;
  # services.bluevein.efiDevice = "/dev/disk/by-uuid/A1B2-C3D4";
}

Option 3: Manual build (any distribution)

# 1. Clone and build
git clone https://github.com/meowrch/BlueVein.git
cd BlueVein
cargo build --release

# 2. Install
sudo cp target/release/bluevein /usr/bin/
sudo cp ./systemd/bluevein.service /etc/systemd/system/

# 3. Run
sudo systemctl daemon-reload
sudo systemctl enable --now bluevein

# 4. Verify
sudo systemctl status bluevein

Tip

Specifying EFI Device: By default, BlueVein automatically detects the EFI partition. If you have multiple EFI partitions or a non-standard configuration, use the BLUEVEIN_EFI_DEVICE environment variable:

# For systemd service (edit /etc/systemd/system/bluevein.service)
Environment="BLUEVEIN_EFI_DEVICE=/dev/disk/by-uuid/XXXX-XXXX"

# Or for manual launch
sudo BLUEVEIN_EFI_DEVICE=/dev/disk/by-uuid/XXXX-XXXX bluevein

⚠️ Use stable device identifiers! Paths like /dev/nvme0n1p1 or /dev/sda1 can change between reboots (especially in multiboot setups). Always use stable identifiers from /dev/disk/by-*.

How to find your EFI partition's stable path:

# Find EFI partition UUID
lsblk -f | grep vfat

# Then use one of these stable paths:
ls -l /dev/disk/by-uuid/      # Filesystem UUID (recommended)
ls -l /dev/disk/by-partuuid/  # Partition UUID
ls -l /dev/disk/by-id/        # Device ID

Stable device examples:

• /dev/disk/by-uuid/A1B2-C3D4 — Filesystem UUID (recommended)
• /dev/disk/by-partuuid/12345678-1234-... — Partition UUID
• /dev/disk/by-id/nvme-Samsung_SSD_...-part1 — Device ID

Windows

Option 1: Pre-built release

1. Go to Releases
2. Download bluevein.exe from the latest release
3. Open PowerShell as Administrator
4. Execute:

# Install and start
.\bluevein.exe install
.\bluevein.exe start

# Verify
Get-Service BlueVeinService

Option 2: Manual build

# 1. Build
cargo build --release
cd target\release

# 2. Open PowerShell as Administrator

# 3. Install and start
.\bluevein.exe install
.\bluevein.exe start

# 4. Verify
Get-Service BlueVeinService

Tip

Specifying EFI Device (Windows): By default, BlueVein automatically detects the EFI partition. To specify a particular device, use the BLUEVEIN_EFI_DEVICE environment variable:

# For manual launch
$env:BLUEVEIN_EFI_DEVICE="\\?\Volume{GUID}\"
.\bluevein.exe

# To set machine-wide environment variable for the service
[System.Environment]::SetEnvironmentVariable('BLUEVEIN_EFI_DEVICE', '\\?\Volume{GUID}\', 'Machine')
.\bluevein.exe install
.\bluevein.exe start

Windows device format:

• \\?\Volume{GUID}\ — Volume GUID path

How to find your EFI device:

# List all partitions and find EFI
Get-Partition | Where-Object {$_.GptType -eq '{c12a7328-f81f-11d2-ba4b-00a0c93ec93b}'} | Get-Volume | Select-Object DriveLetter, FileSystemLabel, FileSystemType, DriveType, HealthStatus, OperationalStatus, SizeRemaining, Size, UniqueId
# or simply: mountvol

⌨️ Service Management

Linux

# Start/stop/restart
sudo systemctl start bluevein
sudo systemctl stop bluevein
sudo systemctl restart bluevein

# Status and logs
sudo systemctl status bluevein
sudo journalctl -u bluevein -f

# Autostart
sudo systemctl enable bluevein   # enable
sudo systemctl disable bluevein  # disable

Windows

# Service management
.\bluevein.exe start      # Start
.\bluevein.exe stop       # Stop
.\bluevein.exe install    # Install
.\bluevein.exe uninstall  # Uninstall

# Or via net
net start BlueVeinService
net stop BlueVeinService

# Check status
Get-Service BlueVeinService

🔥 How It Works?

System Architecture

graph TB
    subgraph Windows
        WinBT[Registry Bluetooth]
        WinMonitor[BlueVein Monitor]
    end
    
    subgraph Linux
        LinuxBT[BlueZ Bluetooth]
        LinuxMonitor[BlueVein Monitor]
    end
    
    subgraph EFI["EFI Partition"]
        Config[bluevein.json]
    end
    
    WinBT <-->|Track changes| WinMonitor
    LinuxBT <-->|Track changes| LinuxMonitor
    
    WinMonitor <-->|Read/Write keys| Config
    LinuxMonitor <-->|Read/Write keys| Config
    
    style Config fill:#89b4fa,stroke:#313244,stroke-width:2px,color:#1e1e2e
    style WinMonitor fill:#f38ba8,stroke:#313244,stroke-width:2px,color:#1e1e2e
    style LinuxMonitor fill:#a6e3a1,stroke:#313244,stroke-width:2px,color:#1e1e2e

Loading

Synchronization Algorithm

sequenceDiagram
participant OS as Operating System
participant Monitor as BlueVein Monitor
participant EFI as EFI/bluevein.json

Note over OS,EFI: 1️⃣ System boot
Monitor->>EFI: Reads keys from EFI
Monitor->>OS: Reads local devices
Monitor->>OS: Updates device keys from EFI if they differ
Monitor->>EFI: Adds new devices from OS to EFI

Note over OS,EFI: 2️⃣ New device pairing
OS->>Monitor: Event: new device
Monitor->>EFI: Reads current bluevein.json
Monitor->>EFI: Adds/updates device key

Note over OS,EFI: 3️⃣ Periodic check (every 30 sec)
Monitor->>EFI: Checks for changes from other OS
Monitor->>OS: Applies new keys to existing devices

Loading

Key Operating Principles

• On boot: BlueVein checks keys in EFI and updates them for devices present in the system. New devices from the system are added to EFI
• On new pairing: The key is immediately saved to EFI and becomes available to the other OS
• On removal: A bond that disappears after BlueVein observed it locally gets a pending-deletion marker in EFI. The other OS removes its matching bond, then clears the EFI record. A missing bond at startup is not treated as a deletion; mismatched keys are never removed automatically. See the deletion protocol.
• Periodically: Checks for changes every 30 seconds and applies key updates from EFI

🔬 Technical Details

Bluetooth LE Support

BlueVein fully supports Bluetooth Low Energy devices with all key types:

Key Type	Purpose	Support
LTK	Long Term Key — main encryption key	✅ Full
Peripheral LTK	LTK for device in peripheral role	✅ Full
IRK	Identity Resolving Key — for privacy (random MAC)	✅ Full
CSRK	Connection Signature Resolving Key — for data signing	✅ Full
AddressType	Address type (public/random)	✅ Full

EFI Access Architecture

BlueVein uses EfiContext to manage EFI partition access:

• Automatic detection: By default, BlueVein automatically finds the EFI partition at standard mount points (/boot/efi, /efi, /boot on Linux)
• Manual specification: Use the BLUEVEIN_EFI_DEVICE environment variable to explicitly specify a device
• Linux access: Even with BLUEVEIN_EFI_DEVICE set, BlueVein reads and atomically writes through the mounted EFI filesystem when that device is mounted. It synchronizes the filesystem after a write so a subsequent raw read sees the same FAT chain. Raw access is used only when the selected EFI device is unmounted.
• Windows access: Uses direct access via fat32-raw.

Do not write to a mounted FAT filesystem through its block device. The kernel can retain cached FAT metadata and later overwrite or misinterpret the raw changes.

Benefits of this approach:

• Flexibility in complex configurations (multiple EFI partitions, RAID, LVM)
• Backward compatibility (works without specifying device)
• Cross-platform (Linux and Windows use a unified interface)

Architecture Decisions

Dual-mode devices: BlueVein automatically merges Classic and LE keys for devices supporting both modes (e.g., many Bluetooth headphones).

CSRK SignCounter:

• Windows doesn't persist SignCounter in registry — it's kept in driver memory only
• BlueVein stores Counter in bluevein.json and takes MAX value during sync
• This prevents counter rollback and protects against replay attacks

Known Limitations

CSRK SignCounter on Windows: Windows Bluetooth stack doesn't persist SignCounter in registry. BlueVein works around this by storing it in bluevein.json, but frequent OS switching may reduce accuracy.

Impact: Minimal. Modern LE devices (keyboards, mice, headphones, gamepads) use LTK for encrypted connections, not CSRK for data signing. Issue may only affect specific IoT devices using unencrypted connections with signing.

Solution: If device doesn't auto-connect after sync — re-pair once. Counter will reset and everything will work.

📚 FAQ

Will this break my Bluetooth?

No. BlueVein only reads and writes pairing keys. It doesn't touch drivers or system files.

What devices are supported?

Any Bluetooth devices: headphones (AirPods, Sony, Bose), mice (Logitech MX Master), keyboards, gamepads (Xbox, PS5).

Tested on:

• AirPods Pro 2
• Sony WH-1000XM5
• Logitech MX Master 3
• Xbox Series X Controller

Is my data safe?

Yes. Pairing keys are stored in the EFI partition, which only root/admin can access. BlueVein runs with elevated privileges, but the code is open — you can verify it yourself.

What about BitLocker or LUKS encryption?

BlueVein works independently of disk encryption. The EFI partition is typically not encrypted and accessible before OS boot.

Does it work with triple-boot?

Yes. BlueVein synchronizes keys between all OSes on one machine, regardless of how many there are.

What if I already have bt-dualboot installed?

BlueVein is fully automatic and works in real-time as a background service.

bt-dualboot, besides requiring manual commands after each pairing, has several other drawbacks identified by the community:

• Crashes on real devices. Doesn't support LE keyboards. Crashes on some configurations.
• Doesn't work with multiple Bluetooth adapters. If you have built-in + external adapter — you'll get an error.
• Requires mounting the Windows partition.
• Uses hacky methods to modify Windows system registry
• Abandoned since 2022 — issues remain unanswered

---

⚒️ Troubleshooting

Problem	Solution
❌ Service won't start (Linux)	Run sudo systemctl status bluevein and check logs: sudo journalctl -u bluevein -n 50
❌ Service won't start (Windows)	Make sure PowerShell is running as Administrator
❌ Device still won't sync	Check that EFI partition is mounted: lsblk -f | grep vfat (Linux) or verify the service is running
❌ Keys match, but Linux does not reconnect	Check the LE/Classic connection and HID profile separately. BlueVein synchronizes bonds; it does not scan for or connect devices. BlueZ 5.87 has a dual-mode private-address reconnect issue that needs a separate host workaround.
❌ Permission denied	BlueVein requires root/admin. On Linux use sudo systemctl or run the service as root

Tip

Still not working?
Open an issue with logs and OS information.

💬 Support

🐛 Found a bug?

1. Collect logs:

   # Linux
   sudo journalctl -u bluevein -n 100 > bluevein_logs.txt
   
   # Windows
   C:/ProgramData/BlueVein/bluevein.log

2. Create an Issue with detailed description and logs

💡 Have an idea?

Open a Feature Request — we always welcome improvements!

🤝 Contributing

Want to improve BlueVein? We'd love your contribution!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

☕ Support the Project

Like BlueVein? Help the project grow! 🚀

💎 Cryptocurrency	📬 Address
TON	UQB9qNTcAazAbFoeobeDPMML9MG73DUCAFTpVanQnLk3BHg3
Ethereum	0x56e8bf8Ec07b6F2d6aEdA7Bd8814DB5A72164b13
Bitcoin	bc1qt5urnw7esunf0v7e9az0jhatxrdd0smem98gdn
Tron	TBTZ5RRMfGQQ8Vpf8i5N8DZhNxSum2rzAs

Every donation motivates us to continue developing the project! ❤️

📊 Project Statistics

---

Made with ❤️ for the Linux community