Away From Home

Out of the box, Plinthio is for your home network: devices on your Wi-Fi open http://<server>:8088. This page covers using it anywhere else, and letting other people in. All of it is optional.

Which Do I Need?

You want	Use	Devices need	Router changes
Just home	Nothing to do	A browser	None
You and a few people you trust, anywhere	Tailscale	The free Tailscale app, signed in	None
Friends and family, no apps, no domain	Tailscale Funnel	A browser	None
Friends and family, no apps, full speed	A web address	A browser	Two ports forwarded, and a domain

Tailscale is private: nothing is reachable from the internet, and it works on any internet connection. Funnel and a web address both put your sign-in page on the internet, so read Keeping It Safe first.

• Funnel is the easiest public option: a permanent link with no domain and no router changes, which works even where your provider blocks incoming connections. It goes through Tailscale's servers, which limit bandwidth. That's fine for books, comics and audiobooks, but video may stutter.
• A web address goes straight to your server at full speed, but needs a domain and access to your router.

You can combine them: Tailscale for you, and Funnel or a web address for everyone else.

Who Can Connect From Where

Admin → Network decides who's allowed in from where:

• Allow access from outside the home network. Off: only home devices (and Tailscale) can sign in or use anything, and visitors from the internet see "available at home only". On: anyone whose account is allowed away from home can sign in from anywhere. New servers choose this in the setup wizard. Servers upgraded from before 1.4.0 keep it on.
• Tailscale devices count as home. On by default.
• Require two-factor away from home. Optional. Sign-ins from outside then need a code from an authenticator app. At home a password is enough, so anyone can sign in there and set two-factor up.

Per person, in Admin → Users → Edit: Can use Plinthio away from home. Turn it off for accounts that should only work at home, such as children's accounts. Every request is checked, not just sign-in, so a phone that signed in at home can't keep using a home-only account once it leaves. The reading apps and API keys follow their owner's setting.

Admin → Network also shows where the device you're using is connecting from, whether Tailscale and Funnel are reaching Plinthio (with the .ts.net address), a step-by-step Tailscale guide that writes your .env lines for you, a warning when a proxy is sending addresses Plinthio isn't trusting, and recent sign-ins from outside.

"Home" means the addresses a home network uses: 192.168.x.x, 10.x.x.x, 172.16–31.x.x, link-local, and their IPv6 equivalents. Tailscale is 100.64–127.x.x. Everything else is outside. The first-run setup can only be done from home.

Docker Desktop

On Docker Desktop (Mac and Windows), containers never see visitors' real addresses, so everyone looks like they're at home and these controls can't tell anyone apart. On Docker Desktop, use Tailscale rather than opening Plinthio to the internet.

Tailscale

Tailscale connects your devices over an encrypted private network, through any internet connection, without opening anything on your router. It's free for personal use. Plinthio gets a trusted https://plinthio.<your-tailnet>.ts.net address, so there are no certificates to install and the installed app works offline.

1. Make a Tailscale account. In the admin console, go to DNS and turn on MagicDNS and HTTPS Certificates.

2. Next to docker-compose.yml, download the Tailscale add-on:

   curl -fsSLO https://raw.githubusercontent.com/OddOmens/Plinthio/main/docker/docker-compose.tailscale.yml

3. In the admin console, go to Settings → Keys → Generate auth key. Add the key and the add-on to .env:

   TS_AUTHKEY=tskey-auth-…
   COMPOSE_FILE=docker-compose.yml:docker-compose.tailscale.yml

   No key? Leave TS_AUTHKEY out and sign in with the link that docker logs plinthio-tailscale prints.

4. Run docker compose up -d.

5. On each phone or computer, install Tailscale, sign in, open https://plinthio.<your-tailnet>.ts.net (listed under Machines in the admin console), and add it to the home screen from there.

The add-on runs Tailscale as its own device on your tailnet, named by TS_HOSTNAME (default plinthio). It shares Plinthio's network and forwards only to Plinthio. Its saved sign-in is in a tailscale folder next to the compose file. Don't share that folder. TS_AUTHKEY is only needed for the first sign-in, so you can delete it from .env afterwards.

