deck-tailscale: putting Tailscale on a Steam Deck that never shows a desktop

The problem: a VPN client on a machine that boots to a game

The Steam Deck runs Linux, but not the kind of Linux a server administrator is used to. It boots into a game-oriented interface, and the desktop environment is somewhere else in the stack, which makes installing a service that has to start on boot awkward. Tailscale publishes a guide for the Steam Deck, and this repository is the script form of that guide, derived from it and tweaked to make the process smoother and to produce an installation that comes up automatically on boot, with no need to enter desktop mode.

That last clause is the point of the whole repository. A Tailscale installation that only runs while a desktop session is alive is not much use on a handheld that mostly runs games, so the script writes a systemd override that re-points the service at the binaries it installed, and enables the service so it comes up on its own.

The audience is narrow and specific: someone with a Steam Deck who wants it on their tailnet, probably for remote access to a home server or a self hosted service, and who is comfortable with a shell script and a root shell. It is a script, not a package, and the repository is correspondingly small: override.conf, readme.md, tailscale.sh and uninstall.sh.

The licence is recorded as unknown for the repository, which is worth noting for anyone planning to redistribute or fork it, and the last push was on 2026-10-08. There are no GitHub releases, so the script in the repository is the artefact, and the project expects you to update it by pulling rather than by downloading a release.

The install sequence, and the root shell it asks for

The installation is five steps, and the second one is the one people trip over.

First, clone the repository to the Deck, switch to root and enter the directory. The documented commands are a clone into a directory called deck-tailscale, then sudo -i to become root, then a change into the directory. The documentation writes that last path as ~deck/deck-tailscale, and the tilde is doing unusual work there, so it is worth checking the path you are actually in before running the next command.

Second, run the install script:

bash tailscale.sh

Third, put the binaries on your path with:

source /etc/profile.d/tailscale.sh

Fourth, bring the Deck onto the network. The command is:

tailscale up --qr --operator=deck --ssh

The QR flag makes Tailscale print a login code that you scan with your phone to authenticate, the operator flag marks the node as a Deck for policy purposes, and the ssh flag enables Tailscale's own SSH server. Finally, run exit to return to your normal user shell once you are done.

Two details in that sequence matter. The script is run as root, and the operator flag is set at install time, which is why the later update commands do not need sudo.

The profile script exists because the binaries are not in a default path. They go to /opt/tailscale, and the profile fragment in /etc/profile.d is what makes the command name resolve, which is also why a fresh shell picks them up automatically and the current one needs sourcing.

What the script writes, and what it leaves alone

The How it works section of the documentation lists the files, and reading them tells you the whole shape of the installation.

The Tailscale binaries tailscale and tailscaled are installed in /opt/tailscale/. The Tailscale systemd unit file is installed at /etc/systemd/system/tailscale.service. The override file that reconfigures the service Exec commands is installed at /etc/systemd/system/tailscaled.service.d/override.conf, and the defaults file for the variables PORT and FLAGS is installed at /etc/default/tailscaled. The service is then started and enabled via systemctl.

The two paths under /etc/systemd/system are the interesting ones, because they behave differently on a re-run. The documentation on updating the install script says the process overwrites the existing binaries and service file, and that the configuration file at /etc/default/tailscaled is left alone. The override file, by contrast, is reset every time the script is run to ensure the path to the binary is correct, and the preexisting file is backed up in that directory as override.conf.bak.

So the rule for an operator is clear and worth stating plainly. Your configuration survives a reinstall, your override does not, and the override is the file that makes the service point at the right binary, which is why it cannot be left stale.

If something goes wrong, the documentation says to copy those files somewhere else and re-run the install script to get back to a working state. The backup is the safety net, and it lives next to the file it replaces.

Self-update, and the sudo path problem it exposes

Once the script has run, Tailscale should be able to update itself, and the documentation says so in as many words.

If you are still in the root shell from the installation steps, the update is two commands:

tailscale update
tailscale set --auto-update

The second one is the interesting one. Enabling auto-update is what makes the first command meaningful later, because a self-updating client only helps if it is allowed to replace itself.

If you are running as the standard deck user instead, there is a wrinkle that the documentation explains with unusual precision. sudo will not find tailscale directly, because /opt/tailscale is not in the default secure_path of sudo. The fix is to use the full binary path:

sudo /opt/tailscale/tailscale update
tailscale set --auto-update

