# Remote Claude Code Terminal Access: Check on Your AI Agent from Anywhere ## Introduction You start a Claude Code session, give it a big task, and then you need to leave your desk. With the right setup, you can check on it — or start a new session — from any browser, anywhere in the world, without SSH keys or VPN. This guide walks you through building a permanent remote terminal pipeline using **tmux** (session persistence), **ttyd** (browser-based terminal), and **Cloudflare Tunnel** (free, secure public URL). It works on Linux, macOS, and Windows (WSL2), across every major terminal app. **What you'll build:** ``` Claude Code → tmux session (persists on your machine) → ttyd (serves it as a web terminal) → Cloudflare Tunnel (permanent public URL, no open ports) → your-domain.com/terminal (access from any browser) ``` ## Prerequisites - A domain name managed on Cloudflare (free plan works) - A machine that stays on (desktop, laptop that sleeps but doesn't shut off, or a VPS) - Basic terminal comfort --- ## Module 1: tmux — Persistent Sessions ### Lesson 1: What tmux Does and Why It Matters tmux is a terminal multiplexer. The key insight: **your shell session lives inside tmux, not inside your terminal app.** When you close the terminal app, the tmux session keeps running. When you reconnect — from any terminal, anywhere — the session is exactly where you left it. For Claude Code, this means: - Start a long task, close your laptop, come back hours later — Claude is still going - Attach to the same session from your phone browser, a coffee shop laptop, or a remote machine - Multiple people can observe the same running session ### Lesson 2: Install tmux ```bash # Ubuntu / Debian / Pop!_OS sudo apt install tmux # macOS brew install tmux # Fedora / RHEL / Rocky sudo dnf install tmux # Arch sudo pacman -S tmux # Windows: install WSL2 first, then run the Ubuntu command above ``` Verify: `tmux -V` should print `tmux 3.x` ### Lesson 3: Core Commands ```bash # Create a named session tmux new-session -s claude # Detach from session (session keeps running) # Press: Ctrl+B, then D # List running sessions tmux ls # Re-attach to a session tmux attach-session -t claude # Kill a session tmux kill-session -t claude ``` The session name `claude` is arbitrary — you can use any name. ### Lesson 4: Terminal App Gotchas **Warp Terminal** is itself powered by tmux internally. Trying to create a tmux session inside Warp will fail with: ``` sessions should be nested with care, unset $TMUX to force ``` Fix: clear the `TMUX` variable for that command only: ```bash TMUX= tmux new-session -s claude TMUX= tmux attach-session -t claude ``` **Konsole / GNOME Terminal on KDE Plasma** — same issue if your desktop environment wraps terminals in a tmux session. Use `TMUX=` prefix. **iTerm2 / Terminal.app (macOS)** — no issues, works natively. **Windows Terminal + WSL2** — run all commands inside the WSL2 shell, not in PowerShell. ### Lesson 5: Convenience Aliases Add these to your `~/.zshrc` or `~/.bashrc`: ```bash # Start or attach to Claude Code tmux session function cn { if TMUX= tmux has-session -t claude 2>/dev/null; then TMUX= tmux attach-session -t claude else TMUX= tmux new-session -s claude -c ~/Projects/your-project \ /path/to/claude --dangerously-skip-permissions fi } # Kill the session alias kill-cn='tmux kill-session -t claude' ``` Replace `/path/to/claude` with the output of `which claude`. Replace `~/Projects/your-project` with your project directory. Reload: `source ~/.zshrc` --- ## Module 2: ttyd — Browser-Based Terminal ### Lesson 1: What ttyd Does ttyd is a small C program that serves a terminal over HTTP/WebSocket. Open the URL in any browser and you get a full interactive terminal — keyboard input, colors, scrollback, everything. It uses xterm.js, the same renderer that powers VS Code's terminal. You'll run ttyd pointed at your tmux session. The browser connects to ttyd, ttyd connects to tmux, so every browser visitor sees the same live session. ### Lesson 2: Install ttyd ```bash # Ubuntu / Debian sudo apt install ttyd # macOS brew install ttyd # Fedora sudo dnf install ttyd # Manual (any Linux) sudo curl -L https://github.com/tsl0922/ttyd/releases/latest/download/ttyd.x86_64 \ -o /usr/local/bin/ttyd && sudo chmod +x /usr/local/bin/ttyd # Windows WSL2: use the Ubuntu command above inside WSL ``` Verify: `ttyd --version` ### Lesson 3: Test It ```bash # Start ttyd pointing at your tmux session (port 7681) ttyd -p 7681 tmux new-session -A -s claude # Open http://localhost:7681 in your browser ``` You should see a terminal. Anything you type appears in the tmux session. ### Lesson 4: Security — Two-Port Strategy **Never expose an unauthenticated terminal to the public internet.** The recommended setup uses two ttyd instances: **Port 7682 — loopback only, no auth** (for your admin panel iframe on localhost): ```bash ttyd --port 7682 --interface lo --writable tmux new-session -A -s claude ``` **Port 7681 — authenticated, exposed via Cloudflare** (for remote access): ```bash ttyd --port 7681 -c happy:your-password --writable tmux new-session -A -s claude ``` The `-c user:pass` flag enables HTTP Basic Auth. Cloudflare provides HTTPS so credentials travel encrypted. ### Lesson 5: Limit to One Active Client By default, multiple browser tabs can connect simultaneously and fight over terminal size. Add `-m 1` to allow only one active resize controller: ```bash ttyd -p 7681 -m 1 -c happy:your-password tmux new-session -A -s claude ``` --- ## Module 3: Cloudflare Tunnel — Permanent Public URL ### Lesson 1: Why Cloudflare Tunnel Three alternatives exist for exposing a local service publicly: | | Cloudflare Tunnel | ngrok | Tailscale | |---|---|---|---| | **Cost** | Free (up to 50 users) | Free tier limited | Free (up to 100 devices) | | **Custom domain** | Yes (your own domain) | Paid only | Via Funnel (limited) | | **Permanent URL** | Yes | Paid only | N/A | | **Open ports needed** | None | None | None | | **Access control** | CF Access (SSO, IP rules) | Basic auth | ACLs | | **Best for** | Production public access | Quick dev sharing | Private team access | For a permanent terminal URL on your own domain, Cloudflare Tunnel is the best free option. ### Lesson 2: Install cloudflared ```bash # macOS brew install cloudflare/cloudflare/cloudflared # Ubuntu / Debian curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb \ -o cloudflared.deb && sudo dpkg -i cloudflared.deb # Fedora / RHEL sudo dnf install cloudflared # Arch sudo pacman -S cloudflared # Windows (PowerShell) winget install Cloudflare.cloudflared # Then use from WSL2 or PowerShell ``` ### Lesson 3: Create a Named Tunnel ```bash # Authenticate (opens browser to Cloudflare login) cloudflared tunnel login # Create the tunnel — gives you a UUID cloudflared tunnel create terminal # Route your subdomain to this tunnel cloudflared tunnel route dns terminal terminal.yourdomain.com ``` This creates a CNAME record in your Cloudflare DNS pointing `terminal.yourdomain.com` → your tunnel UUID. ### Lesson 4: Configure the Tunnel Create `~/.cloudflared/terminal-config.yml`: ```yaml tunnel: YOUR-TUNNEL-UUID-HERE credentials-file: /home/YOUR-USERNAME/.cloudflared/YOUR-TUNNEL-UUID.json ingress: - hostname: terminal.yourdomain.com service: http://localhost:7681 originRequest: noTLSVerify: true connectTimeout: 30s - service: http_status:404 ``` Test it: ```bash cloudflared tunnel --config ~/.cloudflared/terminal-config.yml run terminal ``` Open `https://terminal.yourdomain.com` — you should see the ttyd login prompt. --- ## Module 4: Auto-Start Everything ### Lesson 1: Linux — systemd User Services systemd user services start automatically when you log in, without needing root. **ttyd service** — `~/.config/systemd/user/claude-web.service`: ```ini [Unit] Description=Claude Web Terminal (ttyd) After=network.target [Service] Type=simple Environment=HOME=/home/YOUR-USERNAME Environment=PATH=/home/YOUR-USERNAME/.local/bin:/usr/local/bin:/usr/bin:/bin Environment=TERM=xterm-256color ExecStart=/usr/bin/ttyd --port 7681 -c happy:your-password --writable /usr/bin/tmux new-session -A -s claude Restart=always RestartSec=5 [Install] WantedBy=default.target ``` **Cloudflare tunnel service** — `~/.config/systemd/user/cloudflared-terminal.service`: ```ini [Unit] Description=Cloudflare Tunnel - Terminal After=network-online.target [Service] Type=simple ExecStart=/usr/bin/cloudflared tunnel --config /home/YOUR-USERNAME/.cloudflared/terminal-config.yml run Restart=always RestartSec=10 [Install] WantedBy=default.target ``` **Claude Code session service** — `~/.config/systemd/user/claude-session.service`: First create a launcher script at `~/.local/bin/start-claude-session.sh`: ```bash #!/bin/bash export HOME=/home/YOUR-USERNAME export PATH=/home/YOUR-USERNAME/.local/bin:/usr/local/bin:/usr/bin:/bin export TERM=xterm-256color tmux kill-session -t claude 2>/dev/null || true tmux new-session -d -s claude -c /home/YOUR-USERNAME/Projects/your-project \; \ send-keys "claude --dangerously-skip-permissions" Enter ``` ```bash chmod +x ~/.local/bin/start-claude-session.sh ``` Then the service: ```ini [Unit] Description=Claude Code tmux session After=network.target [Service] Type=forking ExecStart=/home/YOUR-USERNAME/.local/bin/start-claude-session.sh ExecStop=/usr/bin/tmux kill-session -t claude Restart=on-failure RestartSec=10 [Install] WantedBy=default.target ``` **Enable all three:** ```bash systemctl --user daemon-reload systemctl --user enable --now claude-web.service systemctl --user enable --now cloudflared-terminal.service systemctl --user enable --now claude-session.service ``` **Check status:** ```bash systemctl --user status claude-web.service systemctl --user status cloudflared-terminal.service systemctl --user status claude-session.service ``` ### Lesson 2: macOS — launchd Agents Create `~/Library/LaunchAgents/com.user.ttyd.plist`: ```xml Label com.user.ttyd ProgramArguments /usr/local/bin/ttyd -p 7681 -c youruser:yourpassword --writable /usr/local/bin/tmux new-session -A -s claude RunAtLoad KeepAlive StandardOutPath /tmp/ttyd.log StandardErrorPath /tmp/ttyd-error.log ``` Create `~/Library/LaunchAgents/com.cloudflare.tunnel.plist`: ```xml Label com.cloudflare.tunnel ProgramArguments /usr/local/bin/cloudflared tunnel --config /Users/YOUR-USERNAME/.cloudflared/terminal-config.yml run RunAtLoad KeepAlive ``` Load both: ```bash launchctl load ~/Library/LaunchAgents/com.user.ttyd.plist launchctl load ~/Library/LaunchAgents/com.cloudflare.tunnel.plist ``` ### Lesson 3: Windows (WSL2) — Task Scheduler The cleanest approach on Windows is to run ttyd and cloudflared inside WSL2 and have Windows Task Scheduler launch WSL2 at startup. **Step 1:** In WSL2, install tmux, ttyd, and cloudflared (see earlier modules). **Step 2:** Create `~/start-terminal-services.sh` in WSL2: ```bash #!/bin/bash export PATH=/home/YOUR-USERNAME/.local/bin:/usr/local/bin:/usr/bin:/bin # Start tmux session with claude tmux kill-session -t claude 2>/dev/null || true tmux new-session -d -s claude -c ~/Projects/your-project tmux send-keys -t claude "claude --dangerously-skip-permissions" Enter # Start ttyd pkill ttyd 2>/dev/null || true nohup ttyd -p 7681 -c user:password --writable tmux new-session -A -s claude \ > /tmp/ttyd.log 2>&1 & # Start cloudflared pkill cloudflared 2>/dev/null || true nohup cloudflared tunnel --config ~/.cloudflared/terminal-config.yml run \ > /tmp/cloudflared.log 2>&1 & ``` ```bash chmod +x ~/start-terminal-services.sh ``` **Step 3:** Open Task Scheduler (taskschd.msc) and create a new task: - **Trigger:** At startup - **Action:** Start a program - Program: `C:\Windows\System32\wsl.exe` - Arguments: `-u YOUR-USERNAME /home/YOUR-USERNAME/start-terminal-services.sh` - **Conditions:** Uncheck "Start only if on AC power" - **Settings:** Check "Run task as soon as possible after scheduled start is missed" --- ## Module 5: Browser Access ### Lesson 1: First-Time Login Navigate to `https://terminal.yourdomain.com`. Your browser will show an HTTP Basic Auth prompt: - **Username:** the username you set in `ttyd -c username:password` - **Password:** the password you set Check "Remember password" or "Save credentials" — the browser stores this and will auto-authenticate on every future visit. ### Lesson 2: What You'll See ttyd renders your terminal in the browser using WebGL2 (xterm.js). You get: - Full color support (256 colors, true color) - Keyboard input including Ctrl+C, Ctrl+Z, arrow keys - Scrollback history - Clipboard (with browser permission) - Responsive resize If you attached to a running tmux session, you'll see whatever was already running there — including an active Claude Code session mid-task. ### Lesson 3: Multiple Devices Open `https://terminal.yourdomain.com` on your phone. You see the same session. Type something — it appears in every connected browser and in your local terminal simultaneously. This is tmux's multiplexing at work: one session, infinite views. --- ## Module 6: Troubleshooting ### "Sessions should be nested" error You're running a terminal that's already inside tmux. Fix: ```bash TMUX= tmux new-session -s claude ``` ### Terminal shows blank/unresponsive in browser Check ttyd is running: `systemctl --user status claude-web.service` Check the tmux session exists: `tmux ls` Restart: `systemctl --user restart claude-web.service` ### Cloudflare tunnel shows offline Check the tunnel: `systemctl --user status cloudflared-terminal.service` Verify the tunnel config: `cloudflared tunnel ingress validate --config ~/.cloudflared/terminal-config.yml` Check Cloudflare dashboard → Zero Trust → Access → Tunnels — your tunnel should show "Healthy." ### Claude not running in the session Attach locally: `tmux attach-session -t claude` You'll see what's actually in the session. Claude may have exited or be waiting for input. ### PATH issues in auto-start If `claude: command not found` in the service, add the full path. Find it with `which claude` and use the absolute path in your service file. ### macOS services not loading after reboot macOS requires user login for LaunchAgents to start (not just boot). They'll start as soon as you log into your desktop. For true boot-time start (before login), use LaunchDaemons in `/Library/LaunchDaemons/` — but this requires root and extra security consideration for a terminal. --- ## Summary You now have: 1. **tmux** keeping your Claude Code session alive regardless of terminal app or connection 2. **ttyd** serving that session as a browser-accessible terminal 3. **Cloudflare Tunnel** providing a permanent HTTPS URL with no open firewall ports 4. **Auto-start** so everything comes up when your machine boots — no manual steps The permanent URL costs nothing extra if you already have a Cloudflare domain. The entire stack runs on hardware you already own. **Daily workflow:** - At home: use your normal terminal app (`c` / `cc` aliases for direct Claude Code) - Long task before leaving: `cn` to start a tracked session, then check `terminal.yourdomain.com` from anywhere - Away: open the URL, see exactly where Claude left off, respond to any prompts, start new tasks