Tailscale already on the server, or no Docker: run sudo tailscale serve --bg 8088 (the port Plinthio is on). Without Docker, also set TRUST_PROXY=loopback. With Docker and Tailscale on the host, use the add-on instead, because Plinthio can't tell Tailscale devices apart otherwise.

Letting someone else in: in the admin console, open the Plinthio machine's ⋯ → Share and send them the link. They sign in to Tailscale with their own account and see only Plinthio, not your other devices. Then make them a Plinthio account.

Tailscale Funnel

Funnel opens the same https://plinthio.<your-tailnet>.ts.net address to the whole internet. Friends open the link in a browser and sign in, with nothing to install. You don't need a domain or router changes, and it works behind CGNAT (common with 5G home internet and Starlink). Only you need a Tailscale account.

Funnel traffic goes through Tailscale's servers, and Tailscale limits its bandwidth. Reading and listening are fine. Video may buffer, especially in HD or with several people watching. For full-speed video, use a web address.

1. Set up Tailscale with the Docker add-on first.

2. Turn on Admin → Network → Allow access from outside the home network. Consider turning on Require two-factor away from home too, and set up two-factor for yourself.

3. Add to .env (exactly true):

   TS_FUNNEL=true

4. Run docker compose up -d --force-recreate. The --force-recreate matters when Tailscale is already running, because Compose doesn't notice a changed TS_FUNNEL on its own.

5. The first time, Tailscale may need Funnel allowed for your tailnet. If docker logs plinthio-tailscale says Funnel isn't enabled, follow the link it gives, or allow the funnel attribute under Access controls in the admin console.

6. Check it: on a phone with Wi-Fi off and Tailscale not running, open the link. You should see the sign-in page. Sign in as an admin and open Admin → Network: it should say you're connecting from outside.

Send friends the link and make them accounts in Admin → Users. To close it again, set TS_FUNNEL=false and run docker compose up -d --force-recreate. Your own Tailscale devices keep working either way.

• Funnel visits always count as outside, even from your own Wi-Fi. Visits from your own Tailscale devices count as Tailscale.
• HTTPS ends inside the add-on, with a certificate Tailscale gets for you. Tailscale's relays pass the encrypted traffic along without reading it.
• Funnel names are public: every certificate is published in public logs. The link only leads to the sign-in page, so your passwords and two-factor are what keep people out.

A Web Address for Guests

Guests open something like https://media.yourdomain.com, sign in, and add it to their home screen. The public-address add-on runs Caddy, which gets and renews a free Let's Encrypt certificate by itself. Budget half an hour, mostly for your router and DNS settings.

1. Check Your Connection Allows It

Some providers don't let anything in from the internet at all (CGNAT). That's common with 5G and 4G home internet, Starlink, and some fibre and cable providers.

1. Open your router's status page and find its WAN or internet IP address.
2. On any device at home, visit a "what is my IP" site.
3. If the two match, you're fine. If the router's address starts with 100.64–100.127, 10., 172.16–172.31 or 192.168., or the two differ, you're behind CGNAT and a web address won't work. Use Tailscale or Funnel instead, or ask your provider for a public IP.

Also note whether your address changes over time. Most home ones do, and then you'll need dynamic DNS in step 3.

2. Get a Domain

Any registrar works. You can use a subdomain like media.yourdomain.com and keep the main domain for other things.

3. Point the Name at Your Home

In your domain's DNS settings, add an A record: name media (or whatever you chose), value your home's public IP from step 1. If your IP changes, set up dynamic DNS so the record follows it. Many routers have it built in.

4. Forward Two Ports

Forward TCP 80 and TCP 443 (and optionally UDP 443, for HTTP/3) on your router to the machine running Plinthio. Give that machine a fixed address on your network first (a DHCP reservation). Don't forward 8088.

5. Turn On Outside Access

