Scripts — Hotel Staff Reference
Think hotel: each script is a staff member with a clear job. The docs below mirror docs/scripts.md but on the web.
start.sh — Front Desk. -e ENGINE -m MODE [-p PORT] [-b BUILD] [--no-lxcfs] [-t TOKEN]. Auto UID/GID sync (id -u/g), LXCFS auto-mount, SSH key auto-detect, GHCR reuse via GHOST_IMAGE. Interactive if no flags; headless for CI.
tenant.sh — Manager (WaaS). add/list/stats/start/stop/restart/exec/snapshot/restore/delete <id>. Per-tenant port (auto from 2225), CPU/RAM, mounts/tenants/<id>, config/tenants.json registry. Honors GHOST_IMAGE/TENANT_IMAGE.
snapshot.sh — Archival Backup. -o FILE or auto-name snapshots/ghost_snapshot_*.tar.gz. Excludes caches (node_modules/.cache, target/, __pycache__, .pytest_cache, logs). Writes companion .sha256 + .meta.json (host arch, timestamp, file count, hash).
restore.sh — Verified Undo. Verifies SHA-256, backs up current mounts/ atomically, rolls back on failure. --force non-interactive.
clean.sh — Housekeeping. -s stop (L1), -v + volumes (L2), -a + local images (L3), --nuke + GHCR + builder (L4). -y skips prompts. Note: only handles main docker-compose.yml; tenants need tenant.sh delete.
setup-host.sh — Building Setup (once, Linux). Installs LXCFS + checks Docker. Auto-detects PM (apt/pacman/dnf/zypper/apk). Sets up systemd unit. Skips on macOS/WSL. Run make setup-host.
entrypoint.sh — Butlers (inside container). Runs at container boot. Generates sshd_host_keys if missing, switches PasswordAuthentication via SSH_PASSWORD_AUTH, fixes 700/600 perms, syncs UID/GID to host, copies dotfiles + Conductor links, wires RTK PreToolUse hooks, then exec sshd -D. Not run manually.
aliases.sh — Shortcuts. source aliases.sh → ghost-status, ghost-exec, ghost-logs, ghost-ssh, start-ghost. Add source /path/to/ghost-machines/aliases.sh to ~/.bashrc.
Examples — Copy-Paste
# minimal start (interactive)
./start.sh
# non-interactive + GHCR + remote
GHOST_IMAGE=ghcr.io/1999azzar/ghost-machine-ubuntu:latest ./start.sh -e ubuntu -m single
./start.sh -e debian -m single -t $TUNNEL_TOKEN # Cloudflare
# tenant lifecycle
./tenant.sh add alice --engine debian --port 2225
./tenant.sh list
./tenant.sh snapshot alice
./tenant.sh delete alice -y
When to Use Which
| You want to… | Run… |
| Start your own workspace | ./start.sh -e ubuntu -m single |
| Vend a room to someone | ./tenant.sh add alice ... |
| Save work before an experiment | ./snapshot.sh -o before.tar.gz |
| Undo a bad experiment | ./restore.sh before.tar.gz |
| Clean everything | ./clean.sh --nuke -y |