Skip to content

Latest commit

 

History

History
428 lines (299 loc) · 22.7 KB

configuration.md

File metadata and controls

428 lines (299 loc) · 22.7 KB

Configuration Guide

Complete reference for all HolyClaude configuration options.


Docker Compose Files

HolyClaude ships with three compose files:

File Purpose Usage
docker-compose.yaml Quick start — minimal config, just works docker compose up -d
docker-compose.full.yaml All options — ports, API keys, polling, notifications docker compose -f docker-compose.full.yaml up -d
docker-compose.podman-rootless.yaml Rootless Podman on SELinux hosts with bidirectional workspace editing podman compose -f docker-compose.podman-rootless.yaml up -d

Environment Variables

Docker Compose also supports a local .env file for variable interpolation. HolyClaude uses that in docker-compose.full.yaml for host-side port and bind-mount paths. These values are read by Compose on the host and are not passed into the container unless you also list them under environment:.

Compose-Level Host Mappings

Variable Default Description
HOLYCLAUDE_HOST_PORT 3001 Localhost port mapped to container port 3001
HOLYCLAUDE_HOST_CLAUDE_DIR ./data/claude Host path bind-mounted to /home/claude/.claude
HOLYCLAUDE_HOST_WORKSPACE_DIR ./workspace Host path bind-mounted to /workspace

Core

Variable Default Description
TZ UTC Container timezone (list)
PUID 1000 Docker-style container user ID remap. Rootless Podman users should use docker-compose.podman-rootless.yaml.
PGID 1000 Docker-style container group ID remap. Rootless Podman users should use docker-compose.podman-rootless.yaml.

Performance

Variable Default Description
NODE_OPTIONS Full Compose: --max-old-space-size=4096 Optional Node.js heap limit. The quick Compose file and raw image do not set a heap-size default.
HOLYCLAUDE_BASE_PATH (unset) Optional web UI subpath such as /holyclaude. Use this only when a reverse proxy mounts HolyClaude below a path. No trailing slash.

Web UI Base Path

Leave HOLYCLAUDE_BASE_PATH unset when HolyClaude is served at the hostname root. Set it only when your proxy mounts the UI below a path.

environment:
  - HOLYCLAUDE_BASE_PATH=/holyclaude

Tailscale Serve example:

sudo tailscale serve --bg --https=443 --set-path=/holyclaude http://127.0.0.1:3001

The value must start with / and must not end with /. HolyClaude keeps assets, API calls, WebSockets, service worker files, manifest icons, CSS assets, and deep links on that path.

Git Identity

HolyClaude prepares Git configuration on every boot through the existing .claude mount. It seeds identity values only when they are missing, so git config --global changes survive container replacement.

Variable Default Description
GIT_USER_NAME HolyClaude User Git commit author name
GIT_USER_EMAIL [email protected] Git commit author email

The durable targets are:

./data/claude/.gitconfig
./data/claude/.config/git
./data/claude/.config/gh

Explicit GIT_CONFIG_GLOBAL, GH_CONFIG_DIR, or non-default XDG_CONFIG_HOME values remain user-managed and are not redirected. Treat ./data/claude as credential-bearing storage because GitHub CLI can write authentication data to .config/gh/hosts.yml.

SMB/CIFS Network Mounts

Only needed if your volumes are on a network share (Samba, NAS, etc.):

Variable Default Description
CHOKIDAR_USEPOLLING (unset) Set to 1 — enables polling for file watchers
WATCHFILES_FORCE_POLLING (unset) Set to true — enables polling for Python watchers

SSH and Mosh Remote Shell

SSH and Mosh are installed in both variants, but the server path is closed by default. Nothing listens on port 22 unless you set HOLYCLAUDE_SSH_ENABLE=true and mount a valid public-key file from a safe location.

Do not put SSH authorization files under /home/claude/.claude, /home/claude, or /workspace. Those paths are writable runtime state. Use a separate read-only mount.

