Skip to Content
🚀 We just launched! Please star us on Github!

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:3000 resolves 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


The 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 tailscale

Replace <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 tailscaled

Grant the operator

sudo tailscale set --operator=smart-panel

Replace 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, and X-Forwarded-Proto from 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/tailscale image 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 install

Retry 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-panel

Replace 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-panel

Replace 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?

Last updated on