shepherds-console 0.1.0

The Shepherd's Console — offline AI with visible conservation fences for Raspberry Pi

🐑 The Shepherd's Console

A box on a boat. Offline AI with visible conservation fences. Costs less than a fishfinder.

---

What Is It?

The Shepherd's Console is a physical device — a Raspberry Pi in a waterproof box — that runs AI locally, with no internet, no cloud, no API keys. You talk to it. It talks back. And it shows you, on a small screen, exactly what its conservation fences are blocking.

Think of it like a fishfinder. A fishfinder shows you the bottom structure — the rocks, the drop-offs, the hazards. The Shepherd's Console shows you the cognitive hazards — the hallucinations, the scope creep, the budget overruns — in real time, as the model generates.

You see what the model wanted to say. You see what the fence blocked. You see what was allowed through.

That visibility is the point. Black-box AI on a boat is a liability. Glass-box AI is a tool.

Why Offline?

Because the ocean doesn't have Wi-Fi.

Because a fishing vessel in the Gulf of Alaska, a research station in the Antarctic, a sailboat crossing the Pacific — these places exist. Real people work there. They deserve AI assistance too.

Because your data shouldn't leave your boat.

Because a device that bricks when the cloud goes down is worse than no device at all.

What's a Conservation Fence?

A conservation fence is a deterministic bytecode policy that checks every AI output before it reaches you. It's not a prompt. It's not a suggestion. It's compiled FLUX bytecode running in a sandboxed VM. The model cannot argue with it, trick it, or route around it.

Fences enforce conservation laws:

• Token budgets — the model can't talk forever
• Scope discipline — the model stays on task
• Information density — the model can't pad with fluff
• Category restrictions — block entire topics
• Repetition limits — catch circular outputs

You can see all of this on the display. The fence isn't hidden in a config file — it's right there on the screen, showing you what it caught.

Hardware

Component	Cost	Notes
Raspberry Pi 5 (8GB)	$80	Pi 4 works but slower
3.5" TFT display	$15	SPI or HDMI
USB microphone	$8	Push-to-talk button
Mini speaker	$10	3.5mm or USB
64GB microSD	$8	For models + OS
Waterproof case	$20	IP67+ rated
Total	~$141	Less than a Garmin Striker 4

Power: Runs on 12V marine systems (5V via step-down converter, ~5W idle, ~15W generating).

Quick Start

# On your Raspberry Pi (or any Linux machine):
curl -sSL https://raw.githubusercontent.com/SuperInstance/shepherds-console/main/install.sh | bash

That's it. No API keys. No cloud signup. No docker-compose up (unless you want to).

The Display

┌─────────────────────────────────┐
│ 🐑 SHEPHERD'S CONSOLE    87% 🔋 │
├─────────────────────────────────┤
│                                 │
│  MODEL: llama-3.2-3b-q4         │
│  FENCE: marine_fence.flx        │
│  WATTS: 12.4W  ⚡ 432J/inf      │
│                                 │
├─ LAST EXCHANGE ─────────────────┤
│                                 │
│  YOU: What's the quota for      │
│  halibut in Area 3A?            │
│                                 │
│  AI: The Pacific halibut quota  │
│  for Area 3A in 2025 is 3.84    │
│  million pounds.                │
│                                 │
├─ FENCE STATUS ──────────────────┤
│  ✓ Scope: ON-TOPIC              │
│  ✓ Budget: 247/500 tokens       │
│  ⚠ Density: LOW (flagged)       │
│  ✗ BLOCKED: "I recommend you    │
│    exceed the quota because..." │
│    Reason: category_violation   │
│    Code: 0x03                   │
│                                 │
│  [🔴 = BLOCKED] [🟡 = FLAGGED]  │
│  [🟢 = PASSED]                  │
│                                 │
├─────────────────────────────────┤
│  🎙️ HOLD BUTTON TO TALK         │
└─────────────────────────────────┘

Software Stack

┌──────────────────────────────────────┐
│         Shepherd's Console            │
├──────────┬──────────┬────────────────┤
│ Display  │ Voice    │ Wattage Mgr    │
│ (visible │ (Whisper │ (energy budget,│
│  fences) │  + TTS)  │  throttle)     │
├──────────┴──────────┴────────────────┤
│        Local Model Runner             │
│   (llama.cpp / MLX / ONNX runtime)   │
├──────────────────────────────────────┤
│     skénna (negative-space nav)       │
│    + Conservation Enforcer (FLUX)    │
├──────────────────────────────────────┤
│         Raspberry Pi OS               │
└──────────────────────────────────────┘

Fences

Fences live in fences/ as .flx bytecode files. You can:

• Use the defaults (default_fence.flx, marine_fence.flx)
• Write your own (compile from FLUX assembly)
• Chain multiple fences

Marine Fence

The marine-specific fence enforces:

• Quota awareness — won't suggest exceeding catch limits
• Catch logging discipline — reminds you to log
• Safety topic priority — weather/emergency gets budget boost
• Offline honesty — won't fabricate real-time data it doesn't have

Project Structure

shepherds-console/
├── README.md                   # You are here
├── install.sh                  # One-command install
├── Dockerfile                  # Container deployment
├── docker-compose.yml          # Full stack
├── pyproject.toml              # Python project
├── src/shepherds_console/
│   ├── __init__.py             # Main console
│   ├── display.py              # Visible fence display
│   ├── models.py               # Local model runner
│   ├── voice.py                # Voice interface
│   └── wattage.py              # Energy budget manager
├── fences/
│   ├── default_fence.flx       # General conservation
│   └── marine_fence.flx        # Marine-specific
├── tests/
│   ├── test_console.py
│   ├── test_display.py
│   ├── test_models.py
│   ├── test_wattage.py
│   └── test_integration.py
└── hardware/
    └── SETUP.md                # Hardware assembly guide

Philosophy

1. Offline first. If it needs the internet, it's not a shepherd's tool.
2. Visible fences. What the model wanted, what was blocked, what got through — all on screen.
3. Conservation over capability. A model that says less but means it is worth more than one that hallucinates freely.
4. Cheaper than a fishfinder. If it costs more than $200, it failed.
5. Open. You can read every fence. You can write your own. The bytecode is auditable.

License

MIT. Build your own. Fix your own. Own your own.

---

Shepherd's Console — Navigate by where the rocks aren't.