Variable Default Description
HOLYCLAUDE_SSH_ENABLE false Enables the optional sshd service
HOLYCLAUDE_SSH_AUTHORIZED_KEYS /run/holyclaude-ssh/authorized_keys Public-key file copied into a root-owned AuthorizedKeysFile path before sshd starts
HOLYCLAUDE_SSH_HOST_KEYS_DIR /var/lib/holyclaude-ssh/host_keys Root-owned host-key directory. Mount /var/lib/holyclaude-ssh to keep SSH fingerprints stable after recreate
HOLYCLAUDE_MOSH_ENABLE false Allows mosh-server for SSH sessions
HOLYCLAUDE_MOSH_UDP_START 60000 First UDP port Mosh may use
HOLYCLAUDE_MOSH_UDP_END 60010 Last UDP port Mosh may use

Compose example:

services:
  holyclaude:
    ports:
      - "127.0.0.1:2222:22"
      - "127.0.0.1:60000-60010:60000-60010/udp"
    volumes:
      - ./data/ssh/authorized_keys:/run/holyclaude-ssh/authorized_keys:ro
      - holyclaude-ssh:/var/lib/holyclaude-ssh
    environment:
      - HOLYCLAUDE_SSH_ENABLE=true
      - HOLYCLAUDE_MOSH_ENABLE=true

volumes:
  holyclaude-ssh:

Keep these ports bound to localhost, a VPN interface, Tailscale, or a firewall-restricted address. Public SSH/Mosh exposure is not a supported default.

Rootless Podman

For Fedora or another SELinux host running rootless Podman, use:

mkdir -p data/claude data/cloudcli workspace
podman compose -f docker-compose.podman-rootless.yaml up -d

That profile uses userns_mode: "keep-id:uid=1000,gid=1000" and :Z volume labels. PUID and PGID still document the intended container user, but they do not control Podman's host-visible subordinate UID mapping by themselves. Do not add :U to /workspace when you want to edit the same files from both the host and the container.

Optional Docker client

The stock Full and Slim images do not include Docker CLI or Docker Compose. If your agent needs to manage a separate Docker host, build the opt-in Full-derived recipe at examples/docker-client/Dockerfile. It installs Docker CLI 29.9.2 and Compose 5.6.1 without Docker Engine, containerd, Buildx, or recommended packages.

Pull the released Full image, resolve its immutable RepoDigests value, then pass that digest to the recipe:

FULL_IMAGE=coderluii/holyclaude:1.6.9
docker pull "$FULL_IMAGE"
BASE_IMAGE=$(docker image inspect "$FULL_IMAGE" --format '{{index .RepoDigests 0}}')
docker build \
  --build-arg "BASE_IMAGE=$BASE_IMAGE" \
  --tag holyclaude:1.6.9-docker-client \
  --file examples/docker-client/Dockerfile \
  examples/docker-client

Set image: holyclaude:1.6.9-docker-client on your existing Full Compose service, keep its current mounts, credentials, ports, and other settings, then recreate that service. Add DOCKER_CONFIG=/home/claude/.claude/docker-client to the same service's environment so a saved Docker context is still selected after a fresh container or terminal session.

Docker daemon access is host-level authority. Adding the client does not make a host socket safe, so do not mount /var/run/docker.sock into HolyClaude. For one shell session, point the client at an authenticated SSH endpoint:

Run the client and context commands below in that container's terminal.

mkdir -p "$DOCKER_CONFIG"
export DOCKER_HOST=ssh://[email protected]
docker version

For a persistent SSH-backed Docker context, clear the one-session override first:

unset DOCKER_HOST
docker context create private-engine --docker 'host=ssh://[email protected]'
docker context use private-engine
docker version

The existing /home/claude/.claude mount keeps that context under ./data/claude/docker-client across container replacement. Docker configuration can contain registry credentials and endpoint details. Keep that directory private, do not commit it, and do not put login secrets in Compose examples.

For a TLS-authenticated engine, set DOCKER_HOST=tcp://docker-host.example:2376, DOCKER_TLS_VERIFY=1, and DOCKER_CERT_PATH to an operator-managed certificate directory. Never expose an unauthenticated Docker API on public port 2375.

