How to Run Tailscale on ZimaOS for Remote Access

If the Tailscale app installs on ZimaOS but clicking its WebUI simply returns you to the ZimaOS dashboard, that does not necessarily mean the Tailscale container is broken. The November 2024 community thread began with exactly that symptom on ZimaOS 1.2.5. The useful correction was that Tailscale is primarily configured through authentication, environment variables, and the Tailscale CLI—not through a conventional application WebUI.

The original reply recommended using the App Store package and supplying a Tailscale authentication key through TS_AUTHKEY. A later 2025 ZimaOS thread confirmed another working path: install Tailscale, run tailscale status in the CLI, open the login URL it returns, and authenticate the node. Current Tailscale Docker documentation supports both auth-key-based and login-based workflows, while also recommending persistent state so the container keeps the same node identity across restarts.

Why the Tailscale “WebUI” Link Can Be Misleading

The original user expected the app to open a management page after installation. Instead, the browser returned to the ZimaOS homepage.

The Original Community Fix: Use TS_AUTHKEY

The first reply said the App Store package could work by creating a Tailscale authentication key and pasting it into:

TS_AUTHKEY

Current Tailscale documentation still defines TS_AUTHKEY as the environment variable used to authenticate a Docker container to a tailnet.

Current reference: Tailscale Docker configuration parameters.

Generate the key in the Tailscale admin console, then treat it as a secret. Do not publish it in screenshots, forum posts, Git repositories, or shared Compose files.

Alternative: Authenticate Through the Tailscale CLI

A later ZimaOS community solution used:

tailscale status

When the node had not yet authenticated, Tailscale returned a login URL. The user opened that URL in a browser and approved the device.

Depending on the installed container and shell context, you may need to run the command inside the Tailscale container rather than directly on the ZimaOS host.

First identify the container:

docker ps --format '{{.Names}}' | grep -i tailscale

Then, if necessary:

docker exec -it TAILSCALE_CONTAINER tailscale status

Use the actual container name shown by your system.

Persist Tailscale State Across Restarts

Current Tailscale Docker documentation recommends setting:

TS_STATE_DIR=/var/lib/tailscale

and mounting that directory to persistent host storage. Without persistent state, a restarted or recreated container can register as a new node instead of retaining its previous identity.

Tailscale also provides:

TS_AUTH_ONCE=true

for deployments that should authenticate only when the container has no existing state.

What a Current Container Configuration Needs

A minimal conceptual Docker setup includes:

environment:
  - TS_AUTHKEY=YOUR_SECRET_KEY
  - TS_STATE_DIR=/var/lib/tailscale
  - TS_AUTH_ONCE=true

volumes:
  - /YOUR/ZIMAOS/PERSISTENT/PATH:/var/lib/tailscale

The exact host path and additional network/device settings depend on the ZimaOS App Store definition. Do not replace a working current app definition with an old CasaOS YAML solely because the 2024 thread linked to a CasaOS tutorial.

Accessing ZimaOS Is Different from Advertising the Whole LAN

There are two common goals:

• Reach the Tailscale node itself: connect to the ZimaOS/Tailscale node using its Tailscale address or MagicDNS name.
• Reach other devices on the ZimaOS LAN: configure the node as a Tailscale subnet router.

The second goal is more complex. Current Tailscale documentation requires the router to advertise routes and have them approved in the admin console.

See Tailscale subnet router documentation.

Subnet Routing in a Dockerized ZimaOS Tailscale App Has Extra Requirements

A 2026 ZimaOS community report showed a Tailscale Docker container that connected successfully but failed to advertise LAN routes. That setup used host networking, privileged mode, and /dev/net/tun, yet subnet routes still did not appear.

This is an important boundary: a container that successfully joins your tailnet is not automatically a functioning subnet router. Routing requires kernel/network privileges, forwarding, route advertisement, and admin approval.

If your only goal is to reach ZimaOS itself remotely, do not enable subnet routing unnecessarily.

Tailscale Does Not Require SMB Guest Access

The 2024 community reply claimed that SMB folder sharing needed guest permissions to work through the Tailscale tunnel. That should not be generalized as a current Tailscale requirement.

Tailscale provides network connectivity. SMB authentication remains an independent Samba/Windows/macOS permission layer. A properly configured named SMB account can work over a Tailscale path just as it can over a LAN.

Guest access may have been a workaround for the specific CasaOS/ZimaOS Samba configuration in that older discussion, but it is not inherent to Tailscale.

Security Notes

• Use a scoped/reusable or ephemeral auth key according to your deployment needs.
• Keep auth keys out of screenshots and repositories.
• Persist state so the node does not repeatedly re-register.
• Use Tailscale ACLs or grants to control which tailnet devices can reach the ZimaOS node.
• Do not expose the ZimaOS dashboard directly to the public internet just because remote access is required.

ZimaOS Tailscale Setup Checklist

1. Install the current Tailscale App Store package.
2. Do not rely on the app's WebUI link as the primary configuration method.
3. Authenticate with TS_AUTHKEY or the Tailscale CLI login URL.
4. Persist /var/lib/tailscale using TS_STATE_DIR.
5. Verify the node appears in the Tailscale admin console.
6. Run tailscale status and confirm the node is connected.
7. Test access to the ZimaOS node before attempting subnet routing.
8. If you need the whole LAN, configure and approve subnet routes separately.

ZimaOS and Tailscale FAQ

Why does the Tailscale WebUI link return to ZimaOS?

Tailscale's container is normally configured through environment variables, authentication, and CLI commands rather than a conventional app WebUI. The source thread showed this exact confusion.

What is TS_AUTHKEY?

It is the Tailscale Docker environment variable used to authenticate the container to your tailnet.

Why should I persist TS_STATE_DIR?

Persistent state allows the container to retain its node identity and authentication across restarts or recreations.

Do I need subnet routing to access ZimaOS remotely?

No. Subnet routing is only needed when the Tailscale node should route traffic to other non-Tailscale devices on the local network.

Does SMB need Guest mode over Tailscale?

No as a general Tailscale rule. SMB account authentication is separate from Tailscale networking.