[GH-ISSUE #4584] Installing Netbird on a Steam Deck #9007

Open
opened 2026-08-05 01:20:28 -04:00 by saavagebueno · 11 comments
Owner

Originally created by @vincentchov on GitHub (Oct 3, 2025).
Original GitHub issue: https://github.com/netbirdio/netbird/issues/4584

Describe the solution you'd like
Hi, can you please explain how I can install Netbird on a Steam Deck? Because the Steam Deck uses an immutable OS, some of the mount points are read-only and get wiped after installing Steam OS updates. I'd like to be able to have it start up when the Steam Deck starts up, without needing to enter desktop mode and manually starting it.

Describe alternatives you've considered
I looked into some tutorials and scripts used for installing Tailscale. The tutorial seemed to suggest one uses systemd-sysext, but their updated installation script seems to have stopped using that method.

Additional context
I opened an issue with the Steam OS repo to confirm with them what's the preferred means of installing the standalone binaries for Netbird along with the systemd services, such that the installation survives updates.

Side note on if going with systemd-sysext:
To use a systemd-sysext image, the image needs a /usr/lib/extension-release.d/extension-release.${PLUGIN_NAME} file that declares what OS that image is compatible with. Tailscale previously used the VERSION_ID variable from the /etc/os-release file to say which version of Steam OS it's compatible with, but I think that won't survive Steam OS updates because VERSION_ID will change whenever Steam OS is updated. There would have to be some way to keep the /usr/lib/extension-release.d/extension-release.netbird file updated so that systemd-sysext doesn't consider the image incompatible.

Originally created by @vincentchov on GitHub (Oct 3, 2025). Original GitHub issue: https://github.com/netbirdio/netbird/issues/4584 **Describe the solution you'd like** Hi, can you please explain how I can install Netbird on a Steam Deck? Because the Steam Deck uses an immutable OS, some of the mount points are read-only and get wiped after installing Steam OS updates. I'd like to be able to have it start up when the Steam Deck starts up, without needing to enter desktop mode and manually starting it. **Describe alternatives you've considered** I looked into some tutorials and scripts used for installing Tailscale. The [tutorial](https://tailscale.com/blog/steam-deck) seemed to suggest one uses `systemd-sysext`, but their updated [installation script](https://github.com/tailscale-dev/deck-tailscale/blob/main/tailscale.sh) seems to have stopped using that method. **Additional context** I opened an [issue](https://github.com/ValveSoftware/SteamOS/issues/2151) with the Steam OS repo to confirm with them what's the preferred means of installing the standalone binaries for Netbird along with the systemd services, such that the installation survives updates. Side note on if going with systemd-sysext: To use a systemd-sysext image, the image needs a `/usr/lib/extension-release.d/extension-release.${PLUGIN_NAME}` file that declares what OS that image is compatible with. Tailscale previously used the `VERSION_ID` variable from the `/etc/os-release` file to say which version of Steam OS it's compatible with, but I think that won't survive Steam OS updates because VERSION_ID will change whenever Steam OS is updated. There would have to be some way to keep the `/usr/lib/extension-release.d/extension-release.netbird` file updated so that systemd-sysext doesn't consider the image incompatible.
saavagebueno added the feature-request label 2026-08-05 01:20:28 -04:00
Author
Owner

@vincentchov commented on GitHub (Oct 6, 2025):

By the way, I looked at their commit history and took some notes. It looks like they stopped using systemd-sysext because of the following:

Commit 34db2ca7f04864da8b2e9ad10438045048750a72 (Sun Oct 9 19:16:40 2022 -0400)

  • added the tailscale.sh file from scratch

Commits 1c0d3f93d2ee64c2773b89f7dd9051a1212d0744 (Sun Oct 9 19:59:39 2022 -0400) and 5f5e195e25fd4a7aa6e34ffd291d88249cdb489d (Sun Oct 9 20:00:18 2022 -0400)

  • mention that "It uses the same system extension method as the official guide, but we put the tailscaled.service file directly in /etc/systemd/system/ because it's actually safe to put things there. Changes in /etc/ are preserved in /var/lib/overlays/etc/upper/ via an overlayfs, meaning that they survive updates."

Commit a31db4859ec81541b8f1240f150d3d409e957430 (Wed Jul 19 19:10:37 2023 -0400)

  • Started writing files to /etc:
    • /etc/systemd/system
    • /etc/default/tailscaled
    • /etc/systemd/system/tailscaled.service.d/override.conf
  • Also added the override.conf file to say that ExtensionDirectories=/var/lib/extensions/tailscale

Commit 582036eeb483bb065f9382e4d4a2e60aee86bdd3

  • Sun Nov 19 22:12:38 2023 -0500
  • stops using SYSEXT_LEVEL when creating tailscale/usr/lib/extension-release.d/extension-release.tailscale

Commit d496b2a7d76f70ab788c786c7a2325115f482671 (Fri Dec 15 15:59:25 2023 -0800)

  • stops creating an extension-release file

Commits dee3fecb400d68cc4e5968d9ea0d9bf8f66923ec (Mon Dec 18 12:20:17 2023 -0800) and 52c0e7670454f59a203811e2b29217b11b141e1a (Mon Dec 18 12:45:47 2023 -0800)

  • stop using home directory

Commit ba0a52692f69185eec22a0dc43d2d0a41b9b9ecd (Tue Dec 19 11:03:39 2023 -0800)

  • Readme changes about the update process
<!-- gh-comment-id:3372020086 --> @vincentchov commented on GitHub (Oct 6, 2025): By the way, I looked at their commit history and took some notes. It looks like they stopped using systemd-sysext because of the following: ## Commit [34db2ca7f04864da8b2e9ad10438045048750a72](https://github.com/tailscale-dev/deck-tailscale/commit/34db2ca7f04864da8b2e9ad10438045048750a72) (Sun Oct 9 19:16:40 2022 -0400) * added the tailscale.sh file from scratch ## Commits [1c0d3f93d2ee64c2773b89f7dd9051a1212d0744](https://github.com/tailscale-dev/deck-tailscale/commit/1c0d3f93d2ee64c2773b89f7dd9051a1212d0744) (Sun Oct 9 19:59:39 2022 -0400) and [5f5e195e25fd4a7aa6e34ffd291d88249cdb489d](https://github.com/tailscale-dev/deck-tailscale/commit/5f5e195e25fd4a7aa6e34ffd291d88249cdb489d) (Sun Oct 9 20:00:18 2022 -0400) * mention that "It uses the same system extension method as the official guide, but we put the `tailscaled.service` file directly in `/etc/systemd/system/` because it's actually safe to put things there. Changes in `/etc/` are preserved in `/var/lib/overlays/etc/upper/` via an overlayfs, meaning that they survive updates." ## Commit [a31db4859ec81541b8f1240f150d3d409e957430](https://github.com/tailscale-dev/deck-tailscale/commit/a31db4859ec81541b8f1240f150d3d409e957430) (Wed Jul 19 19:10:37 2023 -0400) * Started writing files to /etc: * /etc/systemd/system * /etc/default/tailscaled * /etc/systemd/system/tailscaled.service.d/override.conf * Also added the override.conf file to say that ExtensionDirectories=/var/lib/extensions/tailscale ## Commit [582036eeb483bb065f9382e4d4a2e60aee86bdd3](https://github.com/tailscale-dev/deck-tailscale/commit/582036eeb483bb065f9382e4d4a2e60aee86bdd3) * Sun Nov 19 22:12:38 2023 -0500 * stops using SYSEXT_LEVEL when creating tailscale/usr/lib/extension-release.d/extension-release.tailscale ## Commit [d496b2a7d76f70ab788c786c7a2325115f482671](https://github.com/tailscale-dev/deck-tailscale/commit/d496b2a7d76f70ab788c786c7a2325115f482671) (Fri Dec 15 15:59:25 2023 -0800) * stops creating an extension-release file ## Commits [dee3fecb400d68cc4e5968d9ea0d9bf8f66923ec](https://github.com/tailscale-dev/deck-tailscale/commit/dee3fecb400d68cc4e5968d9ea0d9bf8f66923ec) (Mon Dec 18 12:20:17 2023 -0800) and [52c0e7670454f59a203811e2b29217b11b141e1a](https://github.com/tailscale-dev/deck-tailscale/commit/52c0e7670454f59a203811e2b29217b11b141e1a) (Mon Dec 18 12:45:47 2023 -0800) * stop using home directory ## Commit [ba0a52692f69185eec22a0dc43d2d0a41b9b9ecd](https://github.com/tailscale-dev/deck-tailscale/commit/ba0a52692f69185eec22a0dc43d2d0a41b9b9ecd) (Tue Dec 19 11:03:39 2023 -0800) * Readme changes about the update process
Author
Owner

@nazarewk commented on GitHub (Oct 6, 2025):

On a debugging session seems like this works fine (is persisted) after downloading binary to /opt/netbird-test/bin/netbird:

/opt/netbird-test/bin/netbird service install
/opt/netbird-test/bin/netbird service start
/opt/netbird-test/bin/netbird status

the resulting /etc/systemd/system/netbird.service file is already persisted by the default configuration and we're storing everything else in /var/lib/netbird.

<!-- gh-comment-id:3372130662 --> @nazarewk commented on GitHub (Oct 6, 2025): On a debugging session seems like this works fine (is persisted) after downloading binary to `/opt/netbird-test/bin/netbird`: ``` /opt/netbird-test/bin/netbird service install /opt/netbird-test/bin/netbird service start /opt/netbird-test/bin/netbird status ``` the resulting `/etc/systemd/system/netbird.service` file is already persisted by the default configuration and we're storing everything else in `/var/lib/netbird`.
Author
Owner

@nazarewk commented on GitHub (Oct 6, 2025):

This script should work as a temporary measure to install netbird

VERSION="0.59.2"

# cleanup the temporary directory
if test -d /opt/netbird/tmp ; then
	rm -r /opt/netbird/tmp
fi

mkdir -p /opt/netbird/bin /opt/netbird/tmp
cd /opt/netbird/tmp

# download and unpack release
wget "https://github.com/netbirdio/netbird/releases/download/v${VERSION}/netbird_${VERSION}_linux_amd64.tar.gz"
tar zxf "netbird_$VERSION_linux_amd64.tar.gz"

# move the binary to the right place
mv netbird /opt/netbird/bin/netbird
chmod +x /opt/netbird/bin/netbird

# create config files
cat <<EOF > /etc/profile.d/netbird.sh
append_path /opt/netbird/bin
EOF
cat <<EOF > /etc/atomic-update.conf.d/netbird.conf
/etc/profile.d/netbird.sh
EOF

/opt/netbird/bin/netbird service install
/opt/netbird/bin/netbird service start

after a reboot you should have netbird command in your PATH, before reboot you can log in using /opt/netbird/bin/netbird up with appropriate flags (like --setup-key)

<!-- gh-comment-id:3372290412 --> @nazarewk commented on GitHub (Oct 6, 2025): This script should work as a temporary measure to install netbird ```shell VERSION="0.59.2" # cleanup the temporary directory if test -d /opt/netbird/tmp ; then rm -r /opt/netbird/tmp fi mkdir -p /opt/netbird/bin /opt/netbird/tmp cd /opt/netbird/tmp # download and unpack release wget "https://github.com/netbirdio/netbird/releases/download/v${VERSION}/netbird_${VERSION}_linux_amd64.tar.gz" tar zxf "netbird_$VERSION_linux_amd64.tar.gz" # move the binary to the right place mv netbird /opt/netbird/bin/netbird chmod +x /opt/netbird/bin/netbird # create config files cat <<EOF > /etc/profile.d/netbird.sh append_path /opt/netbird/bin EOF cat <<EOF > /etc/atomic-update.conf.d/netbird.conf /etc/profile.d/netbird.sh EOF /opt/netbird/bin/netbird service install /opt/netbird/bin/netbird service start ``` after a reboot you should have `netbird` command in your PATH, before reboot you can log in using `/opt/netbird/bin/netbird up` with appropriate flags (like `--setup-key`)
Author
Owner

@vincentchov commented on GitHub (Oct 23, 2025):

To be clear, how should I try uninstalling Netbird to test out this installation script?

<!-- gh-comment-id:3437366893 --> @vincentchov commented on GitHub (Oct 23, 2025): To be clear, how should I try uninstalling Netbird to test out this installation script?
Author
Owner

@nazarewk commented on GitHub (Oct 24, 2025):

/opt/netbird/bin/netbird service uninstall && rm -r /opt/netbird && rm /etc/profile.d/netbird.sh /etc/atomic-update.conf.d/netbird.conf should be good enough for uninstalling

<!-- gh-comment-id:3442751258 --> @nazarewk commented on GitHub (Oct 24, 2025): `/opt/netbird/bin/netbird service uninstall && rm -r /opt/netbird && rm /etc/profile.d/netbird.sh /etc/atomic-update.conf.d/netbird.conf` should be good enough for uninstalling
Author
Owner

@vincentchov commented on GitHub (Oct 27, 2025):

I got the following error when running as the main user, even though it asked for my sudo password.
Error: uninstall service: remove /etc/systemd/system/netbird.service: permission denied

I still got the error when I ran netbird down && netbird service stop && netbird service uninstall. It did work when I ran sudo su before trying the commands you suggested.

<!-- gh-comment-id:3453216350 --> @vincentchov commented on GitHub (Oct 27, 2025): I got the following error when running as the main user, even though it asked for my sudo password. ```Error: uninstall service: remove /etc/systemd/system/netbird.service: permission denied``` I still got the error when I ran `netbird down && netbird service stop && netbird service uninstall`. It did work when I ran `sudo su` before trying the commands you suggested.
Author
Owner

@rehcnt commented on GitHub (Jan 18, 2026):

Hello! Is it possible to autostart netbird? After reboot I need to up service again.

<!-- gh-comment-id:3765020181 --> @rehcnt commented on GitHub (Jan 18, 2026): Hello! Is it possible to autostart netbird? After reboot I need to up service again.
Author
Owner

@vincentchov commented on GitHub (Jan 18, 2026):

Hi @rehcnt, I'll need to double-check but I think the above steps did work for me, which would allow for autostart. It seems they haven't gotten a chance to update the install script that would do the above steps for you. I haven't had a chance myself to try proposing a change to their install script.

Did you try those steps yet?

Temporary steps to install the service: https://github.com/netbirdio/netbird/issues/4584#issuecomment-3372290412

I had asked about the uninstallation steps because I wanted to make sure that the above temporary script was enough to get it to work, and not due to some additional manual steps that we didn't document.

<!-- gh-comment-id:3765024442 --> @vincentchov commented on GitHub (Jan 18, 2026): Hi @rehcnt, I'll need to double-check but I think the above steps did work for me, which would allow for autostart. It seems they haven't gotten a chance to update the install script that would do the above steps for you. I haven't had a chance myself to try proposing a change to their install script. Did you try those steps yet? Temporary steps to install the service: https://github.com/netbirdio/netbird/issues/4584#issuecomment-3372290412 I had asked about the uninstallation steps because I wanted to make sure that the above temporary script was enough to get it to work, and not due to some additional manual steps that we didn't document.
Author
Owner

@rehcnt commented on GitHub (Jan 18, 2026):

@vincentchov yes, I did make steps above, so installation was successful, script installed with no errors and netbird works.
However, netbird works until reboot, after that I need to "/opt/netbird/bin/netbird service start" to launch. What is not really convenient, so it last challenge in this setup.

<!-- gh-comment-id:3765037778 --> @rehcnt commented on GitHub (Jan 18, 2026): @vincentchov yes, I did make steps above, so installation was successful, script installed with no errors and netbird works. However, netbird works until reboot, after that I need to "/opt/netbird/bin/netbird service start" to launch. What is not really convenient, so it last challenge in this setup.
Author
Owner

@vincentchov commented on GitHub (Jan 18, 2026):

Interesting. I would have expected /opt/netbird/bin/netbird service install to have done it, and be equivalent to enabling a systemd service. I don't think I'll be able to try this out for about a week or so since I'm on vacation and don't have a keyboard with me.

<!-- gh-comment-id:3765044011 --> @vincentchov commented on GitHub (Jan 18, 2026): Interesting. I would have expected `/opt/netbird/bin/netbird service install` to have done it, and be equivalent to enabling a systemd service. I don't think I'll be able to try this out for about a week or so since I'm on vacation and don't have a keyboard with me.
Author
Owner

@rehcnt commented on GitHub (Jan 18, 2026):

Sorry, my bad: I edited systemctl service earlier, that is why it was not started after reboot. :(

<!-- gh-comment-id:3765048637 --> @rehcnt commented on GitHub (Jan 18, 2026): Sorry, my bad: I edited systemctl service earlier, that is why it was not started after reboot. :(
Sign in to join this conversation.
No Label feature-request
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#9007