[v1] Tailscale tsnet integration in core

[ironicbadger]

Summary

I’d like to contribute optional Tailscale integration using the native go tsnet library, so that Silo can join a tailnet without a separate daemon or container. Would you be open to this in core, or would you prefer a Silo-managed plugin?

In time, I'd want to add Tailscale to your official clients too, but this is talking about your preferred architecture for the server side TS implementation. Happy to agree on scope before implementing.

User value / why v1

Built-in Tailscale access would let users securely reach Silo remotely without port forwarding, a public reverse proxy, or a separate Tailscale daemon/container. Using tsnet would give Silo its own tailnet identity and let administrators manage the connection through Silo.
This does not need to block v1. I’m proposing it now to agree on whether it belongs in core or a plugin, and I’m happy to target v1.1 if that better fits the roadmap.

API surface

Proposed endpoints, subject to maintainer agreement:

• GET /api/v1/tailscale/capability — reports whether the server supports embedded Tailscale: { supported: boolean }.
• GET /api/v1/admin/tailscale/status — administrator-only connection status: { enabled, state, hostname, addresses, endpoints, auth_url?, error? }. state distinguishes disconnected, awaiting authorization, connecting, connected, and error. auth_url is returned only when enrollment requires it.
• POST /api/v1/admin/tailscale/connect — administrator-only start or resume connection. Optional request: { hostname }. Returns 202 Accepted with the current connection state; enrollment proceeds asynchronously.
• POST /api/v1/admin/tailscale/disconnect — administrator-only disables tailnet access and closes its listeners. Preserves node identity for a later reconnection.

Existing playback, authentication, Jellyfin-compatible, and Audiobookshelf-compatible APIs remain accessible through the new listeners. Clients use the appropriate tailnet endpoint and authenticate with their existing Silo credentials; no playback payload changes are proposed.

Private node keys are never exposed through the API. Enrollment URLs are administrator-only and excluded from logs. Identity deletion, automatic login through Tailscale identity, and Funnel are outside the initial scope.

Client impact (android / apple / web)

• Web: add the admin controls and connection status; verify playback, seeking, and realtime behavior through the tailnet endpoint.
• Android and Apple: no proposed playback API changes or embedded VPN. Verify existing server URL entry and playback against the tailnet endpoint on supported devices with Tailscale connectivity.
• Jellyfin and Audiobookshelf clients: preserve their separate protocol surfaces and verify authentication, playback, and progress updates.

Rough size (server-side)

M

AI harness

codex

AI tool(s)

codex

AI model(s)

astra

AI involvement

Human-written, AI-reviewed

Independent or adversarial review

• Independent or adversarial review: n/a for this proposal draft. Required before submitting a non-trivial implementation.

[Quick104]

Hey Alex! We're big fans and appreciate the interest. Yes, I want this in Silo. The one condition is that tsnet sits behind a provider interface so it can be swapped for the NetBird client or another overlay without touching the rest of the server.

Timing. The server is mid-transition to /api/v2, which is in testing and should merge soon. This targets v2 (v1 is frozen), so I'd rather land it after v2 settles. That likely means 1.1, which matches what you suggested.

Where it lives. In core, not the plugin runtime. Silo plugins run out-of-process over gRPC, and tsnet's connections come from a userspace network stack, so a plugin can't hand the server a listener. The provider boundary is an in-process Go interface: start, stop, status, listen returning a net.Listener, an optional identity lookup, and a state hook. Compiled in, disabled unless configured.

tsnet fits that directly. NetBird's embed package is close to a twin (userspace by default, ListenTCP, IdentityForIP, file-based state), so it's the second provider I'd expect. Pangolin's Newt is a command rather than a library and works as a reverse tunnel, so that stays a sidecar with a docs page.

API shape. Close to yours, generalised across providers under /api/v2/network-access and /api/v2/admin/network-access/{provider}: a capabilities endpoint listing supported providers, admin status, and connect/disconnect with connect returning 202. HTTPS with tailnet certs is the default listener, the same as tailscale serve. Provider state goes in Silo's encrypted settings so keys never sit in files or logs. Native, Jellyfin, and Audiobookshelf surfaces come through the overlay listener unchanged. Your exclusions stand: no Funnel, no identity login, no key exposure.

Clusters. Clients only talk to API replicas and proxy nodes, so those are the only places a provider is required. Transcode nodes are dialed over the backend address and don't need it. The hard part is that a client arriving over the overlay must be handed a proxy's overlay address rather than its LAN or public one. I'd phase it:

1. Provider interface, tsnet provider, admin API, web admin controls. Single-node deployments where the API server serves streams itself.
2. Providers on proxy nodes and per-access-path URL resolution for multi-node.
3. Later: NetBird provider, identity login via the existing auth-provider plugin type, Funnel.

Client side. Nothing needed. Tailscale ships native apps for every platform we target, so the clients just take the overlay URL as their server address.

[zZebrahz]

Thanks for the conversation on this, huge fan of your work!

I wanted to also highlight another project, Channels DVR that takes an approach similar to this (all by my own assumption/observation as their source is not public). They from what I can tell have implemented this directly into their server offering and they also offer native clients on Android/Apple/Amazon which do not implement Tailscale directly into their clients and point their users to install the Tailscale app in addition to their native clients.

