# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

OpenClaw on Proxmox is a single-script deployment tool (`setup-openclaw-lxc.sh`) that automates creating a Proxmox LXC container with a fully configured OpenClaw AI assistant, LXQt desktop, Google Chrome, and VNC/noVNC remote access. It targets Proxmox VE 8.x+ hosts running as root.

## Architecture

The entire project is one Bash script with this flow:

1. **Pre-flight** — Verify Proxmox CLI tools (`pct`, `pvesh`, `pveam`), root access, and x86_64 architecture
2. **Auto-detection & User prompts** — Detect next VMID and available storages, prompt user with smart defaults
3. **Template management** — Check local storage, download Debian 13 or fallback to Debian 12 template
4. **Container creation** — Privileged LXC with nesting enabled, DHCP networking, onboot autostart
5. **Package installation** — Node.js 22, Homebrew (as non-root `brewuser`), OpenClaw (npm global), LXQt, TigerVNC, noVNC, Google Chrome, OpenClaw browser extension, OpenSSH server
6. **Configuration** — OpenClaw gateway settings (`gateway.auth.mode token`), VNC password/xstartup (no blanking), noVNC auto-scaling patch, Chrome as default browser (`--no-sandbox` wrapper), SSH root login
7. **Desktop integration** — Desktop shortcuts for onboarding wizard (`--skip-daemon`) and dashboard (pre-filled token)
8. **Systemd services** — Three auto-starting services with dynamically detected binaries: `openclaw-gateway` (port 18789), `vncserver` (:1/5901), `novnc` (port 6080)
9. **Verification** — Check all services are active, print connection info (direct one-click URLs)

Key helper: `ct_exec()` wraps `pct exec $VMID -- bash -c` for all in-container commands.

## Development Notes

- No build system, test suite, or linter — this is a standalone Bash script
- Uses `set -euo pipefail` and ERR trap for strict error handling and cleanup tips
- All in-container operations use heredoc-embedded config files (systemd units, desktop files, wrapper scripts)
- Colorized output via `info()`, `ok()`, `warn()`, `err()`, `fatal()` helper functions
- Homebrew is installed under a dedicated `brewuser` account (non-root requirement) with passwordless sudo (`0440` permission) and a transparent wrapper script at `/usr/local/bin/brew` so root and OpenClaw can run `brew` commands
- The noVNC auto-scaling patch modifies `/usr/share/novnc/app/ui.js` in-place via `sed`
- Auth token is generated with `openssl rand -hex 16`

## Testing Changes

There is no automated test infrastructure. To test changes, run the script on a Proxmox host:

```bash
bash setup-openclaw-lxc.sh
```

Verify by checking: container creation, all three systemd services running, noVNC web access, and OpenClaw dashboard reachability.

## Shell Style

- Bash with `set -euo pipefail`
- Double-quoted variables throughout
- Heredocs for multi-line content (both quoted `'EOF'` and unquoted `EOF` depending on variable expansion needs)
- `grep -v` to suppress noisy apt/install output
- Python3 one-liners for JSON parsing of Proxmox API output