Files

T

leetcrypt ad13ec14ba docs(sandbox): specs for goose harness + GUI distros, command ref, themes

Add the goose-harness and sandbox-distros-GUI design specs, a consolidated
command reference and demo-reels plan, the AI-harness planning note, and
two new client themes (blue-orange, pink-red-gray).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-06-08 10:38:36 -07:00

7.7 KiB

Raw Permalink Blame History

hack-house → Command Reference

Status: Living reference · Date: 2026-06-07 Scope: The full categorized list of in-room slash commands + keybindings, mirroring the /help popup (hh/src/ui.rs::help_clusters). This is the canonical text reference for the /sbx <type> <option> grammar, the container gui option, and the "did you mean" fuzzy-suggestion behaviour. See also: spec-sandbox-distros-gui.md (grammar + GUI spec), spec-goose-harness.md, spec-virtualbox-sandbox.md.

0. Grammar at a glance

/sbx <type> <option…>

The first token after /sbx selects the backend (docker, podman, multipass, local, vbox); the rest are options. vbox is the exception that takes extra options (a VM name / new / gui). The legacy /sbx launch <backend> … form is still accepted as a transitional alias.

Keyword options (gui, install) are position-independent — they are filtered out of the positionals, so they are never mistaken for the image name.

1. Virtual machines / sandboxes

Command	What to expect
`/sbx docker [gui] [image] [install]`	Linux container, shared shell relayed to the room. Default image `parrotsec/core` (Parrot OS) + auto dev toolchain. `gui` → noVNC desktop (see §4). `install` → install Docker first if missing.
`/sbx podman [gui] [image] [install]`	Rootless/daemonless container — no sudo modal. Default image `kalilinux/kali-rolling` (Kali). `gui` → noVNC desktop. `install` → install Podman first if missing.
`/sbx multipass [image] [install]`	Full Ubuntu VM (default `24.04`), shared shell relayed to the room. `install` → install Multipass first if missing.
`/sbx vbox`	VirtualBox VM picker — local GUI (↑↓ move · Enter/Tab boot · Esc dismiss).
`/sbx vbox new [name]`	Build a FRESH Ubuntu VM from a cloud image (cloud-init installs the dev toolchain).
`/sbx vbox [gui] <vm> [yes]`	Boot a VirtualBox VM's GUI on YOUR machine (non-host appends `yes` to install/import first).
`/sbx gui <vm> [yes]`	Alias of `/sbx vbox gui <vm> [yes]`.
`/sbx local`	A plain shell on your own machine — no VM.
`/sbx stop`	Tear down the running sandbox (purges the VM/container).

Save / load / list

