Files

sarah 1b92d1bff7 Fix critical bugs and improve reliability, compatibility, and usability

- Fix Homebrew installation: install sudo, set sudoers permissions, and add transparent root wrapper
- Add Debian 12 fallback when Debian 13 template is unavailable
- Ensure proper OpenClaw token authentication configuration
- Dynamically resolve binary paths in systemd services
- Configure SSH root password login
- Clean stale VNC locks on startup and prevent screen-blanking
- Add --skip-daemon flag to onboarding shortcut to avoid service conflict
- Enable nesting and onboot autostart for container
- Prompt for VMID and storage pools with auto-detected defaults

2026-09-26 13:12:47 +02:00

3.1 KiB

Raw Permalink Blame History

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:

Pre-flight — Verify Proxmox CLI tools (pct, pvesh, pveam), root access, and x86_64 architecture
Auto-detection & User prompts — Detect next VMID and available storages, prompt user with smart defaults
Template management — Check local storage, download Debian 13 or fallback to Debian 12 template
Container creation — Privileged LXC with nesting enabled, DHCP networking, onboot autostart
Package installation — Node.js 22, Homebrew (as non-root brewuser), OpenClaw (npm global), LXQt, TigerVNC, noVNC, Google Chrome, OpenClaw browser extension, OpenSSH server
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
Desktop integration — Desktop shortcuts for onboarding wizard (--skip-daemon) and dashboard (pre-filled token)
Systemd services — Three auto-starting services with dynamically detected binaries: openclaw-gateway (port 18789), vncserver (:1/5901), novnc (port 6080)
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 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

3.1 KiB Raw Permalink Blame History