v1.2.0

Author: CoderLuii

.github/SECURITY.md

@@ -39,6 +39,17 @@ The container has unrestricted outbound network access. This is required for:
 - Git operations (clone, push, pull)
 - Any web requests Claude Code makes during development tasks
 
+## Exposing HolyClaude to the Internet
+
+**Do not port-forward HolyClaude to the public internet.** CloudCLI exposes a full shell and holds your AI provider credentials. A simple password is not sufficient protection — basic auth gets brute-forced, and one compromise means an attacker has arbitrary code execution, access to your workspace, and a paid Claude Code instance running on your credentials.
+
+If you need to reach HolyClaude from outside your local network, use:
+
+- **[Tailscale](https://tailscale.com)** — WireGuard mesh VPN, zero open ports, identity-based auth. Recommended for personal and small-team use.
+- **[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)** — Outbound-only tunnel to Cloudflare's edge, optional Cloudflare Access SSO in front. Recommended when you need a public hostname or shared access.
+
+Both options are free for personal use, encrypt the connection end-to-end, and never require opening a port on your router. See the [Remote Access & Exposure](../README.md#shield-remote-access--exposure) section of the README for full details.
+
 ## Reporting a Vulnerability
 
 If you discover a security vulnerability in HolyClaude:

README.md

@@ -78,6 +78,7 @@ Your existing Anthropic account works directly:
 | :file_folder: | [Project Structure](#file_folder-project-structure) |
 | :floppy_disk: | [Data & Persistence](#floppy_disk-data--persistence) |
 | :lock: | [Permissions](#lock-permissions) |
+| :shield: | [Remote Access & Exposure](#shield-remote-access--exposure) |
 | :bell: | [Notifications](#bell-notifications) |
 | :arrows_counterclockwise: | [Upgrading](#arrows_counterclockwise-upgrading) |
 | :construction: | [Troubleshooting](#construction-troubleshooting) |
@@ -125,6 +126,8 @@ http://localhost:3001
 
 > No `.env` files. No pre-configuration. No reading 40 pages of docs before you can start. It just runs.
 
+> **Want to reach it from outside your network?** Don't port-forward it. See [Remote Access & Exposure](#shield-remote-access--exposure) — use Tailscale or Cloudflare Tunnel instead.
+
 <p align="right">
   <a href="#top">↑ back to top</a>
 </p>
@@ -734,18 +737,19 @@ holyclaude/
 | What | Where (container) | Where (host) | Survives rebuild? |
 |------|-------------------|-------------|-------------------|
 | Settings, credentials, API keys | `/home/claude/.claude` | `./data/claude` | **Yes** |
+| Claude Code session (OAuth, onboarding) | `/home/claude/.claude.json` | `./data/claude/.claude.json.persist` | **Yes** |
 | Your code and projects | `/workspace` | `./workspace` | **Yes** |
-| CloudCLI account | `/home/claude/.cloudcli` | *(container only)* | No |
-| Onboarding state | `/home/claude/.claude.json` | *(container only)* | No |
+| CloudCLI account | `/home/claude/.cloudcli` | *(container only by default — see below)* | No (opt-in available) |
 
 ### What survives `docker compose down && docker compose up`:
 - Your Anthropic authentication and API keys
-- Claude Code settings and memory (`CLAUDE.md`)
+- Claude Code settings, memory (`CLAUDE.md`), and OAuth session (no re-login)
 - All your code in `./workspace`
 - Git configuration
+- Codex, Gemini, and Cursor CLI auth (since v1.1.7)
 
 ### What you'll redo (10 seconds):
-- CloudCLI web account — quick signup, that's it
+- CloudCLI web account — quick signup, that's it (unless you opt into persistence below)
 
 ### Re-triggering first-boot setup:
 ```bash
@@ -756,6 +760,28 @@ docker compose restart holyclaude
 
 > **Never delete `./data/claude/` entirely.** That's where your credentials live. Delete the sentinel file if you want a fresh bootstrap. Delete specific config files if you want to reset settings. But never nuke the whole folder.
 
+### Persisting the CloudCLI account (optional, local storage only)
+
+By default, the CloudCLI account database (`~/.cloudcli`) is container-local and gets wiped on rebuild. Re-creating the account takes 10 seconds, so most people leave it as-is.
+
+If you want it to survive rebuilds, add a **named Docker volume** to your compose file:
+
+```yaml
+services:
+  holyclaude:
+    volumes:
+      - ./data/claude:/home/claude/.claude
+      - ./workspace:/workspace
+      - cloudcli-data:/home/claude/.cloudcli   # add this line
+
+volumes:
+  cloudcli-data:                                # and this block
+```
+
+> **Do NOT bind-mount `./data/cloudcli` on a network share (NAS, SMB/CIFS, NFS).** CloudCLI stores its account in SQLite, and SQLite's file locking breaks on network mounts. You'll hit `database is locked` errors constantly. Named volumes live on the Docker engine's local filesystem, which is why this works — bind mounts pointing at a NAS will not.
+
+A bind mount to a local SSD path is fine too, just keep it off any network share.
+
 <p align="right">
   <a href="#top">↑ back to top</a>
 </p>
@@ -793,6 +819,57 @@ This is how I personally run it. Edit `./data/claude/settings.json` on your host
 
 ---
 
+## :shield: Remote Access & Exposure
+
+HolyClaude binds CloudCLI to port `3001`. By default that's local-only — fine for running on your laptop or a home server you SSH into.
+
+**The moment you want to reach it from outside your network, read this section.**
+
+### Don't port-forward it to the public internet
+
+I'll say it flat out: do not punch a hole in your router and expose `3001` to the open internet. Not even with a password. Here's why:
+
+- CloudCLI exposes a full shell through the web terminal plugin
+- It can run arbitrary code, install packages, and read/write your entire `/workspace`
+- It holds your Anthropic OAuth tokens and API keys
+- Basic auth / app-level passwords get brute-forced, credential-stuffed, and scraped out of logs
+- One leaked password = someone else has a paid Claude Code instance running on your box with your money
+
+A password is a speed bump, not a door. Treat HolyClaude like you'd treat an SSH session: never on the open internet without a proper tunnel in front of it.
+
+### Use a proper tunnel instead
+
+These are the two options I actually recommend:
+
+| Option | Who it's for | Why |
+|--------|-------------|-----|
+| **[Tailscale](https://tailscale.com)** | Personal use, small teams | WireGuard mesh VPN. Install Tailscale on your server + your laptop/phone, and you reach `http://holyclaude:3001` from anywhere as if you were on the LAN. No ports opened, no DNS, no certs. Free for personal use. |
+| **[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)** | Sharing with others, public hostname | Cloudflare proxies the connection, so port `3001` stays closed. You get a real domain with HTTPS, and you can put Cloudflare Access (Google/GitHub SSO) in front of it. Free tier covers most personal use. |
+
+Both give you:
+- Zero open ports on your router
+- Encrypted transport end to end
+- Real identity-based auth (not a shared password)
+- Audit logs
+
+### If you insist on exposing it directly (please don't)
+
+If you absolutely have to skip the tunnel (self-hosting tutorial, isolated lab network, whatever), at the very minimum:
+
+1. **Put a reverse proxy in front of it** (Caddy, nginx, Traefik) with real TLS
+2. **Add IP allowlisting** at the firewall or proxy level — only your known IPs
+3. **Enable `bypassPermissions: false`** (the default) so shell commands still prompt
+4. **Rotate your Anthropic credentials** if anything looks off
+5. **Run behind Cloudflare Access or similar SSO**, not basic auth
+
+Even with all that, the risk surface is huge. Use Tailscale or Cloudflare Tunnel. They're free, they take five minutes to set up, and they're what I personally use.
+
+<p align="right">
+  <a href="#top">↑ back to top</a>
+</p>
+
+---
+
 ## :bell: Notifications
 
 Walk away from your computer and know when your AI agents are done. Claude Code, Codex, and Gemini CLI all send notifications when a task completes. Uses [Apprise](https://github.com/caronc/apprise) — supports 100+ services including Discord, Telegram, Slack, Email, Pushover, Gotify, and more.

docs/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to HolyClaude will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.2.0] - 04/09/2026
+
+### Added
+- Remote access security guidance recommending Tailscale or Cloudflare Tunnel instead of exposing HolyClaude directly to the public internet
+- Optional CloudCLI account persistence documentation using a named Docker volume for local storage users
+
+### Fixed
+- Corrected persistence docs to reflect that Claude Code OAuth session (`~/.claude.json`) already survives container rebuilds
+- Synced translated READMEs and troubleshooting docs with the current persistence behavior
+
 ## [1.1.9] - 04/04/2026
 
 ### Fixed

docs/translations/README.de.md

@@ -78,6 +78,7 @@ Dein bestehendes Anthropic-Konto funktioniert direkt:
 | :file_folder: | [Projektstruktur](#file_folder-project-structure) |
 | :floppy_disk: | [Daten & Persistenz](#floppy_disk-data--persistence) |
 | :lock: | [Berechtigungen](#lock-permissions) |
+| :shield: | [Fernzugriff & Exposition](#shield-remote-access--exposure) |
 | :bell: | [Benachrichtigungen](#bell-notifications) |
 | :arrows_counterclockwise: | [Aktualisieren](#arrows_counterclockwise-upgrading) |
 | :construction: | [Fehlerbehebung](#construction-troubleshooting) |
@@ -125,6 +126,8 @@ http://localhost:3001
 
 > Keine `.env`-Dateien. Keine Vorkonfiguration. Kein Lesen von 40 Seiten Dokumentation, bevor du anfangen kannst. Es läuft einfach.
 
+> **Willst du von außerhalb deines Netzwerks darauf zugreifen?** Kein Port-Forwarding. Sieh [Fernzugriff & Exposition](#shield-remote-access--exposure) — nutze stattdessen Tailscale oder Cloudflare Tunnel.
+
 <p align="right">
   <a href="#top">↑ nach oben</a>
 </p>
@@ -734,18 +737,19 @@ holyclaude/
 | Was | Wo (Container) | Wo (Host) | Überlebt Rebuild? |
 |------|-------------------|-------------|-------------------|
 | Einstellungen, Zugangsdaten, API-Keys | `/home/claude/.claude` | `./data/claude` | **Ja** |
+| Claude Code Session (OAuth, Onboarding) | `/home/claude/.claude.json` | `./data/claude/.claude.json.persist` | **Ja** |
 | Dein Code und deine Projekte | `/workspace` | `./workspace` | **Ja** |
-| CloudCLI-Konto | `/home/claude/.cloudcli` | *(nur Container)* | Nein |
-| Onboarding-Status | `/home/claude/.claude.json` | *(nur Container)* | Nein |
+| CloudCLI-Konto | `/home/claude/.cloudcli` | *(standardmäßig nur Container — siehe unten)* | Nein (Opt-in verfügbar) |
 
 ### Was `docker compose down && docker compose up` überlebt:
 - Deine Anthropic-Authentifizierung und API-Keys
-- Claude Code-Einstellungen und Memory (`CLAUDE.md`)
+- Claude Code-Einstellungen, Memory (`CLAUDE.md`) und OAuth-Session (kein erneutes Login)
 - Dein gesamter Code in `./workspace`
 - Git-Konfiguration
+- Codex-, Gemini- und Cursor-CLI-Auth (seit v1.1.7)
 
 ### Was du wiederholen musst (10 Sekunden):
-- CloudCLI-Web-Konto — schnelle Anmeldung, das war's
+- CloudCLI-Web-Konto — schnelle Anmeldung, das war's (außer du aktivierst die Persistenz unten)
 
 ### Ersten-Start-Setup erneut auslösen:
 ```bash
@@ -756,6 +760,28 @@ docker compose restart holyclaude
 
 > **Lösche niemals `./data/claude/` vollständig.** Dort leben deine Zugangsdaten. Lösche die Sentinel-Datei, wenn du einen frischen Bootstrap willst. Lösche bestimmte Konfigurationsdateien, wenn du Einstellungen zurücksetzen möchtest. Aber vernichte niemals den gesamten Ordner.
 
+### CloudCLI-Konto persistieren (optional, nur lokaler Speicher)
+
+Standardmäßig ist die CloudCLI-Kontodatenbank (`~/.cloudcli`) container-lokal und wird beim Rebuild gelöscht. Das Konto neu zu erstellen dauert 10 Sekunden, also lassen die meisten Leute es so.
+
+Wenn du willst, dass es Rebuilds überlebt, füge ein **named Docker volume** zu deiner compose-Datei hinzu:
+
+```yaml
+services:
+  holyclaude:
+    volumes:
+      - ./data/claude:/home/claude/.claude
+      - ./workspace:/workspace
+      - cloudcli-data:/home/claude/.cloudcli   # add this line
+
+volumes:
+  cloudcli-data:                                # and this block
+```
+
+> **Mache KEIN Bind-Mount von `./data/cloudcli` auf einem Netzwerk-Share (NAS, SMB/CIFS, NFS).** CloudCLI speichert sein Konto in SQLite, und SQLites File-Locking funktioniert auf Netzwerk-Mounts nicht. Du wirst ständig `database is locked`-Fehler bekommen. Named Volumes leben auf dem lokalen Dateisystem des Docker-Engines, deshalb funktioniert das — Bind-Mounts auf ein NAS werden nicht funktionieren.
+
+Ein Bind-Mount zu einem lokalen SSD-Pfad ist auch in Ordnung, halte ihn nur von jedem Netzwerk-Share fern.
+
 <p align="right">
   <a href="#top">↑ nach oben</a>
 </p>
@@ -793,6 +819,57 @@ So betreibe ich es persönlich. Bearbeite `./data/claude/settings.json` auf dein
 
 ---
 
+## :shield: Fernzugriff & Exposition
+
+HolyClaude bindet CloudCLI an Port `3001`. Standardmäßig ist das nur lokal — gut für den Betrieb auf deinem Laptop oder einem Heimserver, auf den du per SSH zugreifst.
+
+**In dem Moment, in dem du von außerhalb deines Netzwerks darauf zugreifen willst, lies diesen Abschnitt.**
+
+### Kein Port-Forwarding ins öffentliche Internet
+
+Ich sage es direkt: Schlag kein Loch in deinen Router und exponiere `3001` nicht ins offene Internet. Nicht mal mit einem Passwort. Warum:
+
+- CloudCLI exponiert eine vollständige Shell über das Web-Terminal-Plugin
+- Es kann beliebigen Code ausführen, Pakete installieren und dein gesamtes `/workspace` lesen/schreiben
+- Es hält deine Anthropic-OAuth-Tokens und API-Keys
+- Basic-Auth-Passwörter werden gebrute-forced, credential-gestuffed und aus Logs extrahiert
+- Ein geleaktes Passwort = jemand anderes hat eine bezahlte Claude-Code-Instanz auf deiner Maschine mit deinem Geld
+
+Ein Passwort ist eine Bodenschwelle, keine Tür. Behandle HolyClaude wie eine SSH-Session: niemals im offenen Internet ohne einen ordentlichen Tunnel davor.
+
+### Nutze stattdessen einen ordentlichen Tunnel
+
+Das sind die zwei Optionen, die ich wirklich empfehle:
+
+| Option | Für wen | Warum |
+|--------|-------------|-----|
+| **[Tailscale](https://tailscale.com)** | Persönliche Nutzung, kleine Teams | WireGuard-Mesh-VPN. Installiere Tailscale auf deinem Server + Laptop/Telefon, und du erreichst `http://holyclaude:3001` von überall, als wärst du im LAN. Keine offenen Ports, kein DNS, keine Zertifikate. Kostenlos für persönliche Nutzung. |
+| **[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)** | Teilen mit anderen, öffentlicher Hostname | Cloudflare proxied die Verbindung, sodass Port `3001` geschlossen bleibt. Du bekommst eine echte Domain mit HTTPS, und kannst Cloudflare Access (Google/GitHub SSO) davor schalten. Das kostenlose Tier deckt die meiste persönliche Nutzung ab. |
+
+Beide geben dir:
+- Null offene Ports an deinem Router
+- Verschlüsselter Transport von Ende zu Ende
+- Echte identitätsbasierte Auth (kein geteiltes Passwort)
+- Audit-Logs
+
+### Wenn du darauf bestehst, es direkt zu exponieren (bitte nicht)
+
+Wenn du den Tunnel absolut überspringen musst (Self-Hosting-Tutorial, isoliertes Lab-Netzwerk, was auch immer), mindestens:
+
+1. **Stelle einen Reverse Proxy davor** (Caddy, nginx, Traefik) mit echtem TLS
+2. **Füge IP-Allowlisting** auf Firewall- oder Proxy-Ebene hinzu — nur deine bekannten IPs
+3. **Aktiviere `bypassPermissions: false`** (der Standard), damit Shell-Befehle noch nachfragen
+4. **Rotiere deine Anthropic-Zugangsdaten**, wenn etwas seltsam aussieht
+5. **Betreibe hinter Cloudflare Access oder ähnlichem SSO**, nicht Basic Auth
+
+Selbst mit all dem ist die Angriffsfläche riesig. Nutze Tailscale oder Cloudflare Tunnel. Sie sind kostenlos, brauchen fünf Minuten zum Einrichten, und das ist, was ich persönlich nutze.
+
+<p align="right">
+  <a href="#top">↑ nach oben</a>
+</p>
+
+---
+
 ## :bell: Notifications
 
 Geh von deinem Computer weg und erfahre, wenn Claude fertig ist. Verwendet [Apprise](https://github.com/caronc/apprise) für Benachrichtigungen — unterstützt 100+ Dienste einschließlich Discord, Telegram, Slack, E-Mail, Pushover, Gotify und mehr.