app-tailscale: a Home Assistant app that puts Tailscale in a container

What the app is for, and what Tailscale does for you

Tailscale is a zero config VPN, which installs on any device in minutes, including your Home Assistant instance, and the README's job is to say what that buys you.

The described capability is creating a secure network between your servers, computers and cloud instances. Even when separated by firewalls or subnets, Tailscale just works. It manages firewall rules for you, and it works from anywhere you are.

That last pair of properties is what makes it interesting for a home lab, and the reason the addon exists at all. The usual way to reach a Home Assistant instance from outside the home is a VPN server on the router, a reverse proxy with a certificate, or a port forward with the security risk that implies. Tailscale replaces all of that with a device that joins a WireGuard mesh, so the traffic arrives over an encrypted peer to peer tunnel without anything listening on your public interface.

The repository is the Home Assistant Community App packaging of it, maintained in the hassio-addons organisation, which is a collection of add-ons and apps maintained by Franck Nijhof. The README says the original setup of this repository is by Franck Nijhof, with the MIT licence and a copyright line covering 2021 to 2026, so this is a project that has been running for several years rather than a new wrapper.

The primary language is recorded as Shell, which tells you the addon is a container image with an entrypoint script rather than a compiled program, and the top level listing is minimal: a .github directory, a .mdlrc and a .yamllint for linting, the LICENSE, the README, and a tailscale/ directory holding the addon itself.

What a Home Assistant app actually is, and why the packaging is the product

A Home Assistant app, formerly called an add-on, is a packaged piece of software that the supervisor installs and manages. The format has a fixed shape: a directory holding a configuration file where the user sets options, a Dockerfile or image reference, a startup script, translations, and a metadata file that declares what the app needs.

That shape explains what this repository actually is. The top level listing is a .github directory, a .mdlrc and a .yamllint for linting, the LICENSE, the README, and a tailscale/ directory. Everything real lives in that one directory, and everything in it exists to satisfy the addon contract rather than to implement a VPN.

So the addon takes the Tailscale client, wraps it, and supplies the things the supervisor expects: a way for the user to set options, a way for the container to be started and stopped, a way for the state to be persisted, and translations of the configuration labels into the languages Home Assistant speaks. The result is that a user installs Tailscale from the Home Assistant add-on store the same way they would install a file editor, without touching a terminal on the host.

The interesting part of the design is what the packaging has to decide on your behalf. Running a VPN client inside a container raises questions the upstream project answers for a bare machine: whether the container needs privileges to create the tunnel interface, whether it should see the host's network namespace so that the instance can be reached from the mesh, and how the subnet routes the container advertises interact with the routes your other machines already have through Tailscale. None of that is visible in the README, which is exactly why the documentation lives in DOCS.md next to the configuration file.

That is the shape of the whole project: a thin, carefully configured wrapper whose value is in getting the host, container and mesh interactions right, with the upstream client doing the actual cryptography.

The badges tell you the project stage and who maintains it

The README carries a row of badges, and reading them tells you a lot more than the marketing copy does.

There is a project stage badge, and it says experimental. That is a specific and useful piece of information: the app is published and usable, but the maintainer is signalling that the interface and behaviour may still change. For a Home Assistant app that is a reasonable position to be in, because the addon configuration format is what users edit, and changes to it are disruptive when you have set the thing up.

The maintenance badge is a URL with a year in it, pointing at 2026, which is a convention used by this collection to show that the project is still being looked after rather than merely still downloadable.

The other badges cover the release history, the GitHub Actions CI status, the commit activity, the licence and the funding links. The funding badges point at GitHub Sponsors and Patreon for Franck Nijhof, which is how this collection of add-ons is supported.

Taken together, the badge row gives you a fair summary before you read a word of the prose: actively maintained by one person with funding behind it, built in CI, and at an experimental stage.

The release history supports that. The recent versions are v0.30.2 on 2026-10-08, v0.30.1 on 2026-09-24 and v0.30.0 on 2026-09-11, so this is at version 0.30 with a release every couple of weeks. The last push was on 2026-10-08, the same day as the newest tag, so the repository is being worked on rather than merely maintained.

Where the actual documentation lives

The README is short, and that is a deliberate choice rather than an unfinished one, because the details are in a separate document.

The README points to the full app documentation with a books link, and the target of that link is a file inside the addon directory, tailscale/DOCS.md in the repository. Putting the documentation inside the addon folder rather than in a separate docs site is a specific choice, and it has an effect: the documentation is versioned with the addon, so the page you read matches the configuration file sitting next to it on your instance.

For an addon like this, that matters more than it might seem. The configuration for a Tailscale app is not just a version number and an auth key. It involves deciding whether the container runs in a privileged or unprivileged mode, what subnet routes the container should advertise, whether the host's own network should be exposed to the mesh, and what the advertised exit node and DNS behaviour are. Each of those has consequences for the rest of your network, and getting one wrong is the kind of thing you would want to read about carefully rather than infer from a README summary.

The support section is more thorough than most, and it names four channels in order of specificity. There is a Home Assistant Community Apps Discord for app support and feature requests, which is the right place for a question about this specific app. There is the main Home Assistant Discord for general questions. There is the Home Assistant Community Forum, and the Reddit subreddit.

And then the last line, which is the one that separates an addon from a product: you could also open an issue here on GitHub. The word could also is doing the work. Issues are for reproducible bugs in the app, and the author would rather you asked the question in chat first, which is the only way to know that something is a support question rather than a defect.

The collection around it, and the licence

This repository is one entry in a wider set, and the README points at the rest of it.

The line reads: we have got some Home Assistant apps for you, and asks whether you want more functionality on your Home Assistant instance, with a pointer to the collection's GitHub repository for the full list.

That context explains a few things about this repository. The addon is thin because the collection is built from many thin addons, each wrapping one upstream project in the Home Assistant addon format, and each one follows the same conventions: a tailscale/ directory with the addon metadata and configuration, a Dockerfile, an entrypoint script, a set of translations, and a documentation file. The .yamllint and .mdlrc files at the root are the linting configuration for that shared structure, and the CI badge in the README row is the workflow that runs those checks across the collection.

The licence is MIT, with the full text in the repository, and the copyright line runs from 2021 to 2026 and names Franck Nijhof. The README closes with the standard MIT warranty disclaimer.

What is worth saying plainly is what this repository is not. It is not a fork of Tailscale, it does not modify the Tailscale client, and it does not reimplement WireGuard. It is packaging that takes an upstream binary and makes it installable and configurable as a Home Assistant app, with the addon format handling lifecycle, configuration, backups and updates. The value it adds is the packaging and the documentation, and the fact that it is maintained by the same person who maintains the other apps in the collection is what makes it likely to still be there when the next upstream release lands.

Editorial conclusion

Adopt app-tailscale if you want your Home Assistant instance reachable over Tailscale from outside your home network without opening a port on your router. Do not adopt it as a general VPN client for the whole household, because it is scoped to the Home Assistant container. Before you install it, read the app documentation linked from the README, because the configuration is in the addon's own config file, and note the badge says the project stage is experimental, so expect the interface to change between releases.

Frequently asked questions

Official sources

1. hassio-addons/app-tailscale on GitHub
2. Issues
3. License: MIT
4. README
5. Releases