Skip to main content

Operations

Documentation Map​

OPERATIONS

Start / Run / Deploy​

Dieses Repository ist standardmaessig kein dauerhafter Service.

The canonical stack contract stands in STACK_CONTRACT.md (docs/STACK_CONTRACT.md) and ../contracts/runtime-stack-contract.json (contracts/runtime-stack-contract.json).

Uebliche Betriebsmodi:

  • lokale CLI-Nutzung
  • Shell-Wrapper fuer OpenClaw-source: exec
  • optionaler lokaler bw serve-Prozess

Healthchecks​

Es gibt keine HTTP-Health-Endpunkte.

Repo-lokale Ersatzchecks:

  • bash scripts/run.sh probe --mode light
  • bash scripts/run.sh doctor --mode deep
  • probe liefert den light-weight Runtime-Status; doctor --mode deep ist der operatorische Vollcheck
  • python3 scripts/export-fabric-metadata.py
  • bash scripts/stack-selfcheck.sh
  • python3 scripts/validate-access-model.py
  • bash scripts/fabric-selfcheck.sh

Readiness​

Es gibt keinen HTTP-Readiness-Endpunkt.

Praktische Ready-Signale:

  • Python verfuegbar
  • bw CLI verfuegbar
  • probe --mode light laeuft
  • doctor --mode deep laeuft nur bei ausdruecklicher Operator-Freigabe
  • Manifest-Selfcheck ist gruen

Logs​

  • Standardausgabe der CLI
  • Fehlerausgabe der CLI/Shell-Skripte
  • keine persistente Logging-Schicht im Repository

Monitoring​

Sinnvolle Operator-Sicht:

  • Version
  • probe-Status
  • access-model contract validation
  • Manifest-Drift
  • Provider-Modus cli oder serve
  • Sicherheitsverletzung, falls serve nicht lokal waere

Operator-visible Status Contract​

The safe status signals that this repository exposes are limited to:

  • probe output
  • doctor output in explicit deep mode
  • CLI version
  • provider mode
  • loopback enforcement state
  • access-model contract validation result
  • operator verdict taxonomy from contracts/operator-verdicts.json

Not implemented:

  • HTTP health/readiness/metrics
  • remote inventory
  • remote control plane

Access Model Operations​

The operational access model for humans, departments, teams, agents, breakglass users, bootstrap admins, and service identities is described in ACCESS_MODEL.md (docs/ACCESS_MODEL.md) and the checked-in contract files under ../contracts (contracts).

The repo-owned verification families that stay deterministic in the default gate are:

  • personal
  • department
  • company
  • agent

Operational rule:

  • if a runtime or provisioning decision would change principal type, access domain, inheritance, revocation, or breakglass behavior, the change must be reflected in the contract set and not only in ad hoc operator notes
  • metadata-only vault inventory is defined in contracts/vault-metadata-inventory.json; it may carry refs and source revisions, but never secret-bearing fields
  • sensitivity classes and operator verdicts stay machine-readable so drift and security incidents can be escalated consistently
  • jhf-keystore remains a consumer and verifier; it does not reconcile production membership or identity state
  • live acceptance on <internal-runtime-redacted> additionally needs a host-side jhf-keystore runtime checkout and an authenticated BW_SESSION; when those are missing, the blocker is external and tracked in Gitea issue #49 plus jhf-openclaw-env#64
  • the verified live runtime host is <internal-runtime-redacted> and the live admin bind is <internal-runtime-redacted>:28222
  • preferred non-interactive bootstrap is scripts/host_live_gate_bw_auth.sh, which consumes the external contract in contracts/non-interactive-bw-auth-bootstrap.md
  • scripts/ensure-bw-session.sh remains the low-level session helper and now accepts either API-key auth or controlled BW_LOGIN_EMAIL plus ${BW_PASSWORD_ENV:-BW_MASTER_PASSWORD}
    • the helper is now host-globally single-flight guarded and throttle/backoff bounded through VW_BW_CHECK_LOCK_PATH, VW_BW_CHECK_STATE_PATH, and the VW_BW_CHECK_* interval/backoff variables
    • the repo-function sweep is authoritative for repo-local hardening and includes an explicit, opt-in live-gated subset The remaining operator guidance for drift and live verification is tracked in Gitea issues #28 and #29.

Bekannte Fehlerbilder​

  • bw nicht installiert
  • lokale Auth fehlt
  • access-model contract drift
  • inconsistent-upstream revision or namespace drift
  • Manifest-Drift zwischen Code und fabric-manifest.json
  • Shell-Syntax-/Line-Ending-Probleme

Restart / Recovery​

  • Da kein Daemon: erneuter CLI-Aufruf reicht meist
  • nur bw serve muss explizit neu gestartet oder beendet werden

Laufzeitabhaengigkeiten​

  • Python
  • bash
  • bw
  • Vaultwarden/Bitwarden-Backend

Betriebsluecken​

  • keine HTTP-Health-/Readiness-Surfaces
  • keine Metriken
  • keine zentrale Log-Aggregationsoberflaeche im Repo selbst
  • future write-governance auth remains documented only and is tracked in Gitea issue #30