Remote Access
Remote access lets you reach a Smart Panel installation from outside your home network — a phone on cellular, a laptop at work — without port forwarding, a public IP address, dynamic DNS, or a hand-built reverse proxy. It ships as a core Remote access module that tracks how the installation is reachable, plus provider plugins that do the actual connecting. The available providers are Tailscale and Cloudflare Tunnel.
Remote access never opens a port on your router and never gives your installation a public IP address. Tailscale connects it to a private mesh network and stays private unless you explicitly turn on Funnel — the only way the Tailscale provider exposes anything publicly. A manually configured external URL or Cloudflare Tunnel can also make an installation publicly reachable.
Internal, External, and Primary URLs
Smart Panel tracks every way this installation can be reached and ranks them so other features — like the MCP module — have one canonical answer to “what is my URL”:
- Internal URL — the LAN address, derived from the backend’s host and port unless you override it. This
is what
http://smart-panel.local:3000resolves to. - External URLs — every address that reaches this installation from outside the LAN: a connected provider’s endpoint (e.g. a Tailscale HTTPS address) and/or a manually configured external URL.
- Primary external URL — Smart Panel ranks every external URL (HTTPS before HTTP, public before private) and treats the top of that ranking as the one to offer other features, such as MCP’s OAuth public base URL suggestion.
Both the internal and external URLs are absolute origins only — scheme, host, and optional port, no path, credentials, query, or fragment.
Choose Your Path
Sign in from a browser link or QR code. No account on your router, no public exposure by default, free tier is enough for a household.
Tailscale (recommended)Publish a dashboard-managed tunnel at your own public hostname. Remote clients need only a browser.
Cloudflare TunnelAlready run your own reverse proxy or dynamic DNS? Register the URL directly — no provider plugin required.
External URL BaselineThe Tailscale plugin isn’t supported inside those deployments. Use the vendor’s own Tailscale integration alongside the external URL baseline.
Docker & Home AssistantThe Remote Access Page
Open Remote access in the Admin UI menu (admin or owner role required). The page has three sections that update live as things change, without a reload:
- Access URLs — your internal URL with copy and QR buttons, plus any LAN candidate addresses (other
network interfaces,
<hostname>.local) you can copy but that aren’t part of the ranked list below. Below that, every external URL: each entry shows its label, an HTTPS/HTTP tag, a Public/Private tag, and a Primary tag on the top-ranked entry, each with its own copy and QR buttons. A manually configured external URL is labeled Manual external URL. - Providers — one card per installed remote-access provider plugin, showing its connection state and published endpoints. A plugin that hasn’t registered its own card yet still gets a generic one.
- Advisories — posture warnings such as an insecure external URL, forwarded-header trust configured without any trusted proxies, or any endpoint that is reachable from the public internet.
The module’s own settings — internal_url, external_url, trust_forwarded_headers, and
trusted_proxies — live under Config → Modules → Remote access. The Remote access module is a core
module but, unlike some others, can be enabled or disabled from the Extensions page. Disabling it
removes external URLs and proxy-trust contributions, leaving the internal URL resolvable. Provider plugins
have their own enablement: disable a provider in Extensions to stop its connection.
Set Up Tailscale
Tailscale connects this installation to a private, WireGuard-based mesh network (a tailnet). Once signed in, the admin UI is reachable from any device signed into the same tailnet — by its Tailscale IPv4 address, or by a MagicDNS name once your tailnet has MagicDNS enabled — with no port forwarding and no public exposure.
Before You Begin
- A Tailscale account — the free tier covers a household.
- To get the HTTPS address later, enable HTTPS Certificates in your tailnet’s DNS settings at login.tailscale.com/admin/dns . Skip this and Smart Panel still works over the tailnet’s plain HTTP address; an advisory reminds you it’s available.
- If your tailnet has device approval turned on, be ready to approve the new node from the Tailscale admin console before it can finish signing in.
- Smart Panel appliances are usually always-on, so consider disabling key expiry for this node in the Tailscale admin console once it’s signed in. If you leave it on, Smart Panel warns you fourteen days before the node’s key expires.
Set up
As the owner, open the Tailscale provider card and choose Set up. This runs a one-time, privileged job: it installs
the tailscale package if it isn’t already present, enables the tailscaled daemon, and grants the
Smart Panel service user as the Tailscale operator so the backend can manage the connection without
further sudo prompts. Progress streams to the card live. The step is idempotent — safe to re-run if it
fails partway or if a reinstall ever drops the operator grant.
The Raspberry Pi image and install-server.sh --with-tailscale both pre-install the tailscale package
(left disabled), so Set up finishes in seconds on those installs. Everywhere else it downloads the
package from Tailscale’s own signed repository during this step.
Sign in
Choose Sign in. Smart Panel shows a Tailscale login link and a QR code — open it on your phone or any device already signed into your tailnet and approve it there. The card polls and flips to Connected, showing the tailnet name, the MagicDNS name (once assigned), and the node’s Tailscale IPs.
For a headless or unattended install, an advanced option accepts a pre-authorised auth key from the Tailscale admin console instead of the interactive link. The key is used once to sign in and is never stored or logged.
Serve HTTPS
Once connected, if your tailnet has HTTPS certificates enabled, Smart Panel automatically serves the
admin UI over HTTPS at https://<node>.<tailnet>.ts.net through
Tailscale Serve — this is usually your primary external URL from
then on. If tailnet HTTPS isn’t enabled, an advisory links to the tailnet DNS settings page instead.
Funnel (optional)
Funnel publishes the Serve HTTPS address to the public internet, not just your tailnet. Your Smart Panel login becomes the only gate in front of it — there is currently no multi-factor authentication. Turn this on only if you specifically need a public URL (for example, a webhook callback), and treat it as public exposure.
Funnel is opt-in and off by default. Turning it on publishes the same Serve URL publicly and raises a persistent advisory reminding you it’s exposed. Your tailnet’s ACL policy also needs to allow Funnel for this node, or Smart Panel reports that as an advisory too.
Tailscale SSH (optional)
Turning on Tailscale SSH lets an administrator open a shell over the tailnet, subject to the tailnet
SSH policy and any required authentication check. Use an existing OS account with a login shell;
the smart-panel service account does not provide one. It is off by default. Turning it off disables
Tailscale SSH and does not stop the separate system OpenSSH service.
Hostname, the control-plane URL (for a self-hosted Headscale server), accepting the tailnet’s DNS and subnet routes, and ACL tags all live in the Tailscale plugin’s own settings, under Config → Plugins → Tailscale.
Connect, Disconnect, and Sign Out
The provider card distinguishes connection, authentication and the current operation:
- Connect starts or reconnects an authenticated node. Disconnect stops the current session and retains authentication. The card offers Connect again once the operation settles. A manually disconnected node can start again after an application restart; disable the plugin for a persistent choice.
- Extensions → Services lists
remote-access-tailscale-plugin / node. Start, Stop, and Restart behave as connect, disconnect, and reconnect. Disabling the Tailscale plugin from the Extensions page disconnects the node the same way. - Sign out, from the Remote access page, is a separate, explicit action: it expires the node’s key and stops authenticated tailnet access. A non-ephemeral device can remain listed in the Tailscale console; delete that listing there if needed. Sign out never happens as a side effect of disconnecting. Signing out can discard the operator grant: run Set up again if the card reports it missing.
- Reset preferences re-applies Smart Panel’s complete set of managed settings, clearing anything changed by hand outside Smart Panel (for example, at the command line on the host).
- A factory reset of the installation signs the node out and clears its Serve configuration along with everything else.
Set Up Cloudflare Tunnel
Cloudflare Tunnel publishes Smart Panel at a public HTTPS hostname without router port forwarding. It runs on Raspberry Pi and generic host installations. You need a Cloudflare-managed domain and a remotely managed tunnel in the Cloudflare dashboard.
Prepare the public route
Create a tunnel and configure its public hostname, such as panel.example.com, to forward to this
installation’s HTTP origin, normally http://localhost:3000. Use the actual backend port if you changed
it. Check that the hostname’s DNS record exists and points to the tunnel. Smart Panel does not create
the dashboard tunnel, DNS record or public route for you.
Install cloudflared
Enable Cloudflare Tunnel in Extensions, open its provider card and choose Set up as the owner.
Start setup installs cloudflared from the signed vendor package repository. If privileged setup is
unavailable, use Run it yourself, apply the displayed commands and choose Re-check. Once the
package requirements pass, the wizard advances to Token and hostname without requiring a saved token.
Configure the connector
Copy the tunnel token from the dashboard into the token field and enter the public hostname only,
without https:// or a path. Save the configuration. The token is stored for future reconnects but is
not returned in configuration reads. Keep the default Auto transport unless your network requires a
specific transport. The connector runs under the Smart Panel service user.
Verify public access
Connected means the connector has an active connection to Cloudflare’s edge. It does not prove that DNS or the public route reaches this installation. Open the public HTTPS URL from outside the LAN, check normal certificate validation, sign in and confirm that live updates work. A configured hostname is published as a public endpoint while connected and may become the primary external URL.
Cloudflare makes the route public: Smart Panel authentication still protects the admin/API. Review any additional access policy in your Cloudflare account separately. The plugin does not provide identity-header single sign-on.
Use the card’s service controls or disable the plugin in Extensions to stop its connector and withdraw its endpoints. To rotate credentials, save a replacement token; the connector restarts with it. Remove credentials explicitly to stop using them. Remove tunnel stops the connector and clears its local token and hostname; it does not delete the dashboard tunnel or DNS record. The package remains installed.
If Connected has no URL, configure the public hostname. If the URL fails while Connected, check DNS, the dashboard route and origin port before reinstalling the package. For a rejected or revoked token, replace it with the current token from the dashboard. Setup progress uses live events with status polling as a fallback, so an interrupted browser connection can recover without repeating installation.
Manual Setup
Set up normally runs unattended, as a privileged one-time job. If it’s unavailable on this installation (see Set up cannot run below) — or you simply prefer to prepare the system yourself — each unmet requirement shows its manual remedy, with a console command or documentation link. Preparing a provider entirely this way is fully supported, not just tolerated: once every requirement is satisfied, Smart Panel picks up the node exactly as if its own Set up action had run.
Tailscale
These are the exact commands the privileged Set up job runs on a Debian-family host (Raspberry Pi OS, Debian, Ubuntu) — the same ones Smart Panel shows you inline, per unsatisfied requirement, on the Remote access page:
Install the package
curl -fsSL https://pkgs.tailscale.com/stable/<id>/<codename>.noarmor.gpg | sudo tee /usr/share/keyrings/tailscale-archive-keyring.gpg >/dev/null
curl -fsSL https://pkgs.tailscale.com/stable/<id>/<codename>.tailscale-keyring.list | sudo tee /etc/apt/sources.list.d/tailscale.list >/dev/null
sudo apt-get update -qq
sudo apt-get install -y -qq --no-install-recommends tailscaleReplace <id>/<codename> with your distribution’s ID and version codename from /etc/os-release (for
example debian/bookworm, ubuntu/noble). On a non-Debian-family distribution, install Tailscale
using the vendor’s own instructions instead.
Enable the daemon
sudo systemctl enable --now tailscaledGrant the operator
sudo tailscale set --operator=smart-panelReplace smart-panel with your installation’s actual service user if you changed it during installation.
Once all three are done, choose Re-check. An already authenticated node can be adopted without signing out; otherwise use Smart Panel’s Sign in step. If you intentionally disconnected the managed service, choose Connect to resume it.
External URL Baseline
You don’t need Tailscale, or any provider plugin, to use remote access. If you already run your own reverse proxy (nginx, Caddy, a managed ingress) or dynamic DNS, register that address directly under Config → Modules → Remote access:
- External URL — the public origin your proxy or DDNS host answers on, e.g.
https://panel.example.com. It appears in the Remote access page’s external URL list labeled Manual external URL, and becomes the primary external URL when no connected provider offers a better-ranked one. - Trust forwarded headers and Trusted proxies — Smart Panel only honours
X-Forwarded-For,X-Real-IP,CF-Connecting-IP, andX-Forwarded-Protofrom a peer address you explicitly list here. A forwarded header from anywhere else is ignored, and the request falls back to being treated as coming directly from the proxy’s own socket address.
Your proxy must forward the client’s real address and terminate TLS itself (or pass along that it did):
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}Add the proxy’s address — the one Smart Panel actually sees as the connection’s socket peer, not a load balancer further upstream — to Trusted proxies and turn on Trust forwarded headers.
A proxy on the same host as the backend (loopback) must still be listed
explicitly. Smart Panel does not automatically trust forwarded headers from
127.0.0.1/::1 just because they’re local: without an explicit trust entry,
any other local process could otherwise spoof a client address and make itself
look like a trusted device, bypassing display registration and the login
throttle. A connected provider contributes its own proxy addresses while
connected: Tailscale Serve and Cloudflare Tunnel are trusted automatically
while their declared proxy endpoints are active and the module is enabled.
This trusted-proxy list is shared: it’s the same set the MCP module uses for its own reverse-proxy trust, and the same one the display-registration guard and login throttle resolve the real client address through — see the Network Requirements page for the general reverse-proxy setup.
Docker and Home Assistant Deployments
The Tailscale plugin needs privileged access to install and run tailscaled on the host — something the
Smart Panel Docker image and the (future) Home Assistant add-on sandbox deliberately don’t grant. Both
deployments report the Tailscale and Cloudflare Tunnel providers as unsupported rather than erroring.
Run a vendor-managed connector outside Smart Panel and use the external URL baseline for those deployments.
Use the external URL baseline together with the vendor’s own Tailscale integration instead:
- Docker — run the official
tailscale/tailscaleimage as a sidecar container on the same Docker network as Smart Panel, and point Smart Panel’s external URL at the address it publishes. See Docker Installation for the base Smart Panel setup. - Home Assistant — install the official Tailscale add-on from the Home Assistant add-on store, and use the same external URL baseline to register the address it gives you.
Troubleshooting
Tailscale shows “Setup required”
The daemon isn’t active yet, the operator grant is missing, or the node needs to sign in again (for example after a key expired). Open the Tailscale provider card and choose Set up — it’s safe to re-run — then Sign in if a login is still needed.
Set up cannot run
Set up reports it can’t start a privileged job on this installation — usually because this host was installed before the privileged-setup sudoers grant existed. Fix it by re-running the installer’s setup step, which is safe to repeat and won’t touch your existing data or configuration:
sudo smart-panel-service installRetry Set up afterward. If it still refuses immediately, wait about a minute — a failed check is cached briefly so a fix doesn’t require a full restart, but that also means it can take up to a minute to notice.
Sign-in fails with a permission error
This means the smart-panel service user was never granted as the Tailscale operator, usually because
Set up hasn’t completed successfully yet, or tailscaled was reinstalled and lost the grant. Re-run
Set up; it’s idempotent and re-applies the operator grant.
Actions do nothing / operator not granted
Sign in, sign out, reset preferences, or the Serve/Funnel toggles fail or seem to have no effect. This is the
same underlying cause as the permission error above — the smart-panel service user isn’t (or is no longer)
the Tailscale operator. Fix it with the exact one-line command Set up itself runs:
sudo tailscale set --operator=smart-panelReplace smart-panel with your installation’s actual service user if you changed it during installation.
Or just re-run Set up from the Remote access page — it’s idempotent and re-applies the same grant among its other steps.
The HTTPS URL never appears
Your tailnet doesn’t have HTTPS Certificates enabled. Turn it on at login.tailscale.com/admin/dns — the advisory on the Remote access page links there directly. The plain HTTP tailnet address keeps working in the meantime.
A “key expiring” advisory appears
The node’s Tailscale key expires within fourteen days. Choose Sign in again on the advisory, or open the Tailscale admin console and disable key expiry for this node, since it’s an always-on appliance rather than a laptop that regularly re-authenticates.
Sign-in is stuck on “Waiting for approval”
Your tailnet requires device approval for new nodes. Open the Tailscale admin console and approve the new Smart Panel device; the card moves to Connected once it’s approved.
Adopting a node prepared from the console
If you ran tailscale up by hand as root — for example while testing Tailscale on this device, or migrating
from a hand-rolled setup — before ever opening Smart Panel’s Remote access page, the node is already signed
in and connected, but the smart-panel service user isn’t the operator yet. Every action reports “operator
not granted,” as above.
You do not need to sign out or re-authenticate. Grant the operator once:
sudo tailscale set --operator=smart-panelReplace smart-panel with your installation’s actual service user if you changed it during installation.
Then reopen the Remote access page, or restart the remote-access-tailscale-plugin / node service from
Extensions → Services. Smart Panel picks up the already-connected node exactly as if its own Set up
action had prepared it from the start — a node prepared entirely from the console like this is fully
supported, not merely tolerated.
What’s Next?
- Network Requirements — general networking and reverse-proxy setup
- Model Context Protocol (MCP) — use your remote access URL for MCP OAuth
- Configuration — manage core module settings