Apus can auto-configure Tailscale Serve (tailnet) or Funnel (public) for the Gateway dashboard and WebSocket port. This keeps the gateway bound to loopback while Tailscale provides HTTPS, routing, and (for Serve) identity headers.

Modes

gateway.tailscale.mode:

Status and audit output use Tailscale exposure for this Apus Serve/Funnel mode. off means Apus is not managing Serve or Funnel. It does not mean the local Tailscale daemon is stopped or logged out.

Config examples

Tailnet-only (Serve)

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
  },
}

Open: https://<magicdns>/ (or your configured gateway.controlUi.basePath)

Tailnet-only (bind to Tailnet IP)

Use this to have the gateway listen directly on the Tailnet IP, with no Serve/Funnel:

{
  gateway: {
    bind: "tailnet",
    auth: { mode: "token", token: "your-token" },
  },
}

Connect a native or CLI client from another Tailnet device:

• WebSocket: ws://<tailscale-ip>:18789

The browser Control UI can create and sign device identity over the direct plain-HTTP address using pure-JavaScript Ed25519. With token/password auth, the shared secret still does not replace browser device identity.

Plain HTTP remains a downgraded transport: identity signing does not encrypt the page, shared secret, or Gateway traffic. Prefer Tailscale Serve for HTTPS. See Insecure HTTP.

Loading the Control UI from the Tailnet address itself is a private same-origin request and needs no gateway.controlUi.allowedOrigins entry. Public or cross-origin browser deployments need an allowed origin.

Public internet (Funnel + shared password)

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password", password: "replace-me" },
  },
}

Prefer APUS_GATEWAY_PASSWORD over committing a password to disk.

The Funnel URL also remains usable from devices inside the tailnet. Tailscale marks public requests as Funnel traffic but sends tailnet peers through its Serve identity path instead. Apus recognizes both paths on its dedicated listener and still requires the configured Funnel password.

CLI examples

apus gateway --tailscale serve
apus gateway --tailscale funnel --auth password

Auth

gateway.auth.mode controls the handshake:

When gateway.auth.mode is unset, a resolved password selects password mode. Without one, token is the default. If both gateway.auth.token and gateway.auth.password are configured, set the mode explicitly.

When token mode has no credential, loopback startup generates a runtime-only token without writing it to config. A separate apus qr command still needs usable configured or supplied token/password authentication. That startup-only token does not configure pairing. See QR auth resolution.

Tailscale identity headers (Serve only)

When tailscale.mode: "serve" and gateway.auth.allowTailscale is true, Control UI/WebSocket auth can use Tailscale identity headers (tailscale-user-login) instead of a token/password. Apus verifies the header by resolving the request's x-forwarded-for address via the local Tailscale daemon (tailscale whois) and matching it to the header login before accepting it. A request only qualifies when it reaches Apus's dedicated managed-Tailscale listener with Tailscale's x-forwarded-for, x-forwarded-proto, and x-forwarded-host headers. Those headers never establish managed Serve provenance or tokenless auth on the ordinary Gateway listener.

This tokenless flow assumes the gateway host is trusted. If untrusted local code may run on the same host, set gateway.auth.allowTailscale: false and require token/password auth instead.

Scope of the bypass:

