https://github.com/osesem/twinbird

Run multiple NetBird instances on a single machine with isolated configs, sockets, and interfaces
https://github.com/osesem/twinbird

cli multi-instance netbird python vpn wireguard

Last synced: 1 day ago
JSON representation

Run multiple NetBird instances on a single machine with isolated configs, sockets, and interfaces

• Host: GitHub
• URL: https://github.com/osesem/twinbird
• Owner: OseSem
• License: mit
• Created: 2026-03-31T17:54:11.000Z (9 days ago)
• Default Branch: main
• Last Pushed: 2026-04-06T12:36:31.000Z (3 days ago)
• Last Synced: 2026-04-06T14:43:40.319Z (3 days ago)
• Topics: cli, multi-instance, netbird, python, vpn, wireguard
• Language: Python
• Homepage: https://pypi.org/project/twinbird/
• Size: 47.9 KB
• Stars: 3
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

README

          
# twinbird

[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

![PyPI - Version](https://img.shields.io/pypi/v/twinbird)

![PyPI - Downloads](https://img.shields.io/pypi/dm/twinbird)

Manage multiple [NetBird](https://netbird.io) instances on a single machine with isolated configs, daemon sockets, and WireGuard interfaces.

## Install

```bash

uv tool install twinbird

```

or

```bash

pip install twinbird

```

## Usage

```bash

# Start a named instance

twinbird up office --management-url https://mgmt.example.com --setup-key YOUR_KEY

# Check status

twinbird status office

# List all instances

twinbird list

# Stop an instance

twinbird down office

```

### Environment Variables

Instead of passing flags every time:

```bash

export TWINBIRD_MANAGEMENT_URL=https://mgmt.example.com

export TWINBIRD_SETUP_KEY=YOUR_KEY

twinbird up office

```

| Variable | Purpose |

|---|---|

| `TWINBIRD_MANAGEMENT_URL` | Default management URL |

| `TWINBIRD_SETUP_KEY` | Default setup key |

| `TWINBIRD_NETBIRD_BIN` | Path to netbird binary (default: `netbird` on PATH) |

| `TWINBIRD_CONFIG_DIR` | Override root config directory |

## How It Works

Each named instance gets:

- Its own config directory (`~/.config/twinbird//` on Linux, `%APPDATA%/twinbird//` on Windows)

- A unique daemon socket address (Unix socket on Linux/macOS, TCP port on Windows)

- A unique WireGuard interface name (`wt` on Linux, `utun` on macOS)

Twinbird starts a separate `netbird service run` daemon per instance, then connects with `netbird up` — all fully isolated from the primary NetBird installation.

## Requirements

- [NetBird](https://netbird.io) installed and on PATH

- Python 3.10+

## License

MIT