Feature Remote access

English · Tiếng Việt · 中文

Remote access

Since 1.4.2, SkimMail can expose itself on the public internet through a tunnel — without opening an inbound port on your router — using either Cloudflare Tunnel or Tailscale as an optional, runtime-downloaded plugin.

What this solves

A self-hosted instance normally lives on a private network: a LAN, a VPN, or bound to localhost behind a reverse proxy you run yourself. That's fine at home, but "let me check mail from my phone on cellular data" needs a publicly reachable address, and the ordinary way to get one — a VPS with a public IP, your own reverse proxy, a TLS certificate — is infrastructure most self-hosters don't want to run just for this. Remote access gets you a public (or tailnet-private) HTTPS address without any of that, at the cost of trusting a tunnel vendor with your traffic's metadata.

Where it is

Settings ▸ Remote access, owner only — every route under /api/remote/* requires the owner role.

The two vendors

Vendor	Plugin	What you need	Address is stable?
Cloudflare Tunnel, quick tunnel	cloudflared (Cloudflare's own binary, SHA256-pinned)	Nothing — no account, no token	No — a fresh random trycloudflare.com URL on every start
Cloudflare Tunnel, named tunnel	cloudflared	A Cloudflare tunnel token and the hostname you configured for it in Cloudflare	Yes
Tailscale	skimmail-tunnel-ts (built by SkimMail, on tsnet)	A Tailscale auth key	Yes, on your tailnet; public only if you turn on Funnel

Both plugins are downloaded on demand — nothing ships in the base binary, apt package or container image — and installed/updated/removed through the same mechanism as every other runtime plugin; see Operations ▸ Plugins for the disk location, the manifest signature check, and what "in use" impact means during an update. This screen's own Install/Uninstall buttons cover getting the plugin onto disk; updating an installed vendor plugin happens from Settings ▸ Plugins, not from here — this screen has no Update button of its own.

Saving a vendor's configuration and starting the tunnel is one action, Save & connect. The token/auth-key fields are write-only: leaving one blank on a later edit keeps whatever is already stored, the same convention as every other secret field in Settings. A Cloudflare token travels to the cloudflared child process over an environment variable, never on its command line — a command line is visible to anyone on the host who can run ps.

The public URL and QR code

Once a tunnel is running, the panel shows the live URL, a Copy button, and a QR code rendered client-side (no third-party service sees the URL) that you can scan straight from a phone camera — useful for typing nothing at all on a small screen. A Cloudflare tunnel of either kind is always public the moment it is running; a Tailscale tunnel is public only when Funnel is turned on, and otherwise reachable only from devices on your own tailnet.

Starting a tunnel stops whichever one was already running — only one tunnel process runs at a time, regardless of vendor.

The AUTH_MODE=none hard guard

Every action that changes anything here — saving configuration, installing, starting, stopping — is refused outright while the server runs AUTH_MODE=none (the mode that skips a login screen entirely, meant for a genuinely private network). The screen replaces the vendor cards with a plain red banner, and the API answers 409 auth_mode_none. This is a hard guard in the code, not a setting you can override from the UI: turning off authentication and turning on remote access are treated as mutually exclusive on purpose, because a public tunnel into an instance with no login would hand your whole mailbox to whoever finds the URL. See Security for what AUTH_MODE=none is for.

The 2FA advisory

While a tunnel is public, the screen shows an amber warning if two-factor authentication looks disabled. One limit worth knowing: the check looks at account id 1 specifically, not at whoever is currently signed in. On the common single-owner instance that is you, so the advisory is accurate; on a multi-user instance it reflects whichever account was created first, which may not be the owner opening this screen and may not have 2FA on even if you do.

Limits

Available since	1.4.2
Role	owner
Vendors	2 — Cloudflare Tunnel, Tailscale
Concurrency	one tunnel process at a time, across both vendors
2FA advisory	checks account id 1 only, not the caller
Hard-disabled under	AUTH_MODE=none

What it does not do

• It adds no authentication of its own. A public tunnel makes SkimMail's own sign-in the only thing between the internet and your mail — which is exactly why the AUTH_MODE=none guard exists and why the 2FA advisory is shown at all.
• It cannot run two tunnels at once. Starting one stops whichever vendor was already running; there is no load balancing or failover between them.
• A Cloudflare quick tunnel gives you no control over the address. Only a named tunnel with a token is stable across restarts.
• It manages no TLS certificate of its own. Both vendors terminate TLS at their own edge; SkimMail never sees or stores a certificate for this.

See also

• Operations — where the plugin lives on disk, how it is updated, and the manifest signature check
• Security — AUTH_MODE and why none disables this feature entirely
• Configuration — SKIMMAIL_PLUGINS_URL, for pointing the plugin manifest fetch at a private mirror

---

SkimMail · skimmail@base101.app · 2026-09-15 · commit dffbb18