Your guide to the new team VPN

Self-hosted NetBird gives us control over our VPN server, user accounts, and access policies, without a per-member VPN subscription for the Community Edition. We take responsibility for server operation, updates, and backups.

NetBird uses its own application. The dashboard is NetBird's standard interface running on our server; it is not the NetBird Cloud service.

Readiness: the pilot demonstrated SSH connectivity and policy blocking, and the external HTTPS address has been live since October 10, 2026. John's Windows PC and the lab servers now connect through it without Tailscale. What remains is each member's own independent test from an outside network; some campus and office networks have been observed to reset the connection to our server (see section 09). This guide prepares your migration; it is not an announcement that the whole team has switched.

• Keep your existing Tailscale connection available during the transition.
• Tell John which devices you need to connect and which servers or services you need to access.
• Have an authenticator app ready for multi-factor authentication (MFA).
• Do not install a new VPN on a company-managed device without the required authorization.

Send this access request to John

Use your existing trusted communication channel. Ask only for the resources needed for your work.

Name:
Email for the invitation:
Device name:
Operating system and version:
Device ownership: personal / organization-managed
Resources needed: GPU server / robot system / test workstation / other
Tasks needed: SSH / file transfer / web application / other
Existing remote OS username, if known:
Access duration: ongoing / until a specific date
Expected connection locations: home / lab / other
Availability for the migration test:

Do not include a password, SSH private key, MFA code, or enrollment token. A public SSH key may be requested separately.

Before you install

• Confirm that you have permission to install networking software. If local administrator approval is needed, arrange it first.
• Save the current SSH hostnames and connection settings you use, so they can be checked during migration.
• Use a recognizable device name, such as alice-laptop or alice-phone. Report replacements or duplicate registrations to John.
• On a phone or tablet only one VPN app can be active at a time. You will need to disconnect Tailscale on that phone while NetBird connects; you can switch back at any time during the transition.
• For a remote-only server, John must establish a recovery path before changing its VPN connection. Do not disconnect its only working management connection.

1. Receive a personal invitation link. John creates it on our own NetBird server and sends it to you privately. It expires, normally within 3 days; ask for a new one if it has lapsed. Invitations are intended for a specific person and must not be forwarded.
2. Create your own password and enroll in MFA. Open the link, set a unique password, and sign in. You will then be asked to scan an MFA QR code with your own authenticator app (Google Authenticator, Microsoft Authenticator, Authy, or similar). Nobody needs your password, one-time codes, or MFA QR code.
3. Install the official NetBird application and point it at our server. Our address is https://your-server.example. Use it instead of the default NetBird Cloud service; section 04 shows where to enter it on each device.
4. Sign in and send John your device name and NetBird IP. Registration alone grants no access: the app will say Connected but nothing is reachable until John adds that device to an access group.
5. Test your approved connections. Confirm that the servers and services you need work through NetBird. Connection names or VPN IP addresses may change; use the updated instructions provided for your devices.
6. Switch only after verification. We will test access with Tailscale disconnected. Remove Tailscale only when John confirms that your device has completed the migration.

The initial plan uses individual accounts on our server. Google or GitHub login has not been configured; do not assume an existing social account will sign you in.

What you should receive before starting

• Your personal invitation link and its expiration time.
• The server address, which is the same for everyone: https://your-server.example.
• Your approved resource list, including destination hostname or IP, service port, and OS username where applicable.
• A migration test window and an agreed fallback procedure.

Only that address is valid. Do not use a demonstration URL, localhost, or an address copied from someone else's screenshots. If an invitation or message shows a different host, stop and confirm with John.

Account and MFA checklist

1. Open the invitation supplied by John and check that its host matches the announced server address.
2. Choose a unique password and save it in your password manager.
3. When prompted, scan the MFA QR code using your own authenticator app and enter the current code to finish enrollment.
4. If recovery options are offered, store them privately. Never send the QR code or recovery information to another member.
5. If the invitation has expired, request a replacement. Do not use another member's account.

Ask John for help if your account opens but no resources are available. That can be the expected state before access is assigned; repeatedly reinstalling the app will not grant permissions.

Begin this section after your invitation link has worked once in a browser. Every device uses the same server address: https://your-server.example. If NetBird is already installed for another network, tell John before changing it.

netbird status

netbird up --management-url 'https://your-server.example'

netbird status

Keep the transition reversible

John may temporarily run both VPNs during testing. If routes or DNS conflict, report it; do not add manual routes or change DNS servers to force a connection. Keep Tailscale available until your independent NetBird test passes.

• Access is restricted by default. Only approved devices, destinations, and service ports will be allowed.
• Permissions follow your work. GPU servers, robot systems, and test equipment may have different access groups. Access to one does not imply access to the others.
• Administrator access is separate. Ordinary member accounts do not grant control over users, VPN policies, or the management server.
• SSH remains a separate permission. A working VPN connection does not create a Linux account or grant SSH or sudo access. Use your assigned account and personally authorized SSH key.
• Periodic sign-in may be required. Login-based devices are configured for reauthentication after eight hours and after a management disconnection lasting ten minutes. Headless server enrollment works differently.

The free self-hosted pilot uses administrator-controlled group assignment to restrict device access. This is distinct from NetBird's licensed built-in “Peer Approval” feature.

Right after enrollment, expect “Connected” with nothing reachable. New devices start in no access group. Send John the device name and NetBird IP; access appears shortly after John assigns the group, without reinstalling or signing in again.

Check the IP range. On our server every device gets an address starting with the range John gave you. Any other range (for example 100.117.) means the app is signed in to a different NetBird network, usually the default NetBird Cloud or a Google/GitHub account. Repeat section 04 with our server address and the invited lab account.

