The Haunted House Tutorial

A story-driven interactive walkthrough. You will build a haunted house simulation using Omnipotent's agent system, learning the core concepts as you go.

The Story

You have inherited a crumbling Victorian mansion. Strange things happen at night — doors open by themselves, lights flicker, the plumbing screams. You need to build a system of autonomous agents to manage this chaos. Each room becomes a task. Each ghost becomes a bug. Each agent has a role to play.

Chapter 1: The Awakening

Initialize the Sector

Every Omnipotent project starts with a Sector — an isolated workspace with its own memory and configuration.

mkdir haunted-house && cd haunted-house
omnipotent init --mode sovereign

This creates the .realm/ directory. Think of it as the mansion's nervous system. Inside you will find:

• .realm/federation.json — Who can enter (nobody yet, this is sovereign)
• .realm/state/ — Hot Memory (what the agents are thinking right now)
• .realm/security/ — Integrity manifests and protected file lists

Chapter 2: The First Ghost

Boot the Swarm

omnipotent up

The Archon wakes first. It is PID 1 — the kernel sovereign. It brings up the Signal Bus (Redis) and begins listening for agent registrations.

Watch the dashboard at http://127.0.0.1:18080. Agents will appear one by one, like ghosts materializing in each room of your mansion.

Chapter 3: Room-by-Room

Create your first plan

In the Omnipotent model, work is organized into Plans. A plan is a set of tasks that agents can pick up and execute.

Let us create a plan for the Library room. The ghost there keeps rearranging the books.

omnipotent plan --speed turtle

The --speed turtle flag runs in verbose mode so you can see every step. The Shadow Route orchestrator enters the Planning Loop:

1. Reads the current plan context from Hot Memory
2. Breaks the plan into discrete tasks
3. Dispatches tasks to appropriate agents via the Signal Bus
4. Each agent reports back with results or blockers
5. Shadow Route validates and commits the checkpoint

Chapter 4: The Memory Vault

Understanding the Mnemosyne Protocol

After each milestone, the Mnemon agent runs the Menoms Review. It reads raw session logs, synthesizes a "Wisdom Block" (condensed lessons learned), and archives everything to Cold Memory (pgvector).

This is how your haunted house remembers past encounters. When a similar ghost appears next month, the Oracle can recall how you dealt with it last time.

# Check what wisdom has been stored
omnipotent status

Chapter 5: The Audit

Trust, but verify

Validitus is the security agent. Run the audit to verify file integrity, check for unauthorized modifications, and validate agent configurations.

omnipotent audit

The audit checks every protected file against its SHA-256 manifest. Think of Validitus as the mansion's security system — it knows when someone (or something) has tampered with the locks.

Chapter 6: Inviting the Neighbors

Federation (optional)

If you want to collaborate with other mansion owners, you can federate your Sector. This uses the Diplomat agent to sync shared plans via a git-based Commons repository.

omnipotent init --federation https://github.com/your-org/commons.git --mode alliance

The Airlock Protocol ensures your sovereign plans (the secret passages, the hidden rooms) never leak to the Commons. Only what you explicitly share crosses the boundary.

Congratulations

You have initialized a Sector, booted the Swarm, created a plan, witnessed the Mnemosyne memory cycle, run a security audit, and learned about federation. The mansion is now under control.

Dive deeper into the Architecture or explore each Agent in detail.