<div align="center">

🏛️ ClaudePantheon

A temple for your persistent Claude Code sessions

Run Claude Code anywhere. Remember everything. Access from any browser.

Quick Start • Configuration • Architecture • Commands • Troubleshooting

</div>

---

🎯 What is ClaudePantheon?

ClaudePantheon gives you a persistent, always-on Claude Code environment that you can access from any device with a web browser. Unlike running Claude Code locally, your sessions, context, and workspace persist across restarts — Claude remembers your projects, preferences, and ongoing work.

The name is inspired by the show Pantheon (based on Ken Liu's short stories), where consciousness is uploaded into a persistent digital environment. ClaudePantheon applies that concept to Claude Code — a temple where your AI assistant lives permanently, remembers everything, and is always available.

╔═══════════════════════════════════════════════════════════╗
║                    ClaudePantheon                         ║
║              A RandomSynergy Production                   ║
╚═══════════════════════════════════════════════════════════╝

---

💡 Use Cases

<table> <tr> <td width="50%">

🏠 Home Server / NAS

Run Claude Code on your home server and access it from your laptop, tablet, or phone. Your AI assistant is always available on your local network.

🖥️ Remote Development

SSH tunnel or reverse proxy to your ClaudePantheon instance from anywhere. Perfect for developers who work across multiple machines.

🏢 Team Workstation

Deploy shared instances for your team. Each developer gets their own persistent Claude environment without local setup.

</td> <td width="50%">

🔧 DevOps & Automation

Let Claude manage your infrastructure. Connect MCP servers for GitHub, databases, Home Assistant, and more — all persisted between sessions.

📱 Mobile Access

Access your AI coding assistant from a tablet or phone browser when you're away from your main workstation.

🧪 Experimentation

Spin up isolated environments to test new workflows, MCP integrations, or Claude configurations without affecting your main setup.

</td> </tr> </table>

---

✨ Features

<table> <tr> <td>

🔄 Persistent Everything

• Session continuity — Claude remembers your conversations
• Workspace files — Your code stays between restarts
• MCP connections — Integrations persist across sessions
• Shell history — Command history saved permanently

</td> <td>

🌐 Access Anywhere

• Web terminal — Full terminal via any browser
• No client install — Just open a URL
• Mobile friendly — Works on tablets and phones
• Landing page — Professional entry point with quick access

</td> </tr> <tr> <td>

⚡ Developer Experience

• Oh My Zsh — Beautiful shell with plugins
• Simple aliases — cc to start, cc-new for fresh session
• Custom packages — Add tools without rebuilding
• User mapping — Seamless host file permissions

</td> <td>

🔌 Extensible

• MCP ready — GitHub, Postgres, Home Assistant, more
• Host mounts — Access any directory on the host
• Customizable webroot — Add custom PHP apps
• WebDAV support — Mount as network drive

</td> </tr> </table>

At a Glance

| Feature | Description | |---------|-------------| | 🏔️ Alpine-Based | Minimal base image, fast startup | | 🔄 Persistent Sessions | All conversations continue where you left off | | 🌐 Single Port | All services via one port (nginx reverse proxy) | | 🏠 Landing Page | Customizable PHP landing page with quick access buttons | | 📁 FileBrowser | Web-based file management built-in | | 🔗 WebDAV | Mount workspace as network drive (optional) | | 🐚 Oh My Zsh | Beautiful shell with syntax highlighting & autosuggestions | | 🔌 MCP Ready | Pre-configured for Model Context Protocol integrations | | 📦 Custom Packages | Install Alpine packages without rebuilding | | 👤 User Mapping | Configurable UID/GID for permission-free bind mounts | | 🔐 Two-Zone Auth | Separate credentials for landing page vs services | | 🌐 Remote Mounts | rclone: S3, Google Drive, SFTP, SMB, WebDAV, FTP, 50+ backends |

---

📋 Prerequisites

• Docker (20.10+) and Docker Compose (v2)
• An Anthropic API key or the ability to run claude auth login for browser-based auth
• ~500MB disk space for the image, plus space for your data

---

🚀 Quick Start

Option 1: Pull from GHCR (recommended)

git clone https://github.com/RandomSynergy17/ClaudePantheon.git
cd ClaudePantheon/docker

cp .env.example .env
# Edit .env — at minimum set CLAUDE_DATA_PATH and PUID/PGID

docker compose pull
docker compose up -d

Option 2: Build from source

cd ClaudePantheon/docker

cp .env.example .env
# Edit .env — at minimum set CLAUDE_DATA_PATH and PUID/PGID

make build
make up

Open http://localhost:7681 — you'll see the landing page with Terminal, Files, and PHP Info buttons. Click Terminal, complete the setup wizard, then type cc to start.

---

🏗️ Architecture

All services accessible via a single port through an nginx reverse proxy:

┌─────────────────────────────────────────────────────────────┐
│                    Browser (Port 7681)                       │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│                       nginx                                  │
│                  (Reverse Proxy)                             │
│                                                              │
│   /              → Landing Page (PHP)                        │
│   /terminal/     → ttyd (Claude Code)                        │
│   /files/        → FileBrowser Quantum                       │
│   /webdav/       → nginx WebDAV (optional)                   │
│     workspace/   webroot/   scripts/   logs/                 │
└─────────────────────────────────────────────────────────────┘

Ports

| Port | Service | Notes | |------|---------|-------| | 7681 | nginx reverse proxy | All web services (/, /terminal/, /files/, /webdav/) | | 2222 | SSH server | Optional, requires ENABLE_SSH=true in .env |

Startup Flow

On container start, the entrypoint script runs through this sequence:

1. Validate data directory exists and is writable, check disk space (100MB minimum)
2. Map user — adjusts container UID/GID to match PUID/PGID from .env
3. Initialize data — creates directory structure under $CLAUDE_DATA_PATH on first run
4. Copy defaults — scripts, nginx config, and webroot are copied from the image into the data volume only if they don't already exist (preserves your customizations)
5. Install packages — reads custom-packages.txt and installs via apk
6. Fix permissions — sets ownership and SSH key permissions
7. Start services — launches nginx, php-fpm, FileBrowser (if enabled), and ttyd

Startup Validation

The entrypoint performs safety checks before proceeding:

• Data directory writable — fails fast if the volume mount is broken
• Disk space — requires 100MB free minimum
• Loop detection — prevents infinite redirect if custom entrypoint is misconfigured
• Package name validation — only alphanumeric, dash, underscore, dot allowed in custom-packages.txt

---

⚙️ Configuration

All configuration is done through docker/.env (copy from .env.example). Changes require make restart unless noted otherwise.

.env Variable Reference

Data & User

| Variable | Default | Description | |----------|---------|-------------| | CLAUDE_DATA_PATH | /docker/appdata/claudepantheon | Host path for all persistent data | | PUID | 1000 | Container user ID (run id -u on host) | | PGID | 1000 | Container group ID (run id -g on host) |

Claude Code

| Variable | Default | Description | |----------|---------|-------------| | ANTHROPIC_API_KEY | (empty) | Claude API key. Alternatively, run claude auth login inside the container | | CLAUDE_BYPASS_PERMISSIONS | false | Skip permission prompts. Also toggleable at runtime with cc-bypass on\|off |

Authentication (Two-Zone System)

| Variable | Default | Description | |----------|---------|-------------| | INTERNAL_AUTH | false | Enable auth for /terminal/, /files/, /webdav/ | | INTERNAL_CREDENTIAL | (empty) | Credentials as user:password | | WEBROOT_AUTH | false | Enable auth for / (landing page) | | WEBROOT_CREDENTIAL | (empty) | Webroot credentials. Falls back to INTERNAL_CREDENTIAL if unset | | TTYD_CREDENTIAL | (empty) | Deprecated. Backward compatibility alias for INTERNAL_CREDENTIAL |

Feature Toggles

| Variable | Default | Description | |----------|---------|-------------| | ENABLE_FILEBROWSER | true | Web file manager at /files/ | | ENABLE_WEBDAV | false | WebDAV endpoint at /webdav/ | | ENABLE_RCLONE | false | rclone remote mounts (requires FUSE in docker-compose.yml) | | ENABLE_SSH | (empty) | Set to exactly true to enable SSH on port 2222 (pubkey auth only) | | LOG_TO_FILE | false | Write logs to $CLAUDE_DATA_PATH/logs/claudepantheon.log. Auto-rotates at 10MB |

System

| Variable | De