The September 2023 IceWhale Community post titled “How to install Tailscale on CasaOS” is extremely short. It points users toward an external tutorial and says Tailscale can provide secure remote access, but the forum body does not preserve the actual installation steps, image version, state mapping, or authentication configuration.
That means a long-lived page should not pretend the old forum post contains a complete modern recipe. The useful way to preserve it is to explain the original CasaOS use case and rebuild the implementation around Tailscale's current Docker model.
This Is a CasaOS Historical Post, Not a ZimaOS Tutorial
CasaOS and ZimaOS share some ecosystem history, but they are not interchangeable operating systems. The source belongs to the CasaOS category and dates from 2023, before today's ZimaOS custom-app, YAML, and Developer Mode workflows.
If the target system is ZimaOS, use a ZimaOS-specific Tailscale page. If the target is CasaOS running on a Linux host, the Docker concepts below remain relevant.
What Tailscale Solves for a CasaOS Server
Tailscale creates an encrypted private network between enrolled devices. A laptop or phone on the same tailnet can reach the CasaOS server through its Tailscale IP or MagicDNS name without opening the CasaOS dashboard directly to the public internet.
That is different from conventional port forwarding: the server initiates its encrypted overlay connection and users connect through the tailnet.
Use the Maintained Tailscale Container
Current Tailscale publishes the tailscale/tailscale container image and documents the supported environment variables for authentication, hostname, state, routes, userspace networking, and health checks.
Start from the current official Tailscale Docker deployment pattern rather than an unversioned third-party Compose snippet from 2023.
Persist the Tailscale State Directory
The most important modern requirement missing from the short source post is persistent state. A Docker container can be recreated during updates or configuration changes. If the Tailscale machine state only exists inside that disposable container, each recreation can register a new node.
Map a CasaOS host directory or Docker volume to the directory configured through TS_STATE_DIR. This preserves the machine's identity, keys, and login state across restarts.
Choose an Authentication Method Deliberately
A container can join the tailnet with an auth key or through an interactive login flow, depending on the deployment. Auth keys are credentials and should never be copied from screenshots or public Compose files.
For a permanent server, avoid ephemeral enrollment unless you intentionally want the machine to disappear after it goes offline.
Avoid Re-Authenticating a Persisted Node on Every Start
Current Tailscale supports TS_AUTH_ONCE=true. When state is already present, the container can reuse it instead of forcing a new enrollment each time it starts.
This is especially useful for a home server that should remain the same node for months or years.
Networking Depends on What You Want to Reach
There are several valid Tailscale container designs:
- a node that only gives the Tailscale container itself an identity;
- a host-integrated node that provides access to services running on the CasaOS host;
- a subnet router that advertises access to other LAN devices;
- a sidecar or proxy arrangement for selected containers.
These modes have different capability and routing requirements. Do not add privileged mode or broad network capabilities automatically. Follow the current Tailscale use case you actually need.
Do Not Expose the CasaOS Dashboard Publicly Just Because Remote Access Is Needed
The value of Tailscale is that remote devices can behave as though they are on a private network with the server. For personal administration, it is usually safer to keep the CasaOS dashboard private to the LAN and tailnet rather than publish it on a public IP.
Pin or Review Versions Before Updating
A 2023 tutorial may have referenced a specific image tag or app-store package. Current deployments should review release changes and update deliberately. Persisted state makes replacing the container much safer because the machine identity is not tied to the old image layer.
Tailscale on CasaOS FAQ
Does the original IceWhale post contain a complete installation procedure?
No. The forum body mainly introduces the external tutorial.
Which container image should a current deployment use?
Tailscale maintains the official tailscale/tailscale image.
How do I stop duplicate nodes after container recreation?
Persist the directory configured by TS_STATE_DIR and avoid unnecessary fresh authentication.
Is this article proof that ZimaOS uses the same setup?
No. The source is specifically a historical CasaOS post.