And there is a note attached to that: --operator=deck was configured during installation, so tailscale set can be run without sudo. The two halves fit together. The operator setting grants the permission to change the node's own configuration, and the update binary needs root because it replaces files in a root-owned directory.

The secure_path detail is the kind of thing that takes an hour to diagnose from scratch, and it is here because somebody hit it and wrote it down. If you are scripting the update path, use the full binary path.

Two failure modes: the SSH chroot trap and a broken config file

The common issues section covers two distinct problems, and both are worth knowing before you need them.

The first is the one the documentation warns about most strongly. This process will most likely fail if you are accessing the terminal over Tailscale SSH, as it seems to be locked in a chroot jail. You should start and connect through the standard SSH server instead, and remember to stop it when you are done. The repository links an issue asking for suggestions on how to fix it.

The reasoning is not hard to reconstruct. The install script needs a root shell and it needs to write to paths outside the home directory, and a Tailscale SSH session is a restricted environment. The irony is sharp: the tool you are installing is the one that breaks the installation, and the workaround is to install it over the other SSH server, which you then have to remember to turn off.

The second failure mode is a broken configuration file, with the symptom spelled out exactly:

invalid value "" for flag -port: can't be the empty string

The resolution is short: delete /etc/default/tailscaled and re-run the installer script. An empty PORT value in the defaults file is what produces that error, and because the installer overwrites the override and the binaries but not that file, deleting it and re-running puts the system back into a state the script knows how to produce.

Between them, these two cover the realistic ways this install goes wrong: the wrong transport, and a defaults file that has been edited into something the service cannot parse.

Updating the script and uninstalling, both of which overwrite

Keeping the install script current is a two step operation, and the documentation recommends doing it from time to time so that you benefit from the improvements.

From the standard deck user, you change into the cloned directory and pull the changes, then run the install script again as root:

sudo bash tailscale.sh

The consequence is stated and matters: this process overwrites the existing binaries and service file, so it is not recommended to tweak those files directly. The configuration file at /etc/default/tailscaled is left alone, while the override file is reset every time, with the previous one backed up as override.conf.bak in the same directory. If something goes wrong, the documentation says to copy those files somewhere else and re-run the install script to get back to a working state.

So the operating rule for this script is that it owns the binaries, the service unit and the override, and you own the defaults file. Editing the owned files is possible and will be lost, and editing the defaults file is the supported way to change PORT and FLAGS.

Removal is the mirror image of installation:

sudo bash uninstall.sh

run from the deck-tailscale directory. The presence of a dedicated uninstall script in a four file repository is a good sign, and it removes the question of what state the system is left in.

Licence, maintenance and where this is the wrong tool

The licence field for the repository is recorded as unknown, and the repository contains no licence file to check. The script installs Tailscale itself, and Tailscale is a separate project with its own terms, but the script that automates the installation and the systemd override it ships are the artefacts in this repository, and their licensing position is not stated. That is a gap to close with the Tailscale team before you redistribute anything derived from it.

The project is not archived, the last push was on 2026-10-08, and there are no GitHub releases, which means there is no tagged version to pin and no changelog to read. The update path is a git pull, so the version you run is the version at the tip of main.

As for when this is the wrong tool, the answer is straightforward. It is specific to the Steam Deck, so a Raspberry Pi, a NUC or a laptop gets a normal Tailscale install. It assumes a systemd host with a root shell and a git client, so a container or a locked down appliance is out of scope. And it is an install convenience, not a configuration system: there is no support for ACLs, exit nodes, DNS settings or a subnet router, because all of that lives in the Tailscale administration interface and in the tailscale client itself.

What it does give you is a working Tailscale on a Deck that comes up on boot, with the systemd override already in place, and a script that knows which files are its own. For that specific job, it is a good answer, and the documentation's honesty about overwriting, backups and the SSH trap is a good part of it.

Editorial conclusion

Adopt deck-tailscale if you want Tailscale running on a Steam Deck that boots straight into a game without a desktop session, and you are willing to read a shell script before running it as root. Do not adopt it as a general install method, since it is specific to the Steam Deck layout, and do not run it over a Tailscale SSH session, which the documentation says will probably fail. Before you run it, read tailscale.sh and uninstall.sh, and note that the licence is not recorded for the repository, so check the licensing position with the Tailscale team before redistributing it.

Frequently asked questions

Official sources

1. Issues
2. README
3. tailscale-dev/deck-tailscale on GitHub