diff --git a/public/docs-static/img/how-to-guides/profiles/manage-profiles.png b/public/docs-static/img/how-to-guides/profiles/manage-profiles.png new file mode 100644 index 00000000..6fe48320 Binary files /dev/null and b/public/docs-static/img/how-to-guides/profiles/manage-profiles.png differ diff --git a/public/docs-static/img/how-to-guides/profiles/profiles.gif b/public/docs-static/img/how-to-guides/profiles/profiles.gif new file mode 100644 index 00000000..315395c0 Binary files /dev/null and b/public/docs-static/img/how-to-guides/profiles/profiles.gif differ diff --git a/public/docs-static/img/how-to-guides/profiles/profiles.png b/public/docs-static/img/how-to-guides/profiles/profiles.png new file mode 100644 index 00000000..e4b0b1a8 Binary files /dev/null and b/public/docs-static/img/how-to-guides/profiles/profiles.png differ diff --git a/src/pages/how-to/profiles.mdx b/src/pages/how-to/profiles.mdx new file mode 100644 index 00000000..69f8c90a --- /dev/null +++ b/src/pages/how-to/profiles.mdx @@ -0,0 +1,206 @@ +# Switching Between NetBird Accounts with Profiles + +NetBird supports multiple profiles on a single device, making it easy to switch between work, home, or other networks. +Only one profile is active at a time, and switching takes just a click. + +This feature also allows you to switch between self-hosted and cloud-hosted NetBird accounts seamlessly without needing +to juggle multiple config files. + +

+ profiles +

+ +Watch a short demo GIF demonstrating how profile switching works [here](/docs-static/img/how-to-guides/profiles/profiles.gif). + +## NetBird Profiles GUI Quickstart + +To get started with NetBird profiles: + +- Upgrade your client application to the latest NetBird version. +- Run the GUI app + +You will see a `default` profile created automatically. + +Add more profiles by hovering over the default profile and clicking "Manage Profiles". +After adding a new profile, select it to make it active. + +You can now change the NetBird settings, e.g., providing a self-hosted +instance URL or allowing SSH. The new settings will be saved in the new profile. Click "Connect" to bring up the new profile. + +The consequent selection of your profiles from the menu will automatically trigger the NetBird client to connect to the network and authentication +if needed. + +## Manage Profiles in the GUI + +* **Add** a new profile with a friendly name input. +* **Delete** any inactive profile (trash icon). +* **Active and default** profiles cannot be removed. + +

+ profiles +

+ +## What Is a Profile? + +A **profile** is your NetBird configuration bundle: WireGuard keys, login state, and network settings all in one file. +Think of it as a separate "NetBird account" on your machine: + +- **Default profile** + Created automatically on first run or after upgrade. +- **Custom profiles** + Any number of additional profiles you add yourself (e.g. `work`, `home`, `test`). + +Profiles live in your system or user config folders: + +| OS | System-wide path | User path | +| ------ | --------------------------------- | ----------------------------------------------------- | +| Linux | `/var/lib/netbird/profiles/...` | `~/.config/netbird/.json` | +| macOS | `/Library/Application Support/...`| `~/Library/Application Support/NetBird/.json`| +| Windows| `%ProgramData%\Netbird\profiles\` | `%APPDATA%\Netbird\.json` | + +--- + +## Why Use Profiles? + +- **Seamless switching** between multiple NetBird networks/accounts +- **No manual config files updates**: all configs are managed through the CLI or GUI +- **Persistent state**: your last active profile reconnects on startup +- **Safe defaults**: you cannot remove the active/default profile by accident + +--- + +## Upgrading From an Older Version + +If you're upgrading from NetBird below version `0.52.0` that did not support profiles, here's what happens: + +* During the first launch after the upgrade, your existing config `/etc/netbird/config.json` (or Windows equivalent) is automatically +copied to a new profile named `default`. +* The `default` profile is set as active, and you can start using it immediately. + +--- + +## Profile CLI Commands + +With the CLI, you can manage profiles easily. The main command is: + +```bash +netbird profile [name] +```` + +### Add a New Profile + +To create a new profile, use the command: + +```bash +netbird profile add +``` + +For example, the command below creates a new profile named `work`: + +```bash +netbird profile add work +``` + +This command does the following in the background: + +* Creates a `work.json` file in your config folder. +* Keeps the client disconnected until you run `netbird up` or `netbird login`. +* Will throw an error if the profile with the same name already exists. + +### List Profiles + +The command below lists all available profiles along with their status: + +```bash +netbird profile list +``` + +For example, running this command might output: + +```text +Found 3 profiles: +✓ work +✗ default +✗ home +``` + +* **✓** = active +* **✗** = inactive + +### Select (Switch) a Profile + +To switch to a specific profile, use: + +```bash +netbird profile select +``` + +For example, to switch to the `home` profile: + +```bash +netbird profile select home +``` + +The successful command will output: + +```text +Profile switched successfully to: home +``` + +If `home` hasn't been used before, you will need to run `netbird up` or `netbird login` to authenticate. +If the profile does not exist, you'll see an error message: + +```text +Error: profile home does not exist +``` + +### Remove a Profile + +To remove a profile, use: + +```bash +netbird profile remove +``` + +For example, to remove the `home` profile: + +```bash +netbird profile remove home +``` + +If successful, you'll see: + +```text +Profile removed successfully: home +``` + +You can't remove an active profile. If the profile your are trying to remove is active, you'll see an error: + +```text +Cannot remove active profile: home +``` + +If the profile does not exist, you'll see an error message: + +```text +Error: profile home does not exist +``` + +The command does the following in the background: + +* Removes `home.json` and `home.state.json` files from your config folder. + +--- + +### Using `--profile` Flags + +You can use the `--profile` flag with any NetBird CLI command to specify which profile to use for that command. +This is useful for running commands in a specific context without switching profiles manually. + +```bash +netbird up --profile work +netbird login --profile home +``` + +NetBird switches to the named profile then runs the command under the hood. If the profile is new and hasn't been used yet, +you'll be prompted to authenticate.