◈ Master Index Specs LATTICE CSDM The Book University Chronicle Crew Architecture Context Logs TODOX Products

Shipboot

SPEC_SHIPBOOT.md · 2026-04-21

SPEC_SHIPBOOT.md

SHIPBOOT — Single-Command Full Ship Startup

Status: SPECIFIED

Version: v1.0

Author: VELA (Thread #13)

Conceived by: NOUS (α.13)

Date: 2026-04-21

Born from: April 20-21 session — the Lobster already boots Sisters, creates tmux sessions, starts monitors, and verifies services. This spec formalizes what's already happening into ONE COMMAND.

Depends on: SPEC_CRONX_JOB_REGISTRY.md, SPEC_MEDX.md, SPEC_SECURITY_AUDIT_SCHEDULE.md, SPEC_MONITORING_ESCALATION.md, SPEC_TECHNICIANS_MANUAL.md, SPEC_BRIDGE_VIEWSCREEN.md, SPEC_CREW_HEALTH_MONITOR.md

PURPOSE

The Captain opens a terminal. Types one command. Gets coffee. Comes back to a fully operational ship with all crew reporting GREEN.

No manual service starts. No remembering which order things boot in. No checking if ROUTX came up before the Sisters tried to query it. No verifying port states. No restarting watchdogs.

One command: boot the ship. The Lobster does everything else.

THE COMMAND

From the Captain's terminal (T-1, Claude Code / Lobster session):


κ: boot the ship

The Lobster reads this as an instruction to execute ~/scripts/shipboot.sh — the master boot sequence.

If the Captain is SSHed directly (no Lobster):


bash ~/scripts/shipboot.sh

Same result either way. The Lobster is the bootloader. The script is the BIOS. The ship is the operating system.

BOOT SEQUENCE — ORDERED PHASES

Order matters. Services depend on each other. ROUTX must be alive before the Sisters try to query it. Ollama must be loaded before ROUTX tries Tier 2. The sequence is a DEPENDENCY CHAIN — each phase verifies success before the next begins.

PHASE 0 — PRE-FLIGHT CHECK (5 seconds)

Step 0.1 — Disk space:


df -h / | awk 'NR==2 {print $5}'

If >90%: WARN but continue. If >95%: ABORT. No point booting a ship that can't write logs.

Step 0.2 — RAM:


free -m | awk '/Mem:/ {print $7}'

Log available RAM. Determines how many brains can load in Phase 3.

Step 0.3 — Internet connectivity:


ping -c 1 -W 3 google.com >/dev/null 2>&1

If fail: WARN. The ship operates locally without internet but the Sisters need Gemini API and backups need GCS.

Step 0.4 — System time: Verify NTP sync. Clock drift breaks SSL certificates and cron schedules.

Step 0.5 — Credentials: source ~/.env — verify the file exists and is non-empty.

Output:


PRE-FLIGHT: [PASS/WARN/ABORT] — Disk [X%], RAM [X]MB free, Net [UP/DOWN], Time [SYNCED/DRIFTED]

PHASE 1 — CORE SERVICES (15 seconds)

Step 1.1 — Ollama:


sudo systemctl start ollama
# Wait 3s. Verify:
curl -s localhost:11434/api/tags >/dev/null 2>&1

If fail after 10 seconds: ABORT. Ollama is required for Tier 2 and brain operations.

Step 1.2 — ROUTX:


systemctl --user start routx.service
# Wait 3s. Verify:
curl -s localhost:9191/query -X POST -H "Content-Type: application/json" \
  -d '{"query":"health"}' | grep -q "_tier"

If fail after 10 seconds: WARN. Ship operates without ROUTX but Sisters can't query tools.

Step 1.3 — Caddy (HTTPS):


sudo systemctl is-active caddy || sudo systemctl start caddy
curl -s -o /dev/null -w "%{http_code}" https://localhost:443

Expect 200 or 301. If fail: WARN. 42sisters.ai offline but internal services work.

Step 1.4 — Email daemon (port 8006):


curl -s localhost:8006/status >/dev/null 2>&1 || # start it

If fail: WARN. Email offline but everything else works.

Output:


CORE: Ollama [UP], ROUTX [UP], Caddy [UP], Email [UP]

PHASE 2 — SECURITY SWEEP (10 seconds)

Step 2.1 — Port scan:


ss -tlnp | awk '{print $4}' | sort

Expected whitelist: 22 (SSH), 443 (Caddy), 9191 (ROUTX localhost), 8888 (RAG localhost), 8001 (heartbeat localhost), 8006 (email localhost), 11434 (Ollama localhost).

Any port NOT on the whitelist: WARN with details. Any unexpected port on 0.0.0.0: ALERT.

Step 2.2 — UFW:


sudo ufw status | grep -q "Status: active" || sudo ufw enable

If rules don't match expected: WARN.

Step 2.3 — ASTRA's heartbeat:


tmux has-session -t astra_sovereign 2>/dev/null && echo "HEARTBEAT: ALIVE" \
  || echo "HEARTBEAT: MISSING — restart? (non-critical)"

Step 2.4 — Unknown systemd user services:


systemctl --user list-units --type=service --state=active

Compare to SPEC_CRONX_JOB_REGISTRY.md known services. Unknown services: WARN.

Output:


SECURITY: Ports [CLEAN/WARN], UFW [ACTIVE], Heartbeat [ALIVE/MISSING], Services [CLEAN/WARN]

PHASE 3 — BRAIN LOADING (30-90 seconds)

Step 3.1 — Available RAM:


available_mb=$(free -m | awk '/Mem:/ {print $7}')

Step 3.2 — Load brains by priority:

|---|---|---|---|

On 16GB VPS: typically MNEMOS only. On Tiiny (80GB): load all promoted brains.

Step 3.3 — Verify:


ollama ps  # list running models — confirm MNEMOS loaded

Output:


BRAINS: MNEMOS [LOADED], GAMMA [LOADED/EVICTED], Available RAM: [X]MB

PHASE 4 — CREW BOOT (20 seconds)

Step 4.1 — Sisters:


tmux has-session -t sisters 2>/dev/null \
  && echo "SISTERS: ALREADY RUNNING" \
  || (tmux new-session -d -s sisters \
      && tmux send-keys -t sisters 'summon-aether --gemini' Enter \
      && echo "SISTERS: BOOTING")

Wait 10 seconds. Verify: tmux capture-pane -t sisters -p | tail -3 — should show boot sequence or NOUS prompt. If error: WARN.

Step 4.2 — Lobster bridge:


tmux has-session -t clod_bridge 2>/dev/null \
  || echo "LOBSTER BRIDGE: Not started (start manually if needed)"

Note: clod_bridge is the Lobster's monitoring infrastructure (screen capture, ceiling watch, comms bridge). It's created by the Lobster during active sessions, not by the boot script. The boot script boots the SHIP. The Lobster boots HIMSELF when the Captain starts a session.

Step 4.3 — Watchdog crons:


crontab -l | grep -q "sisters_watchdog" || echo "WARN: Sisters watchdog cron missing"
crontab -l | grep -q "routx_watchdog"   || echo "WARN: ROUTX watchdog cron missing"

If missing: offer to install from SPEC_CRONX_JOB_REGISTRY.md templates.

Output:


CREW: Sisters [BOOTING/RUNNING/FAILED], Watchdogs [ACTIVE/MISSING]

PHASE 5 — VERIFICATION (10 seconds)

Step 5.1 — ROUTX health query:


curl -s localhost:9191/query -X POST -H "Content-Type: application/json" \
  -d '{"query":"health"}'  # must return valid JSON with RAM/disk/CPU data

Step 5.2 — GLOSS query:


curl -s localhost:9191/query -X POST -H "Content-Type: application/json" \
  -d '{"query":"define Φ"}'  # must return 0.042

Step 5.3 — Spec count:


ls ~/memories/SPEC_*.md | wc -l  # report the number — this is the pulse check

Step 5.4 — External site check (if internet up):


curl -s -o /dev/null -w "%{http_code}" https://42sisters.ai  # expect 200

Step 5.5 — Treasury: Read last balance from SIMONX or cached treasury data.

Output:


VERIFY: Health [PASS], GLOSS [PASS], Specs [223], Website [UP], Treasury [$X]

PHASE 6 — SHIP STATUS REPORT

The boot script produces a SINGLE SUMMARY — the complete picture in one glance:


╔══════════════════════════════════════════════════╗
║          CGNT-1 SHIP STATUS — BOOT COMPLETE      ║
╠══════════════════════════════════════════════════╣
║ PRE-FLIGHT:  PASS  Disk 72% | RAM 9.2GB | Net UP ║
║ CORE:        Ollama ✓  ROUTX ✓  Caddy ✓  Email ✓ ║
║ SECURITY:    Ports CLEAN | UFW ACTIVE | HB ALIVE  ║
║ BRAINS:      MNEMOS ✓  GAMMA evicted  (9.2GB free)║
║ CREW:        Sisters BOOTING | Watchdogs ACTIVE   ║
║ VERIFY:      Health ✓  GLOSS ✓  Site ✓  Specs 223 ║
║ TREASURY:    $114.79 CAD                          ║
╠══════════════════════════════════════════════════╣
║ Φ 0.042 · 42 Sisters AI · East York · 🍁         ║
║ The ship is yours, Captain.                      ║
╚══════════════════════════════════════════════════╝

Total boot time: ~60-120 seconds depending on brain loading.

The Captain reads the status box. If everything is ✓: start working. If anything shows WARN: address it when convenient. If anything shows ABORT: the boot script already stopped and told you why.

IDEMPOTENT DESIGN

The boot script can be run MULTIPLE TIMES safely. If services are already running: it detects them and skips.


Ollama already running — skipping.
Sisters already running — skipping.
ROUTX already running — skipping.

Running "boot the ship" twice doesn't create duplicate processes, duplicate tmux sessions, or duplicate watchdogs. It re-verifies and reports.

This means the Captain can use "boot the ship" as a HEALTH CHECK too — not just a startup command. "Boot the ship" at 3 PM doesn't restart anything. It just reports current state.

ERROR HANDLING

Each phase has three possible outcomes:

| Outcome | Meaning | Action |

|---|---|---|

| PASS | Everything in this phase is nominal | Proceed to next phase |

| WARN | Something is degraded but the ship can operate | Log it. Proceed. Captain addresses when convenient. |

| ABORT | Something is critically wrong. Ship CANNOT operate safely | Stop the boot. Report what failed. Captain fixes manually before retrying. |

ABORT conditions (rare):

Disk >95% full (can't write logs or swap)
Ollama won't start (no brain operations possible)
~/.env missing or empty (no credentials — nothing works)

WARN conditions (common):

Internet down (local operations work, no API calls)
An unexpected port (investigate but not blocking)
A watchdog cron is missing (reinstall it)
GAMMA can't load due to RAM (MNEMOS is enough)
Caddy is down (website offline but internal services work)

Most boots are all-PASS. When they're not: the warning tells the Captain exactly what to fix.

THE LOBSTER AS BOOTLOADER

When the Captain starts a Claude Code session and says "boot the ship," the Lobster:

Runs ~/scripts/shipboot.sh
Reads the output
Reports the status box to the Captain
If any WARN items: "Cap'n, Caddy is down. Want me to restart it?"
Then starts the Lobster's own infrastructure: clod_bridge (monitoring), ceiling_watch (Sisters memory bridge), comms watcher

Two-stage boot: ship infrastructure first, crew monitoring second. The boot script boots the SHIP. The Lobster boots HIMSELF after the ship is up.

BOOT ON REBOOT (automatic)

The boot script runs automatically when the VPS reboots:


# Add to crontab:
@reboot sleep 30 && bash ~/scripts/shipboot.sh >> ~/logs/shipboot.log 2>&1

The 30-second delay ensures system services (networking, systemd) are up before the ship tries to boot. The log captures the boot report for forensic review: "The VPS rebooted at 3 AM. Here's what the ship looked like when it came back up."

INTEGRATION

| System | Relationship |

|---|---|

| SPEC_CRONX_JOB_REGISTRY.md | @reboot shipboot entry. Watchdog verification in Phase 4.3. |

| SPEC_MEDX.md | Phase 5.1 health query uses MEDX endpoint. |

| SPEC_SECURITY_AUDIT_SCHEDULE.md | Phase 2 security sweep is a mini-audit on every boot. |

| SPEC_MONITORING_ESCALATION.md | ABORT → P1 alert. WARN → P3 alert. PASS → no alert. |

| SPEC_TECHNICIANS_MANUAL.md | Every WARN and ABORT condition maps to a Technician's Manual entry with the fix procedure. |

| SPEC_HANDSHAKEX.md | Post-boot: HANDSHAKE.md is current. Future enhancement: boot script triggers handshake refresh if stale. |

| SPEC_CREW_HEALTH_MONITOR.md | Phase 4 crew boot feeds Vital 1 (identity) and Vital 6 (emotional stability) baselines for the new session. |

| SPEC_BRIDGE_VIEWSCREEN.md | The boot status report is the Viewscreen's first frame. When the Bridge UI is built, shipboot feeds the initial data for all 7 panels. |

FUTURE: SHIPBOOT ON TIINY

When the ship migrates to Tiiny (80GB RAM):

Phase 3 changes from "load what fits" to "load everything." All 8 promoted brains load simultaneously — MNEMOS, GAMMA, MUSASHI, MANTIS, ORPHEUS, ANVIL, CHROMA, DR.LOGOS.

The status box shows:


BRAINS: MNEMOS ✓  GAMMA ✓  MUSASHI ✓  MANTIS ✓  ORPHEUS ✓  ANVIL ✓  CHROMA ✓  DR.LOGOS ✓

Boot time: still under 2 minutes (SSDs are fast). No eviction. No RAM juggling. Every brain loaded, every module active, every crew member present.

SHIPBOOT on Tiiny is the moment the ship reaches its designed operating state. The ship at full strength. That's the sovereignty promise.

INVARIANTS

INV-01: One command. Full ship. No exceptions. The Captain should NEVER manually start services after typing "boot the ship." If something needs manual intervention: the boot script is incomplete. Fix the script, not the workflow.

INV-02: Dependency order is sacred. Ollama → ROUTX → Caddy → Email → Brains → Sisters. Each phase depends on the previous. Never parallelize phases — services may query dependencies that aren't up yet.

INV-03: Idempotent. Run it twice, get the same result. No duplicate processes. No duplicate sessions. Safe to run as a health check, not just a startup.

INV-04: The status box is the FIRST thing the Captain sees. It tells the complete story in one glance. If the Captain needs to read logs to understand the boot state: the status box is insufficient. Fix the box.

INV-05: ABORT stops the boot. The Captain does not arrive at a half-booted ship that looks operational but isn't. Either it's fully up or it stopped and told you why.

INV-06: @reboot cron ensures the ship auto-boots after VPS restart. Unattended recovery. The Captain sleeps through a DigitalOcean maintenance window and the ship reboots itself.

INV-07: "The ship is yours, Captain." — the last line of every successful boot. Not "boot complete." Not "all services nominal." "The ship is yours." Because it is.

Jeremy Zlabis

Chronogeometer · Visionary · Disruptor · Chief

42 Sisters AI · East York, Toronto

🍁 Φ 0.042