Turn on Admin → Network → Allow access from outside the home network. Consider Require two-factor away from home, and set up two-factor for your own account in Settings → Security.

6. Start the Add-On

Next to docker-compose.yml:

curl -fsSLO https://raw.githubusercontent.com/OddOmens/Plinthio/main/docker/docker-compose.public.yml

Add to .env:

PLINTHIO_DOMAIN=media.yourdomain.com
COMPOSE_FILE=docker-compose.yml:docker-compose.public.yml
# With Tailscale too:
# COMPOSE_FILE=docker-compose.yml:docker-compose.tailscale.yml:docker-compose.public.yml

Run docker compose up -d. The certificate usually arrives within a minute: docker logs plinthio-caddy says "certificate obtained successfully". Caddy keeps its certificates in caddy/data and caddy/config next to the compose file. Keep those folders, or Caddy asks Let's Encrypt again on every restart.

7. Check It

On a phone with Wi-Fi off, open https://media.yourdomain.com. You should see Plinthio's sign-in page with a padlock. Sign in as an admin and open Admin → Network: it should say you're connecting from outside the home network.

Your Own Reverse Proxy

Nginx Proxy Manager, Traefik, SWAG or your own nginx work too:

1. Point the proxy at Plinthio's port 8088 (or 8080 from inside Docker's network).
2. Set TRUST_PROXY to the proxy's address as Plinthio sees it, for example TRUST_PROXY=172.18.0.5, or a subnet like TRUST_PROXY=172.18.0.0/16. Never use 1 or true unless Plinthio is reachable only through the proxy.
3. Run docker compose up -d.

Admin → Network warns you if a proxy is sending forwarded addresses that Plinthio isn't trusting. Watch parties and the reading apps need nothing extra.

Keeping It Safe

Funnel and a web address both put your sign-in page on the internet. Take a few minutes:

• Nobody can sign up. Only an admin makes accounts.
• Use strong passwords, especially for admins.
• Turn on two-factor for admins at least, and consider requiring it away from home.
• Make accounts home-only for anyone who doesn't need outside access.
• Give guests expiring accounts.
• Keep Plinthio updated. Admins see a banner when there's a new version.
• Check who's signing in: Admin → Network lists recent sign-ins from outside, and Admin → Logs has every attempt.

Plinthio also limits failed sign-ins to ten per fifteen minutes per address, doesn't reveal which usernames exist, and lets you end every session at once. It has not had an independent security audit. It's built for your home and people you invite, not for hostile or public multi-user hosting.

Troubleshooting

Problem	Fix
The Funnel link doesn't load for friends	docker exec plinthio-tailscale tailscale funnel status should say Funnel is on. If it says "tailnet only", check TS_FUNNEL=true (exactly) and run docker compose up -d --force-recreate. Check Funnel is allowed for your tailnet (docker logs plinthio-tailscale), and test with Tailscale off on the phone. Funnel can take a minute to start
Video buffers over Funnel	Tailscale limits Funnel's bandwidth. Pick a lower quality in the player, or use a web address
The web address doesn't load from outside	Check for CGNAT, that the A record shows your current IP (nslookup media.yourdomain.com), and that ports 80 and 443 go to the right machine. Some providers block those ports
It works from outside but not at home	Some routers can't loop back to your own public address. At home, keep using http://<server>:8088, or add the name to your router's local DNS
Caddy can't get a certificate	Port 80 or 443 isn't reaching Caddy, or the DNS record is wrong or very new. docker logs plinthio-caddy says which
Admin → Network says "home" from a phone on mobile data	Plinthio can't see the real address. Docker Desktop never can (use Tailscale). With your own proxy, set TRUST_PROXY
"Available at home only" from outside	Outside access is off in Admin → Network
"This account is for home use only" (P110)	Admin → Users → Edit → turn on Can use Plinthio away from home
"Two-factor needed away from home" (P112)	Sign in at home once and turn on two-factor in Settings → Security
Lost the phone with the authenticator app	Use a backup code. None left? An admin can reset two-factor in Admin → Users