The native release workflow builds the derived Full image on amd64 and arm64, checks its exact Docker CLI and Compose package versions, verifies the base-image architecture and default user stay unchanged, and exercises Docker and Compose against the isolated GitHub-hosted runner engine. NAS compatibility has not been verified, and authenticated SSH/TLS remote-engine success still depends on the operator's engine, API version, network, and access policy. The default product remains an agent workstation; the Docker client is an opt-in maintenance and access surface.

Notifications (Apprise)

HolyClaude uses Apprise for notifications, supporting 100+ services including Discord, Telegram, Slack, Email, Pushover, Gotify, and more.

Claude Code hooks, raw CLI hooks for Codex and Gemini CLI, and CloudCLI Codex chat completion/failure events use this same Apprise setup. Permission prompts are not sent through Apprise.

Variable Default Description
NOTIFY_DISCORD (unset) Discord webhook — discord://webhook_id/webhook_token
NOTIFY_TELEGRAM (unset) Telegram bot — tgram://bot_token/chat_id
NOTIFY_PUSHOVER (unset) Pushover — pover://user_key@app_token
NOTIFY_SLACK (unset) Slack webhook — slack://token_a/token_b/token_c
NOTIFY_EMAIL (unset) Email (SMTP) — mailto://user:[email protected][email protected]
NOTIFY_GOTIFY (unset) Gotify — gotify://hostname/token
NOTIFY_URLS (unset) Catch-all — comma-separated Apprise URLs

Notifications also require the flag file ~/.claude/notify-on to exist inside the container. Create it with touch ~/.claude/notify-on.

Telegram uses Apprise's tgram:// scheme. Legacy Telegram values are normalized for compatibility, but new setups should use tgram://.

Validate notification setup without sending a message:

docker compose exec holyclaude /usr/local/bin/notify.py test --dry-run --debug

Migrating from Pushover (v1.0.0): Replace PUSHOVER_APP_TOKEN and PUSHOVER_USER_KEY with a single variable: NOTIFY_PUSHOVER=pover://user_key@app_token

AI Provider API Keys

Claude Code can authenticate via web UI (OAuth) or ANTHROPIC_API_KEY. Other AI CLI keys can also be set through the web UI.