Three separate checks must pass

1. Identity: your account can authenticate and your device is registered.
2. Network policy: that device is allowed to reach the requested destination and port.
3. Application permission: the server accepts your SSH account/key or application login.

The pilot currently allows only a specific SSH test path among the enrolled devices. It does not authorize unrestricted lab traffic. Final member permissions will be assigned before each migration, and ping may remain blocked.

A VPN account also does not approve operating a robot or changing shared equipment. Follow the equipment's normal access and coordination procedures.

Before attempting SSH, obtain three values from John: destination, port, and remote OS username. Your NetBird email and your Linux username may be different.

The pilot uses an SSH bridge on port 2222. That is a temporary implementation detail, not a port to assume for every machine. Production instructions may use standard port 22 or another explicitly assigned port.

Windows PowerShell: connect using assigned values

Run the following only after John supplies the connection details. It prompts for values rather than embedding a fake server address:

$SshHost = Read-Host 'Assigned server hostname or NetBird IP'
$SshUser = Read-Host 'Your assigned remote OS username'
$SshPort = Read-Host 'Assigned SSH port'
ssh -p $SshPort "$SshUser@$SshHost"

This uses your existing SSH configuration and available keys. If a particular key is required, John will provide the correct key-selection instructions for your device. In PowerShell, your home path uses $env:USERPROFILE; the CMD expression %USERPROFILE% is not expanded in the same way.

macOS or Linux: command format

The following is a format illustration, not a ready-to-run command. Replace each uppercase label with your assigned value:

ssh -p ASSIGNED_PORT YOUR_OS_USERNAME@ASSIGNED_HOST

SSH key handling

• Use your own existing authorized key, or generate a separate key when requested. Do not overwrite an existing key file.
• Only the public key, normally ending in .pub, is provided for server registration. The private key stays on your device.
• On first connection, verify the server's host-key fingerprint through John before accepting it. Stop if an existing host key unexpectedly changes.
• For VS Code Remote SSH, use the confirmed host, user, port, and identity file. Keep the old working host entry until the new connection is verified.
• SCP and SFTP need the same authorized destination and credentials. Test with a small, non-sensitive file before relying on large transfers.

Never fix an SSH error by sharing a private key, disabling host-key checking, or enabling root login. A public-key authentication error usually means the network reached an SSH service but the username/key combination was not accepted.

Complete this with John for each device. One successful device does not validate every laptop or server.

• The client is connected to the announced self-hosted management URL.
• Your account and MFA work, and John has identified the correct registered device.
• Your approved server connection succeeds with the assigned address, port, and account.
• Your required workflow works: terminal, file transfer, editor, or approved web application.
• John verifies that an explicitly chosen unauthorized destination or port is blocked. Do not scan the lab network.
• From a different network, such as a mobile hotspot, the approved workflow works with Tailscale disconnected.
• After reconnecting or rebooting at an agreed time, access recovers or prompts for reauthentication as expected.
• You know how to report a failure and how to use the agreed fallback during the migration window.
• John explicitly confirms that this device is ready to retire its Tailscale connection.

Do not stop the sole VPN connection on a remote-only host while connected through it. Independent testing must have a local operator, console, or other confirmed recovery path.

Send a completion report

Device:
Date/time and time zone:
Test network: lab / home / mobile hotspot / other
NetBird connected: yes / no
Approved resources tested:
SSH / file transfer / application results:
Tailscale disconnected during independent test: yes / no
Reconnect or reboot result:
Remaining problems:
John's cutover confirmation: pending / received

• Use your own account. Do not share logins or SSH private keys.
• Keep your operating system and VPN application updated, and lock your device when unattended.
• Do not share invitation links, device enrollment keys, passwords, or MFA secrets in team chats.
• Do not open router ports, publish internal services, or disable security controls to troubleshoot access.
• If you see a certificate warning, stop and contact John. Do not bypass it.
• Report a lost device, suspicious login, or exposed credential promptly so access can be revoked.

If a device or credential is lost

Contact John immediately through your established channel. Identify the affected device or account and the approximate time of the incident. Do not send the exposed secret itself. John will review VPN access, device registration, and any separate SSH credentials; replacing one does not automatically revoke the others.

When you replace a computer or leave the team

Ask for the old device to be removed and request enrollment for the replacement. Do not copy another device's VPN identity or your colleague's credentials. Let John know when access is no longer needed so VPN and server permissions can be removed.

Send John your device name, operating system, the service you are trying to reach, and the error message. Remove passwords, tokens, invitation links, and other secrets before sharing screenshots or logs.

During the transition, keep Tailscale as the fallback until told otherwise. Ping may be intentionally blocked, so a failed ping alone does not mean the VPN is broken.

Our server and network can still experience outages. Self-hosting and MFA reduce certain risks; they do not guarantee uninterrupted service or make a system impossible to compromise.

Support request template

Device and operating system:
NetBird client version:
Time of failure and time zone:
Network location/type:
NetBird connection status:
Tailscale state: connected / disconnected
Approved resource and service:
What I expected:
What happened / exact error:
What changed recently:
Checks already tried:

Start with netbird status or the app's status screen. Share only the relevant portion privately with John; diagnostic output can reveal device names, internal addresses, and network details. Send full diagnostic bundles only when requested.

Use these for software instructions. John's messages remain the source for your assigned resources and migration timing.

• Windows installation · macOS installation · Linux installation · Android · iOS
• Desktop connection and profiles · CLI reference
• Self-hosted user invitations · Local MFA