claude-code-ultimate-guide/tools/mobile-access.md

Claude Code Mobile Access

⚠️ STATUS: WIP / UNTESTED

This guide is a work in progress. The setup has not been fully tested across different environments. Use at your own risk. Contributions and feedback welcome.

---

The Problem

Claude Code CLI is a local interactive process, not a service with a session API. Each instance is autonomous. Even claude --remote only offloads execution—it doesn't create a relay system.

What's missing: A native claude --serve mode that exposes a WebSocket API, allows multiple clients, and maintains the same conversation context.

The workaround: Expose your terminal via web browser using ttyd, accessible from anywhere via Tailscale VPN.

---

Solution: ttyd + Tailscale

YOUR COMPUTER                     YOUR PHONE
┌─────────────────┐               ┌─────────────────┐
│  Claude Code    │◄──────────────│  Browser        │
│  (runs here)    │   Tailscale   │  (same session) │
│                 │   (VPN)       │                 │
└─────────────────┘               └─────────────────┘

• ttyd: Exposes your terminal in a web browser
• Tailscale: Free VPN that gives your computer a fixed IP, accessible from anywhere (4G, public WiFi, etc.)
• tmux: Keeps session alive even if you close the browser

Use case: Follow and continue Claude Code sessions from your phone (commuting, away from desk, etc.)

---

Why This Approach?

ToS Considerations

Some third-party wrappers (like OpenCode) have been blocked by Anthropic for ToS violations. This approach is ToS-safe because:

• You're using the official Claude Code CLI
• ttyd just exposes your terminal via browser (no wrapper)
• Tailscale is just a VPN for secure access
• No third-party client interacting with Claude's API

---

Prerequisites

• macOS or Linux
• Claude Code CLI installed and authenticated
• Tailscale account (free tier works)

---

Installation

Quick Setup Script

#!/bin/bash
# claude-mobile-setup.sh

set -e

echo "=== Setup Claude Code Mobile ==="

# 1. Install ttyd + tmux
echo "[1/2] Installing ttyd..."
if [[ "$OSTYPE" == "darwin"* ]]; then
    brew install ttyd tmux
else
    sudo apt install -y tmux
    sudo snap install ttyd --classic
fi

# 2. Install Tailscale
echo "[2/2] Installing Tailscale..."
if [[ "$OSTYPE" == "darwin"* ]]; then
    brew install tailscale
else
    curl -fsSL https://tailscale.com/install.sh | sh
fi

# 3. Create launcher script
mkdir -p ~/.local/bin
cat > ~/.local/bin/claude-mobile << 'EOF'
#!/bin/bash
PORT=7681
PASS="${CLAUDE_MOBILE_PASS:-claude123}"

TS_IP=$(tailscale ip -4 2>/dev/null || echo "not connected")

echo "══════════════════════════════════"
echo "  CLAUDE CODE MOBILE"
echo "══════════════════════════════════"
echo "  URL:  http://$TS_IP:$PORT"
echo "  User: claude"
echo "  Pass: $PASS"
echo "══════════════════════════════════"
echo ""
echo "Open this URL on your phone."
echo "Press Ctrl+C to stop."
echo ""

# Kill existing session if any
tmux kill-session -t cc 2>/dev/null || true

# Start Claude in tmux, expose via ttyd
tmux new-session -d -s cc 'claude'
exec ttyd -W -p $PORT -c "claude:$PASS" tmux attach -t cc
EOF

chmod +x ~/.local/bin/claude-mobile

# Add to PATH
if [[ ":$PATH:" != *":$HOME/.local/bin:"* ]]; then
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
fi

echo ""
echo "=== Installation Complete ==="
echo ""
echo "Next steps:"
echo "  1. Run: tailscale up"
echo "  2. Run: source ~/.zshrc"
echo "  3. Run: claude-mobile"
echo ""

Manual Installation

# macOS
brew install ttyd tmux tailscale

# Linux (Debian/Ubuntu)
sudo apt install -y tmux
sudo snap install ttyd --classic
curl -fsSL https://tailscale.com/install.sh | sh

---

Usage

First Time Setup

# 1. Connect to Tailscale (one-time)
tailscale up
# Follow the link to authenticate with Google/GitHub/etc.

# 2. Install Tailscale on your phone
# iOS: App Store → Tailscale
# Android: Play Store → Tailscale
# Login with same account

# 3. Start Claude Code Mobile
claude-mobile

Output

══════════════════════════════════
  CLAUDE CODE MOBILE
══════════════════════════════════
  URL:  http://100.78.42.15:7681
  User: claude
  Pass: claude123
══════════════════════════════════

On Your Phone

1. Open Safari/Chrome
2. Go to http://100.78.42.15:7681 (use your actual Tailscale IP)
3. Login with claude / claude123
4. You now have Claude Code in your browser

---

Configuration

Change Password

export CLAUDE_MOBILE_PASS="your-secure-password"
claude-mobile

Or add to your shell config:

echo 'export CLAUDE_MOBILE_PASS="your-secure-password"' >> ~/.zshrc

Change Port

Edit ~/.local/bin/claude-mobile and change PORT=7681 to your preferred port.

---

Security

Layer	Protection
Network	Tailscale uses WireGuard encryption
Authentication	Basic auth (username:password) via ttyd
Access	Only accessible from your Tailscale network

Recommendations:

• Use a strong password (not the default claude123)
• Don't expose ttyd directly to the internet without Tailscale
• Keep Tailscale client updated on all devices

---

Troubleshooting

"not connected" instead of IP

# Check Tailscale status
tailscale status

# If disconnected, reconnect
tailscale up

Can't access from phone

1. Ensure Tailscale app is installed on phone and connected to same account
2. Check firewall isn't blocking port 7681
3. Try accessing locally first: http://localhost:7681

Session not persisting

The tmux session should persist. To manually reattach:

tmux attach -t cc

ttyd command not found

# macOS
brew reinstall ttyd

# Linux
sudo snap install ttyd --classic

---

Alternatives Considered

Solution	Pros	Cons	ToS Risk
ttyd + Tailscale ✅	Simple, no wrapper, ToS-safe	Terminal UX on mobile	✅ Safe
Happy Coder (7.1K ⭐)	Native apps, polished	Wraps CLI	⚠️ Unknown
Claude Code Web (5.5K ⭐)	Rich UI	Wraps CLI	⚠️ Unknown
tmux + SSH	Zero deps	Needs SSH client on phone	✅ Safe

We chose ttyd + Tailscale because:

• It's just your terminal exposed via browser
• No third-party wrapper around Claude Code
• Zero ToS risk—you're using the official CLI

---

Related Resources

• ttyd GitHub - Terminal web server
• Tailscale - Zero-config VPN
• ttyd + Claude Code Guide - Community tutorial
• VPS Setup Guide - Alternative: run on VPS

---

Contributing

This doc is WIP/UNTESTED. If you test this setup, please share:

• Your OS/environment
• Any issues encountered
• Suggested improvements

Open an issue or PR on this repo.

---

Last updated: January 2026 | Status: WIP/UNTESTED