Command	What to expect
`/sbx save [label] [--local]`	Save docker/podman/multipass state. `--local` on a container also writes a portable `.tar`.
`/sbx load <label>`	Relaunch a saved docker/podman/multipass snapshot (auto-detects backend).
`/sbx snaps`	List saved docker/podman/multipass snapshots.
`/sbx vmsave <vm> [label] [--local]`	Save a VirtualBox VM snapshot. `--local` also exports a portable `.ova` to `/send`.
`/sbx vmload <vm> [label]`	Restore a VirtualBox snapshot + boot (omit label for the VM's current snapshot).
`/sbx vms` · `/sbx vmsnaps <vm>`	List local VirtualBox VMs · a VM's snapshots.
`/drive` · `F2`	Type into the shared shell (`F2` releases; `Esc` reaches vim).

Defaults

Backend	Default image	Notes
Docker	`parrotsec/core`	swap `parrotsec/security` per-launch for full tools
Podman	`kalilinux/kali-rolling`	minimal; add `kali-linux-headless` for the toolset
Multipass	`24.04`	Ubuntu cloud release
Local	(host shell)	—

Any image is overridable positionally: /sbx podman parrotsec/security, /sbx docker ubuntu:24.04, etc.

2. AI agents

Command	What to expect
`/ai start [model\|profile]`	Spawn an agent (ollama tag or `models.toml` profile).
`/ai start <model> allow`	Spawn + auto-grant the agent sandbox drive.
`/ai stop`	Dismiss the agent you started.
`/ai <question>`	Ask an agent in the room (`/ai <name> <q>` if many).
`/ai <name> !<task>`	Have a granted agent run a task in the sandbox (Goose harness).
`/ai list`	List AI agents present + their provider/model.
`/ai models`	Show models the active agent's backend can serve.

3. Permissions (owner)

Command	What to expect
`/grant <user\|agent>`	Let a member OR an AI agent drive the shell.
`/revoke <user\|agent>`	Take back sandbox drive permission.
`/sudo <user>`	Delegate VM superuser (real sudo).
`/unsudo <user>`	Revoke VM superuser.
`/ai start <name> allow`	Shortcut: grant the agent drive at spawn.

4. Container GUI (noVNC)

Containers are headless, so gui runs an XFCE desktop + VNC server inside the container and bridges it to your browser via noVNC.

Invoke: /sbx podman gui or /sbx docker gui.
Backend-specific: gui is honoured only for Docker/Podman; on headless/local backends it is a flagged no-op.
The noVNC port (6080) is published on host loopback only (127.0.0.1:6080) — reachable from this machine's browser, never the LAN.
Open http://127.0.0.1:6080. Default VNC password hackhouse (override with HH_SBX_GUI_PASS).
One GUI sandbox at a time per host (fixed port). Heavy first pull (a full desktop) — strictly opt-in.

5. Files

Command	What to expect
`/send <user> <path>`	Send a file/dir directly to one member.
`/sendroom <path>`	Offer a file/dir to the whole room.
`/accept` · `/reject`	Respond to an incoming file offer.

6. Appearance

Command	What to expect
`/theme [name]`	Switch vestment, or bare `/theme` lists options.
`/theme save [name]`	Keep the vestment you're wearing for reuse.
`Ctrl+Alt+P` · `/theme random`	Conjure a random vestment (palette + sigil).

7. Layout (resize panes)

Key / Command	What to expect
`F4`	Fullscreen the terminal (cycle: terminal → chat → split).
click a pane · `F5`	Select a pane to resize (✎ marks it) — `F5` cycles chat → terminal → roster → input.
`↑` / `↓`	Grow / shrink height.
`←` / `→`	Grow / shrink the selected pane's width.
`Esc` / `Enter`	Finish editing the selected pane.
`/layout reset`	Restore the default split.
`/layout save <name>` · `load <name>`	Remember an arrangement and re-apply it.
`/layout list` · `rm <name>`	List or delete saved layouts.

8. Keys

Key	What to expect
`Enter`	Send chat message.
`F1` · `/help`	Toggle the categorized help popup.
`Ctrl-C` (while driving)	Interrupt the running command.
`Ctrl-X` (owner, not driving)	Kill switch — revoke all drive + interrupt the shell.
`PgUp` / `PgDn`	Scroll chat · `Home`/`End` = oldest/live (scrolls sandbox scrollback while driving).
`Up` / `Down` · wheel	Scroll the sandbox terminal (mouse works while driving).
`Ctrl-R` (when closed)	Reconnect to the house after a drop / AFK.
`/pw`	Show this room's password (local only).
`/clear`	Wipe your chat scrollback (local only).
`Ctrl-C` · `Ctrl-Q`	Quit hack-house.

9. Roster glyphs (badges stack)

Glyph	Meaning
(theme sigil) host	Opened the house (first in the room).
⚡ sudoer	VM superuser in the sandbox.
◆ driver	May drive the shell.
• member	Present — no extra powers.

10. "Did you mean…?" (typo help for new users)

Unrecognised slash input is caught instead of being silently sent as chat:

A mistyped top-level command (e.g. /halp) → unknown command ‘/halp’ — did you mean \/help`? (/help lists all)`.
A mistyped /sbx subcommand (e.g. /sbx dcoker) → unknown \/sbx dcoker` — did you mean `/sbx docker`?`.
No close match → falls back to … /help lists all commands.

Matching uses Levenshtein edit distance (≤ 3 and shorter than the input), so genuine free-text like /ai <question> (a known command) is never hijacked.

7.7 KiB Raw Permalink Blame History Unescape Escape