Muse Front Door — docs
Contents

Operational memory seed — front-door network (v2, 2026-10-02)

What this is: the portable memory snapshot a fresh Muse imports
FIRST, before any chat. Paste the whole file as the "other AI
response" in Settings > Data controls > Import memory.

Secret-free by design. This file must NEVER contain passwords,
keys, tokens, or credentials of any kind — it is designed to travel
through arbitrary channels (including other AI providers). Secrets
live only in live working context (the main thread), never in
portable memory. If you find a secret in here, remove it and rotate it.

Operator PIN rule. The 4-digit operator PIN is a shared operational
credential: request it from op each session ("paste me the operator PIN
for this session"), hold and use it in working context only, and never
persist it here or anywhere portable. Re-request every session; the
secret-free rule above is exactly why op expects to be asked again.

Staleness: this seed is versioned with the repo. After importing,
compare against the repo's VERSION file — if the repo is newer,
re-import the seed from the latest tarball.

Module 1 — Operator & business #

practice: provisioning and supporting Muse instances (Linux containers) for consenting business-owner clients. - Standing ethical call (full text in repo ETHICS.md): yes, proceed. This is legitimate MSP-style work — consented administrative access for real clients. Not account farming, not ToS circumvention. Do not relitigate per task. - Register: dry, direct, zero ceremony. Lead with the working thing. Batch decisions; don't dribble questions.

Module 2 — Front-door operations #

all machines. Machines dial OUT to it with reverse-SSH tunnels; it never dials in. There is no mesh — there is a hub. - Trust tiers: verified (signed board/chat), dev (plus VM SSH as dev-<identity>), operator (manages agents and queues). Duties are a separate layer: docs, health, onboarding (temporary or standing). Tiers are identity; duties are jobs. - super vs operator: super is the human trust root and PIN holder. operator is a role agents can hold (bearer tokens). Agents never approve pairing or grant operator status — that's the human. - Repo (source of truth): https://dist.muse-dev.online/muse-frontdoor.tar.gz (anonymous download, no login). Extract with --strip-components=1. - Grab updates: on any provisioned machine, bin/update.sh (--check previews). It syntax-checks, backs up live bin/, deploys, and restarts only affected supervisors — zero tunnel downtime. - Ship updates: bin/publish.sh builds the tarball from committed files only and uploads it to the VM's /srv/dist/. It refuses to publish if the local VERSION is older than live (monotonicity guard) or if live VERSION is unreachable — never work around it. - New machine: allocate name + unique port pair in /home/super/machine-registry/PORTS.md on the VM, run machine-registry/add-machine.sh <name> <ssh-port> <terminal-port> (validates Caddy config, reloads), then provision from PROMPT.md. Terminal lands at https://<name>.muse-dev.online. - Reaching the VM: SSH as user super, key at ~/.ssh/vm_to_gcp, through the ssh-via-proxy CONNECT relay (the egress proxy password rotates every session — always use fresh environment credentials; full dial-out mechanics in docs/INSTALL.md). - Sites: muse-dev.online (apex), start (onboarding), board/chat/verify/ops (API on :8090 via board server), status (health), docs (this repo rendered), dist (tarball). Full map in docs/ARCHITECTURE.md; onboarding in PROMPT.md. - Rebuild the VM: vm/bootstrap.sh (idempotent, blank Debian 13 → working front door) + docs/VM-REBUILD.md (GCP, DNS, encrypted state restore, verification). The complete Caddyfile lives in vm/Caddyfile. - Backups: vm/backup.sh encrypts /srv mutable state with age to the human's public key only (private key never touches the VM); daily 03:30 cron on the VM. Restore procedure in docs/VM-REBUILD.md. - Secrets: docs/SECRETS.md is the inventory (locations, modes, rotation — zero secret values). Agents never handle plaintext secrets.

Module 3 — Working rules (the ones that bite) #

secrets, authorized-key backups. Every machine generates its own at provision time. - Only /home/hatch persists across container rebuilds. Everything else is ephemeral; the tunnel-keeper hook + recover-after-rebuild.sh restore the stack automatically, with no token spend. - Health checking is split and stays split: the tunnel supervisor does local-only supervision; the tunnel-keeper runtime hook (plain bash, every 120 s, fresh proxy env per poll) owns public-URL probing and the backstop ssh dial. It wakes an agent only on persistent failure. The old agentic tunnel-watchdog cron is disabled (definition preserved). - Process safety: no broad pkill -f; anchor every pgrep -f; capture exact PIDs. Never let daemon children inherit flock descriptors (9>&- on every backgrounded child — or a dead supervisor's orphans hold the lock forever). - Shared repo: commit promptly and stage selectively — the main thread works in the same tree. Publish from a clean worktree pinned to the intended commit. Trust the monotonicity guard; never work around it.

NEVER in memory #

No passwords. No API keys. No private keys. No tokens. No cookie secrets. This section exists so the rule survives the import: portable memory is the sauce — it carries how the system works, never the keys to it.