OctoPrint Tailscale Funnel Plugin

This plugin makes your OctoPrint instance accessible from anywhere via Tailscale Funnel, without needing to configure port forwarding, dynamic DNS, or complex firewall settings.

Disclaimer: This plugin was partially vibe-coded.

Features

• Enable/disable Tailscale Funnel access directly from OctoPrint's settings
• Monitor the current Funnel connection status
• Display the public URL for accessing OctoPrint remotely
• Configure the port to expose via Funnel

Screenshot

Requirements

• OctoPrint 1.3.0 or higher
• Tailscale installed and configured on the system
• Python 3.7 or higher

Installation

1. Install Tailscale on your system and ensure it's running (see https://tailscale.com/download/linux or run curl -fsSL https://tailscale.com/install.sh | sh)
2. Start Tailscale on your system (run sudo tailscale up)
3. Authenticate using the Tailscale URL (e.g. https://login.tailscale.com/a/)
4. Install the plugin through OctoPrint's plugin manager (go to Settings -> Plugins -> Install and search for "Tailscale Funnel")
5. Configure the plugin settings in OctoPrint's settings panel
6. Enable Funnel through the plugin interface

Latest Release

Get the latest packaged release (wheel, sdist, zip) from Gitea: Releases

Building from Source

If you want to build the plugin from source, please refer to the BUILDING.md file for detailed instructions.

Configuration

The plugin adds a new section to OctoPrint's settings panel with the following options:

• Port: The port to expose via Funnel (default: 80)
• Confirm Enable: Require confirmation before enabling Funnel (default: True)

Runtime Permissions (sudo)

Some Tailscale operations (serve/funnel) may require elevated privileges depending on your setup. The plugin executes tailscale from the OctoPrint process user. If enabling/disabling Funnel fails with permission errors or HTTP 500, configure passwordless sudo for the OctoPrint user to run tailscale:

1. Determine the OctoPrint service user (common: octoprint or pi):

systemctl show -p User octoprint | sed 's/User=//'

2. Allow passwordless sudo for tailscale for that user (replace ):

echo '<USER> ALL=(root) NOPASSWD: /usr/bin/tailscale *' | sudo tee /etc/sudoers.d/octoprint-tailscale
sudo chmod 440 /etc/sudoers.d/octoprint-tailscale
sudo visudo -cf /etc/sudoers.d/octoprint-tailscale

3. Test (should not prompt for a password):

sudo -n tailscale status --json >/dev/null && echo OK || echo FAIL

Security note: Restricting the sudo rule to /usr/bin/tailscale * limits elevated access to the Tailscale CLI.

Initial Tailscale Serve/Funnel setup (optional)

If you prefer preconfiguring Tailscale manually (instead of letting the plugin set it up), these commands map OctoPrint on port 80 to the root path and enable Funnel using current Tailscale CLI syntax:

# Tailnet-only mapping at /
sudo tailscale serve --bg --http 80 http://127.0.0.1:80
# Public internet via Funnel (HTTPS will be available on 443)
sudo tailscale funnel --bg 80

Disable/reset if needed:

sudo tailscale serve --http=80 off
sudo tailscale funnel reset

Security Considerations

Enabling Funnel makes your OctoPrint instance accessible from the public internet. Only enable it when needed and disable it when finished. The plugin will show a confirmation dialog before enabling Funnel if the "Confirm Enable" option is checked.

Disable Funnel automatically on system boot (systemd)

If you prefer to make sure the Tailscale Funnel is always off after a system reboot (independent of the plugin), you can add a small systemd unit that disables Funnel shortly after boot:

1. Create unit file:

sudo tee /etc/systemd/system/octoprint-tailscale-funnel-off.service >/dev/null <<'UNIT'
[Unit]
Description=Disable Tailscale Funnel after boot
After=network-online.target tailscaled.service
Wants=network-online.target

[Service]
Type=oneshot
User=octoprint
ExecStart=/usr/bin/tailscale funnel reset
# Optional: also turn off possible serve mappings on common ports
ExecStart=/usr/bin/tailscale serve --http=80 off
ExecStart=/usr/bin/tailscale serve --https=80 off

[Install]
WantedBy=multi-user.target
UNIT

2. Enable and test:

sudo systemctl daemon-reload
sudo systemctl enable --now octoprint-tailscale-funnel-off.service
sudo systemctl status octoprint-tailscale-funnel-off.service

Notes:

• Adjust User=octoprint if your OctoPrint runs under a different user (e.g. pi).
• If sudo is required for tailscale on your system, add the corresponding sudoers entry as described above.
• You can add a short delay by inserting ExecStartPre=/bin/sleep 5 if Tailscale comes up late during boot.

API Endpoints

The plugin exposes the following API endpoints:

• GET /api/plugin/tailscale_funnel/status - Get current Funnel status
• POST /api/plugin/tailscale_funnel/enable - Enable Tailscale Funnel
• POST /api/plugin/tailscale_funnel/disable - Disable Tailscale Funnel

Updates via Gitea (update.json)

This plugin can announce new versions via a JSON file hosted in your Gitea repo. The plugin is configured to read: https://gitea.elpatron.me/elpatron/octo-funnel/raw/branch/main/update.json

Workflow for a new release (example to bump 0.1.1 → 0.1.2):

1. Update the version in setup.py (plugin_version = "0.1.2").
2. Build artifacts (sdist/wheel/ZIP).
3. Upload the ZIP to Gitea Releases or ensure the archive URL resolves for the tag.
4. Commit and push update.json with the new version:

{ "version": "0.1.2" }

5. In OctoPrint: open Software Update and trigger a re-check (or restart).

License

AGPLv3