Channels DVR project is often many versions behind of the latest Tailscale version and while they do mention they are in contact with the Tailscale team directly about their implementation and keeping it up to date with any security fixes, they do get a lot of public support requests regarding version control so if we move forward with this I'd also like to take that into consideration for maintainability. I don't know if the tsnet provider can auto update or if this would require a Silo Server dot version bump each time. Either way it could become a source of ongoing maintenance.

Ideally, we could make a pluggable system for this, however our initial discovery implied that this would not be easily feasible. We may have missed something in the discovery however that was why we felt core would be the best place for this if it were going to be worked on.

Just wanted to highlight these potential maintenance pieces as well as shed some light on a popular project out there that already has something along these lines incorporated, however I do believe that you likely already knew about this with your previous work experience 😄.

[ironicbadger]

Hi 👋 fwiw, Silo is exactly what we need today. A modern, multi-threaded system that is built for scale (perhaps a little more scale than many of us at home will ever need!). Kudos.

I checked tsnet’s update behavior and [its updater explicitly excludes custom tsnet binaries](https://github.com/tailscale/tailscale/blob/v1.102.4/clientupdate/clientupdate.go#L198-L203), so compiling it into Silo would require a new Silo build for Tailscale updates. What's your expected release cadence? tsnet could reasonably be expected every 6ish weeks iirc but you only need to update for CVEs or new features, it doesn't actually matter all that much tbh. It would show up as 1.102.3-ERR-BuildInfo in the console. So, the provider interface helps isolate code changes, but doesn’t decouple releases.

There is another plugin option that could be worth exploring. Let the plugin own the tsnet listener and reverse-proxy traffic to Silo locally, with gRPC handling configuration and status. No listener transfer is needed, [Tailscale even documents this pattern](https://tailscale.com/docs/reference/tsnet-server-api). Silo already has plugin update machinery and the main missing piece appears to be reliable startup/restart supervision for an always-running ingress plugin.

I’d suggest keeping the provider-neutral admin API and prototyping that helper approach once v2 settles. If the lifecycle and proxying work proves disproportionate, a compiled-in provider remains a reasonable first step, with the release coupling understood.

Do you have an approximate timeline for when /api/v2 will be ready for this work? I can easily wait until then if that makes integration simpler.

[Quick104]

Your first line is exactly what I pictured: a Proxmox cluster, or one box with transcodes offloaded to the old NUC in the corner.

Let's go down the plugin route. If it works I'd prefer it. It fits the plugin model better and makes maintenance significantly easier.

The host already has plugin auto-update, encrypted config, and hot reload. What it lacks is supervision for an always-running plugin: today the only automatic restart is on manifest drift. I'll take that on: an always-on plugin kind with startup ordering, crash restart with backoff, and health in the admin API.

The admin API stays provider-neutral under /api/v2/network-access, with the plugin reporting status and taking connect/disconnect over gRPC.

I'm aiming for /api/v2 to land on Monday. I'll need some time on client updates first, then I'll pick up the server and SDK work for the always-on plugin kind so you can build against it.

[ironicbadger]

Ping me if you can once the new api is released. Thanks!

[Quick104]

@ironicbadger

/api/v2 merged, and the server and SDK work for this is ready to build against. I want you to have a working plugin before the server PR merges so you can test the contract and request changes.

Build against

• SDK v0.16.1 (feat(network-access): add the network_access_provider.v1 capability silo-plugin-sdk#21, feat(auth): make usernames and emails case-insensitive #22): capability network_access_provider.v1 with Connect, Disconnect, and GetStatus. RuntimeHost now implements GetHostInfo (host role, node id, listeners to expose, an ingress token), ReadInstanceState and WriteInstanceState for encrypted per-instance state, and ReportNetworkAccessStatus. runtimehost.InstanceStateStore matches tsnet's ipn.StateStore shape apart from the key type. The proxy contract is in docs/[network-access-provider.md](https://github.com/home/dev/.t3/worktrees/silo-server/t3code-db0902e0/docs/network-access-provider.md), and examples/hello-network-access is a stub to copy from.
• Server branch feat/network-access-plugins (feat(plugins): resident network-access providers with proxy-node support #1096): plugins declaring the capability start at boot, restart on crash, and stop last. Proxy nodes run the same installation with their own state scope and report their overlay origin, so tailnet clients get the proxy's tailnet address for streams. Admin surface is /api/v2/network-access/capabilities, /api/v2/admin/network-access/{provider}/{status,connect,disconnect}, and a Settings page.

Contract, short version

• Each host runs its own instance and is its own tailnet node. Derive a distinct hostname per instance from GetHostInfo.
• On every proxied request preserve Host, set X-Forwarded-Proto: https and X-Forwarded-For, and set X-Silo-Ingress-Token from GetHostInfo. The token rotates on every process start.
• Expose every listener GetHostInfo returns: api always, jellyfin and abs when enabled, only api on proxies.
• Keep node state in the host store, never files. Persist desired_connected there and reconnect on start.
• Report awaiting_authorization with the auth URL for interactive login and never log it. Support an auth key as a secret config field so multi-node deployments enroll without a click per host.

If the contract needs a change, comment on #1096, or open a PR from your fork against feat/network-access-plugins and I'll merge it into the branch.

[ironicbadger]

Here you go. It is alpha status but seems to be functional for every Tailscale feature I'd want in a media server context.

https://github.com/ironicbadger/silo-plugin-tailscale

[zZebrahz]

Thanks!

I left some validation notes here to check later but wanted to also place it here in case you also wanted to check before I get to it.