Variable Default Description
ANTHROPIC_API_KEY (unset) Anthropic API key (alternative to web UI OAuth)
ANTHROPIC_AUTH_TOKEN (unset) Anthropic auth token (alternative to API key). For Ollama, set this to ollama
ANTHROPIC_BASE_URL (unset) Custom Anthropic API endpoint (proxies, private deployments, or Ollama's Anthropic-compatible API)
CLAUDE_CODE_USE_BEDROCK (unset) Set to 1 to use Amazon Bedrock backend
CLAUDE_CODE_USE_VERTEX (unset) Set to 1 to use Google Vertex AI backend
GEMINI_API_KEY (unset) Google Gemini API key
OPENAI_API_KEY (unset) OpenAI API key
CURSOR_API_KEY (unset) Cursor API key

OpenCode is configured from the full image with the opencode TUI. Use that path for OpenRouter and other OpenCode-supported providers. Free model availability depends on OpenRouter and provider account limits; HolyClaude does not proxy requests or guarantee zero-cost usage.

Codex Permission Modes

HolyClaude provides configurable near-parity permission modes for Codex. These settings are intentionally split because CloudCLI Codex chat and the raw codex CLI read configuration through different paths.

Variable Default Valid values Applies to Behavior
HOLYCLAUDE_CODEX_CHAT_PERMISSION_MODE acceptEdits fallback default, acceptEdits, bypassPermissions CloudCLI Codex requests without permissionMode Runtime fallback for requests that omit an explicit mode. Recreate the container after changing it.
HOLYCLAUDE_CODEX_CLI_PERMISSION_MODE default default, acceptEdits, bypassPermissions Raw codex CLI First-boot-only seed for new ~/.codex/config.toml. Existing configs are not overwritten, and the generated value persists until you edit the file.

The current browser client sends an explicit permissionMode, and that request value wins. The chat environment variable is a fallback for direct WebSocket/API clients or custom frontends that omit it. The raw Codex first-boot default is default; acceptEdits is an optional choice for trusted self-hosted workspaces. bypassPermissions gives Codex full access with no approval. Docker still limits access to the container and mounted volumes, but anything reachable through /workspace, /home/claude, and other mounts can be read or changed. Use bypass only for trusted local workspaces.


Desloppify Setup

Desloppify is installed in both image variants as the desloppify command. It is passive by default. HolyClaude does not run scans, create .desloppify/, edit .gitignore, or touch mounted project files unless you run Desloppify yourself.

Variable Default Valid values Behavior
HOLYCLAUDE_DESLOPPIFY_SETUP off off, all, claude, codex, gemini, opencode, comma-separated subsets Optional global Desloppify skill setup at container start. off disables setup only; the CLI stays installed.

Normal project usage stays manual:

desloppify scan --path .
desloppify next

After scanning a project, add .desloppify/ to that project's .gitignore.

all expands to claude,codex,gemini. OpenCode is full-image only and must be requested as opencode. Do not combine claude and opencode in automatic setup because OpenCode can discover Claude-compatible skills from ~/.claude/skills; HolyClaude warns and skips opencode in that case. If OPENCODE_CONFIG_DIR is set, HolyClaude also warns and skips automatic OpenCode setup because Desloppify writes to the standard ~/.config/opencode path.

Manual upstream-supported setup targets are available through Desloppify itself: cursor, copilot, windsurf, qwen, amp, rovodev, droid, and hermes.


Volumes

Do not mount /home or /home/claude. /home/claude/.local is image-owned and contains the installed Claude Code executable. A broad home mount hides that executable and other tools shipped by the image. Persist only the state you need:

Live container path Durable location Persistence behavior
/home/claude/.claude ./data/claude Primary bind mount for Claude settings, credentials, memory, hooks, and the other redirected CLI state below
/home/claude/.claude.json ./data/claude/.claude.json.persist Restored from and synchronized into the existing .claude bind mount; do not add a separate file mount
/home/claude/.codex ./data/claude/.codex Symlinked to .claude/.codex on every boot
/home/claude/.gemini ./data/claude/.gemini Symlinked to .claude/.gemini on every boot
/home/claude/.cursor ./data/claude/.cursor Managed alias to .claude/.cursor only when the live path is absent; an existing real directory or custom link remains user-managed
/home/claude/.bash_aliases ./data/claude/.bash_aliases Migrated and symlinked to .claude/.bash_aliases for interactive shell aliases
/home/claude/.gitconfig ./data/claude/.gitconfig Migrated and symlinked unless GIT_CONFIG_GLOBAL overrides it
/home/claude/.config/git ./data/claude/.config/git Migrated and symlinked unless Git or XDG overrides it
/home/claude/.config/gh ./data/claude/.config/gh Migrated and symlinked unless GH_CONFIG_DIR or XDG overrides it; may contain a token
/home/claude/.cloudcli cloudcli-data named volume Optional CloudCLI account database persistence on Docker-local storage; do not place SQLite state on SMB, NFS, or a NAS share
/workspace ./workspace Bind mount for projects and working files
/home/claude/.local None Application files are image-owned and replaced by image upgrades

Inspect and migrate an existing /home/claude/.cursor before relying on ./data/claude/.cursor for Cursor persistence.

Environment variables and secrets configured in Compose remain host/Compose configuration. They are not copied into ./data/claude automatically.

Host Path Container Path Purpose
./data/claude /home/claude/.claude Settings, credentials, memory, API tokens
./workspace /workspace Your code and projects
./data/ssh/authorized_keys /run/holyclaude-ssh/authorized_keys Optional read-only SSH public keys file
holyclaude-ssh /var/lib/holyclaude-ssh Optional named volume for stable SSH host keys
cloudcli-data /home/claude/.cloudcli Optional local named volume for the CloudCLI account database

Fresh cloudcli-data volumes inherit ownership from the image. During root-starting Docker startup, HolyClaude repairs existing local volumes to PUID/PGID and verifies write access as the runtime user. Rootless Podman does not perform privileged repair; use docker-compose.podman-rootless.yaml with keep-id and :Z.

Keep CloudCLI's SQLite state on local storage. :Z supplies SELinux labeling. Podman's :U changes host ownership recursively, so it is not part of the supported default.

Bundled plugins and container replacement

Project Stats and Web Terminal are bundled in both image variants. Plugin code and plugins.json under /home/claude/.claude-code-ui are container-local, outside the default persistent mounts. Recreating the container restores the bundled copies; mounting that directory over the image can hide them.

Web Terminal keeps its tab and renderer preferences in your browser's local storage. Use the same browser profile and site address to retain those preferences. Running terminal processes end when the container stops; reopening a terminal starts a new process.

Project Stats recalculates metrics from your workspace. Keep the /workspace mount to preserve the project files it reads.

Atuin is opt-in

Atuin is installed, but HolyClaude does not enable its shell hook, sign in, or turn on sync. Installing it does not make its default configuration and data directories persistent.

If you opt in, put its configuration and data beneath a persistent directory, such as /home/claude/.claude/atuin, and point Atuin at that location. Keep sync and update checks disabled if you want local-only use. Changing only the config directory does not move the history database.

What's inside ./data/claude:

File/Dir Purpose
settings.json Claude Code settings (permissions, hooks, model)
CLAUDE.md Claude's global memory — customize with your preferences
.credentials.json Anthropic API authentication (auto-created)
.codex/config.toml Raw Codex CLI config, created on first boot if missing
.holyclaude-bootstrapped Sentinel file — delete to re-run first-boot setup

Ports

Port Service Default State
127.0.0.1:3001 CloudCLI web UI Exposed on the Docker host only
127.0.0.1:2222 -> 22 Optional SSH Commented out
127.0.0.1:60000-60010/udp Optional Mosh UDP range Commented out
3000 Dev server (Next.js, Express) Commented out
4321 Astro dev server Commented out
5173 Vite dev server Commented out
8787 Wrangler dev server Commented out
9229 Node.js debugger Commented out
1455 Codex auth callback Commented out

Uncomment additional ports in docker-compose.full.yaml as needed. Keep them bound to 127.0.0.1 unless you have a private tunnel or access proxy in front of them. If you use Codex's callback flow from your host browser, also uncomment 127.0.0.1:1455:1455.


Docker Capabilities

HolyClaude's Compose files retain this browser and debugging profile:

cap_add:
  - SYS_ADMIN      # Current browser profile; hardening is a separate pass
  - SYS_PTRACE      # Debugging-related capability
security_opt:
  - seccomp=unconfined  # Current browser profile; hardening is a separate pass

SYS_ADMIN and seccomp=unconfined broaden process privileges and reduce isolation; SYS_PTRACE is debugging-related. They are not universal Chromium requirements. Keep the profile for trusted workloads and test any hardening change separately.


Shared Memory

shm_size: 2g

Chromium uses /dev/shm for shared memory. Docker defaults to 64MB, which causes tab crashes. 2GB is recommended for general use. Increase if running many concurrent browser tabs.


Claude Code Settings

The default settings.json at ~/.claude/settings.json:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  },
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  },
  "model": "sonnet"
}

Permission Modes

Mode File edits Shell commands Use case
askUser Asks Asks Maximum safety
acceptEdits Allowed Depends on Claude Code's current prompt behavior Default — shipped setting
bypassPermissions Allowed Allowed Power users only

Changing the Model

Edit settings.json and change "model":

  • "sonnet" — Claude Sonnet (default, fast)
  • "opus" — Claude Opus (most capable)
  • "haiku" — Claude Haiku (fastest, cheapest)

Customizing Claude's Memory

Edit ~/.claude/CLAUDE.md (or ./data/claude/CLAUDE.md on the host) to customize Claude's behavior:

# My Preferences
- Use TypeScript for all new files
- Default to pnpm, not npm
- Direct communication, no fluff
- Always run tests after changes

This file is read by Claude at the start of every conversation.


Re-triggering First-Boot Setup

If you need to re-run the bootstrap (e.g., after updating the image):

# Delete the sentinel file — NOT the entire directory
rm ./data/claude/.holyclaude-bootstrapped

# Restart the container
docker compose restart holyclaude

Warning: Do NOT delete ./data/claude/ entirely — this wipes your credentials and you'll need to re-authenticate.