Zouroboros Observatory

Portable, private-by-default operational visibility for Zouroboros installations. The package reads supported telemetry sources, normalizes them into a versioned snapshot, and serves a read-only React dashboard without exposing raw paths, secrets, prompts, or private memory content.

Install

npm install -g zouroboros-observatory
zouroboros-observatory init
zouroboros-observatory doctor
zouroboros-observatory start

The default server binds to 127.0.0.1:4178. Binding to any non-loopback host fails closed unless ZOUROBOROS_OBSERVATORY_TOKEN is set.

Commands

zouroboros-observatory init [--force]
zouroboros-observatory doctor [--json]
zouroboros-observatory snapshot [--json]
zouroboros-observatory start [--host 127.0.0.1] [--port 4178]
zouroboros-observatory export --target zo-site --out ./observatory-site

The unified CLI exposes the same workflow under zouroboros observatory.

Configuration

The package reads ~/.zouroboros/config.json and ~/.zouroboros/observatory.json, then applies environment overrides.

| Variable | Purpose | |---|---| | ZOUROBOROS_HOME | Configuration root, default ~/.zouroboros | | ZOUROBOROS_INSTANCE_NAME | Operator-visible instance label | | ZOUROBOROS_MEMORY_DB | SQLite memory database | | ZOUROBOROS_RESULTS_DIR | Swarm, workflow, and evaluation artifacts | | ZOUROBOROS_REPO | Installed repository root for governance evidence | | ZOUROBOROS_FACTORY_DIR | Optional software-factory telemetry root | | ZOUROBOROS_CHRONICLE_PATH | Optional Chronicle JSON feed | | ZOUROBOROS_OBSERVATORY_TOKEN | Bearer token required for non-loopback binds | | HOST / PORT | Server bind overrides |

Missing optional sources remain visible as unavailable with exact setup guidance. Bounded scans inspect at most 200 files across three directory levels and only parse JSON files smaller than 2 MB.

Security

• SQLite opens in read-only mode.
• The HTTP API supports GET only.
• Non-loopback startup requires bearer authentication.
• Tokens are accepted only in the Authorization header, never in query strings.
• Responses disable caching, framing, cross-origin opening, and unrestricted content loading.
• Source labels are normalized to basenames; absolute paths and raw content do not enter snapshots.
• Chronicle reports counts and state only, never proposal bodies.

The Zo Site export is private by default and still requires ZOUROBOROS_OBSERVATORY_TOKEN as defense in depth.

Library API

import {
  createObservatorySnapshot,
  createObservatoryServer,
  runObservatoryDoctor,
} from "zouroboros-observatory";

const snapshot = createObservatorySnapshot();
const doctor = runObservatoryDoctor();
const server = createObservatoryServer({ host: "127.0.0.1", port: 4178 });