Running a Containerized ttyd and tmux Web Terminal over Tailscale for Mobile Homelab Access

A phone showing a tmux session in a browser terminal served by a Docker container over a private Tailscale network

A phone can reach your homelab terminal without a single public port, and it can come back to the same shell after a dropped signal. The recipe is a small Docker container running ttyd, a web terminal daemon, wrapped around a persistent tmux session, reachable only over your private Tailscale network. If a long build or an AI coding session is running when you lock the screen, it keeps running, and you reattach when you are ready.

This guide builds that container from scratch. For the personal story behind why I wanted it, read Running Full AI Coding Sessions from My Phone with ttyd, tmux, and Tailscale on Frizzle Tech Blog.

Prerequisites

The setup needs very little. Any Linux host that already runs containers will do, as long as it has joined your tailnet and you can reach it from your phone through the Tailscale app.

  • A Linux host running Docker Engine with the Docker Compose plugin.
  • A Tailscale account with the host joined to your tailnet, plus the Tailscale app signed in on your phone.
  • A non-root user with UID and GID 1000 on the host.
  • A modern mobile browser such as Safari on iOS or Chrome on Android.
  • A workspace directory on the host that holds the repositories you want to reach, for example /path/to/git.

Step 1: Craft the Mobile-Optimized Containerfile

Start with a Debian Bookworm base image. Debian Bookworm does not package ttyd, so the Containerfile downloads the official static binary from the project releases page. Add tmux, git, and the basic tools you reach for on a phone, then switch to a non-root user so a compromised session does not own the container.

FROM debian:bookworm-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
       tmux git openssh-client curl ca-certificates \
       build-essential vim less \
    && rm -rf /var/lib/apt/lists/*

ARG TTYD_VERSION=1.7.7
RUN curl -fsSL -o /usr/local/bin/ttyd \
       "https://github.com/tsl0922/ttyd/releases/download/${TTYD_VERSION}/ttyd.$(uname -m)" \
    && chmod +x /usr/local/bin/ttyd

RUN useradd -m -u 1000 -s /bin/bash dev
COPY tmux.conf /home/dev/.tmux.conf
COPY entrypoint.sh /usr/local/bin/entrypoint.sh
RUN chmod +x /usr/local/bin/entrypoint.sh \
    && chown dev:dev /home/dev/.tmux.conf

USER dev
WORKDIR /home/dev/work
EXPOSE 7681
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

Swap dev for whatever username you prefer. Keeping UID 1000 means files you create in the mounted workspace match the owner on the host.

Step 2: Configure tmux Auto-Reattach and Touch Scrolling

The trick that makes this survive bad signal is tmux new-session -A. The -A flag attaches to the named session if it exists and creates it if it does not. When your phone drops off the network, the websocket closes, but tmux keeps the shell and everything inside it alive.

Create entrypoint.sh:

#!/usr/bin/env bash
set -euo pipefail

exec ttyd \
  --writable \
  --port 7681 \
  --interface 0.0.0.0 \
  -t fontSize=18 \
  -t disableLeaveAlert=true \
  tmux new-session -A -s mobile-terminal

The --writable flag matters because recent ttyd versions start read-only. The fontSize=18 client option keeps text readable on a small screen, and disableLeaveAlert stops the browser from nagging you when you close the tab.

Then create tmux.conf so touch scrolling and a roomy scrollback work:

set -g mouse on
set -g history-limit 50000
set -g status-position top
set -g default-terminal "tmux-256color"

With mouse on, dragging a finger scrolls the pane history instead of sending raw arrow keys to your shell.

Step 3: Deploy the Service with Docker Compose

Put the Containerfile, entrypoint.sh, and tmux.conf in one folder such as /path/to/git/mobile-terminal. Create an empty gitconfig file there too (or copy your own with cp ~/.gitconfig gitconfig), because Docker would otherwise create a directory with that name. Then add a docker-compose.yml beside them:

services:
  mobile-terminal:
    build: .
    container_name: mobile-terminal
    restart: unless-stopped
    ports:
      - "<tailscale-ip>:7681:7681"
    volumes:
      - /path/to/git:/home/dev/work
      - ./gitconfig:/home/dev/.gitconfig:ro
      - mobile-terminal-home:/home/dev

volumes:
  mobile-terminal-home:

The workspace mount gives the terminal your real repositories. The named volume keeps shell history and tool caches across rebuilds. Because that volume sits over the home directory, later edits to tmux.conf will not reach an existing container until you copy the file in or remove the volume. Mount credentials such as SSH keys read-only and only if you need them, and scope any token to the minimum permissions.

Build and start it:

cd /path/to/git/mobile-terminal
docker compose up -d --build
docker compose logs -f mobile-terminal

Step 4: Bind Securely to the Tailscale Network

The line that keeps this private is the port mapping. Binding to <tailscale-ip>:7681 publishes the port only on the host's tailnet address, not on the LAN interface and not on the public internet. Find the address on the host with:

tailscale ip -4

Paste that 100.x.y.z address into the Compose file in place of the placeholder. If you prefer a named HTTPS endpoint, you can instead bind to 127.0.0.1:7681 and let Tailscale Serve proxy it:

tailscale serve --bg 7681

Either way, do not map 7681 on 0.0.0.0 and do not forward it on your router. A web terminal is a shell, so treat it like one. Tailscale authentication is your first gate, and you can add a ttyd --credential user:password flag as a second one.

Step 5: Test Mobile Browser Ergonomics and Session Recovery

With the container running, open the Tailscale app on your phone and confirm it is connected. Then browse to http://<tailscale-ip>:7681 (or the Tailscale Serve URL).

Run a quick persistence test:

1. Start a long command, such as ping localhost or a test suite.

2. Lock your phone or switch to cellular and back.

3. Reopen the page.

You should land in the same tmux session with the command still running. Detach on purpose with Ctrl+b then d, and list sessions from the host with docker exec -it mobile-terminal tmux ls.

A few habits help on a touch keyboard. Turn off auto-correct for your browser keyboard if you can, use a Bluetooth keyboard for longer sessions, and keep commands short with shell aliases so you type less.

Hardware & Gear Used in This Guide

  • Homelab host: small Linux server running Debian 12 Bookworm with Docker Engine and the Compose plugin
  • Storage: NVMe SSD holding the workspace repositories
  • Network: 2.5GbE wired connection to the home network, with Tailscale providing remote access
  • Mobile client: iPhone or Android phone running the Tailscale app and a modern browser

What You Can Do Next

  • Put an authenticating reverse proxy in front for a second gate.
  • Build a custom tmux status line.
  • Install your favorite local AI command line assistants inside the container and run them from anywhere on your tailnet.

Later,
     SteveO