• Applies to the Control UI WebSocket auth surface and read-only GET/HEAD requests for Control UI profile avatars. Other HTTP API endpoints (/v1/*, /tools/invoke, /api/channels/*, etc.) never use Tailscale identity-header auth. They always follow the gateway's normal HTTP auth mode.
• For Control UI operator sessions that already carry browser device identity, a verified Tailscale identity skips the bootstrap-token/QR pairing round trip.
• It does not bypass device identity itself: device-less clients are still rejected, and node-role connections still go through normal pairing and auth checks.

Externally managed Serve and Funnel

You can point a native Tailscale Serve or Funnel route at the ordinary Gateway listener when another service owns the route. Configure the route's immediate source narrowly in gateway.trustedProxies, and ensure it overwrites or safely rebuilds X-Forwarded-For. Apus then treats the request as generic trusted-proxy ingress, uses the forwarded client address for rate limits, and applies the configured gateway auth mode normally. Because Funnel is public, Gateway-protected routes reject externally managed Funnel ingress when gateway.auth.mode is none. Configure token, password, or trusted-proxy authentication. The aggregate health, readiness, and startup checks retain their existing unauthenticated responses, without exposing detailed readiness or startup data. See Health and readiness.

This compatibility path does not grant managed Tailscale semantics. gateway.auth.allowTailscale cannot provide tokenless auth. Apus does not call tailscale whois. It does not own or clean up the external route. Without an explicitly trusted source and a valid non-loopback forwarded client address, Gateway-authenticated routes fail with proxy_attribution_required. If the proxy connects over loopback, adding 127.0.0.1 to trustedProxies explicitly trusts same-host processes to supply proxy attribution. Keep token or password auth enabled unless every process on the host belongs to the same trust boundary.

Notes

• Tailscale Serve/Funnel requires the tailscale CLI installed and logged in.
• Ordinary apus doctor checks the configured local Serve/Funnel backend before maintenance and repair prompts. It names stopped, logged-out, approval-pending, starting, or unavailable backends and prints the next action. This prerequisite check does not enable Tailscale, change routes, or modify exposure/authentication settings. Update-driven Doctor defers this advisory until ordinary Doctor runs after the update, because shipped updaters restrict candidate config reads; repairs remain best effort. A running backend alone does not prove the Serve/Funnel route or Gateway is ready.
• tailscale.mode: "funnel" refuses to start unless auth mode is password, to avoid public exposure.
• Apus holds Serve/Funnel as a foreground Tailscale claim. Gateway startup normally succeeds only after the claim is active, and stopping or losing the Gateway releases it automatically. If Serve explicitly reports that it is not enabled on the tailnet, including when it waits for enablement until the startup deadline, Apus confirms claim cleanup, warns, and keeps the authenticated loopback Gateway available. Remote Serve access remains unavailable; configuration and tailnet policy are unchanged. Restore the intended Serve policy and restart the Gateway to retry. Funnel denials, unknown failures, cancellation, and unconfirmed cleanup still stop startup.
• Stopping during startup also releases the claim before readiness. If Tailscale requires sudo -n, cleanup uses sudo -n /bin/kill for the process group Apus started. Give the Gateway user Tailscale operator access with sudo tailscale set --operator=$USER to avoid requiring privileged startup and cleanup.
• With managed ingress enabled, startup can adopt a predecessor background HTTPS root route on its managed port. It adopts the route when the target is exactly http://127.0.0.1:<configured-gateway-port>, or the equivalent localhost URL with an optional trailing slash. Startup then replaces the route with the dedicated managed listener and logs the adoption. Routes to other targets, or roots sharing their port with other handlers or hostnames, remain untouched. Startup reports the conflicting HTTPS port and recovery guidance. Doctor leaves externally managed configuration unchanged.
• Named Tailscale Services are not supported by managed ingress because Tailscale requires them to run as persistent background routes. Existing gateway.tailscale.serviceName installs must run apus doctor --fix. Doctor disables managed ingress and removes the key. Inspect the retained Service route, clear it with tailscale serve clear <service-name>, then enable device Serve with gateway.tailscale.mode: "serve" if desired.
• Older releases could advertise an externally configured default HTTPS Serve route that targeted a gateway.bind: "lan" listener. That route does not automatically gain trusted ingress provenance. Run apus doctor to inspect it. Doctor leaves the configuration unchanged, because it cannot prove who owns the route. The route may belong to the current Tailscale hostname and be stale from an older Apus release. If you confirm that, remove only its root handler with tailscale serve --yes --https=443 --set-path=/ off or tailscale funnel --yes --https=443 --set-path=/ off. Then configure gateway.bind: "loopback" plus gateway.tailscale.mode: "serve" manually, and restart the Gateway. If another service must retain ownership, leave managed Tailscale ingress off and use the explicit trustedProxies compatibility path above.
• gateway.tailscale.preserveFunnel: true is a deprecated migration guard. It detects an externally configured tailscale funnel route before reapplying Serve. If that route still targets the ordinary Gateway listener, Apus leaves it unchanged and warns because the route is not managed ingress. Gateway-authenticated routes work only through the explicit trustedProxies compatibility path above and continue to require the configured auth. Plugin-authenticated webhook routes such as Google Chat and SMS keep using their own signature and auth checks. To migrate, first configure a durable gateway.auth.password (prefer a SecretRef) or APUS_GATEWAY_PASSWORD. Set gateway.auth.mode to password. Run apus config set gateway.tailscale.mode funnel. Then run apus config unset gateway.tailscale.preserveFunnel.
• gateway.bind: "tailnet" uses a direct Tailnet bind (no HTTPS, no Serve/Funnel) plus required local 127.0.0.1 when a Tailnet IPv4 is available. Otherwise it falls back to loopback only.
• gateway.bind: "auto" uses 0.0.0.0 in detected containers and prefers loopback otherwise. Use tailnet to limit direct network exposure to the Tailnet while retaining same-host loopback access.
• The main Serve/Funnel route exposes the Gateway Control UI + WS. Nodes connect over that same WS endpoint. Portals allocate separate private Serve HTTPS ports; they never inherit Funnel exposure. Tailnet grants or ACLs must allow the portal ports as well as the Gateway port. Externally managed routes do not automatically allocate portal ingress.

Tailscale prerequisites and limits

• Serve requires HTTPS enabled for your tailnet. The CLI prompts if it is missing.
• Tailnet Serve traffic injects Tailscale identity headers. Public Funnel traffic uses a Funnel marker instead, while tailnet access to the same Funnel URL follows the Serve identity path.
• Apus-managed Serve/Funnel proxy to a dedicated 127.0.0.1:<ephemeral-port> listener while ordinary local clients keep the configured Gateway port. Startup fails closed rather than sharing listener provenance, and the foreground claim releases the route when its Gateway owner disappears.
• When the Gateway starts at boot before the local Tailscale daemon has connected (tailscale status reports NoState or Starting, or the daemon is not accepting connections yet), the managed claim waits up to 90 seconds for it, logging progress. Any other daemon state fails closed immediately.
• A daemon reporting Stopped still prevents Gateway startup. Completed failures with that explicit status do not trigger channel crash-loop suppression after the Tailscale connection is restored. Apus never starts a deliberately stopped Tailscale daemon. Unknown startup failures and unclean exits retain the normal breaker protection.
• Hostname discovery accepts status output up to 16 MiB, including peer lists on large tailnets. If discovery fails, the Gateway logs a warning and keeps its active Serve/Funnel claim, but managed portals remain unavailable. Check tailscale status --json on the Gateway host, resolve the reported error, and restart the Gateway to publish its hostname.
• Funnel requires Tailscale v1.38.3+, MagicDNS, HTTPS enabled, and a funnel node attribute.
• Funnel only supports ports 443, 8443, and 10000 over TLS.
• Funnel on macOS requires the open-source Tailscale app variant.

Recover an orphaned foreground claim

Older Gateways could leave a foreground Tailscale claim running after a forced shutdown or an interrupted sudo-backed start. Updating fixes cleanup for new claims but does not automatically remove existing claims with unproven ownership.

If startup reports an occupied HTTPS port, run tailscale serve status --json. Check Foreground for the reported session, hostname, path, and proxy target. On macOS or Linux, inspect candidate CLI processes with ps -axo pid,ppid,args | grep '[t]ailscale'. Confirm which process created that route before stopping it with kill -TERM <confirmed-pid> (or sudo kill -TERM <confirmed-pid> for a root process). Tailscale status does not report the claimant PID. A backend listener PID or an orphaned parent alone does not prove ownership. If another application owns the claim, leave it alone and keep Apus managed ingress off until you resolve the conflict.

Verify that the foreground session disappears from tailscale serve status --json, then restart the Gateway. tailscale serve --https=443 --set-path=/ off removes a background Web handler. It does not release a foreground claim.

Browser control (remote Gateway + local browser)

To run the Gateway on one machine but drive a browser on another, run a node host on the browser machine. Keep both machines on the same tailnet. The Gateway proxies browser actions to the node. No separate control server or Serve URL is needed.

Avoid Funnel for browser control. Treat node pairing like operator access.

Learn more

• Tailscale Serve overview: https://tailscale.com/kb/1312/serve
• tailscale serve command: https://tailscale.com/kb/1242/tailscale-serve
• Tailscale Funnel overview: https://tailscale.com/kb/1223/tailscale-funnel
• tailscale funnel command: https://tailscale.com/kb/1311/tailscale-funnel

Related

• Remote access
• Discovery
• Authentication