Voxera OS Join Waitlist

Operator Guide

Contracts, commands, and observability reference

A concise reference for operators running Voxera OS. Covers queue contracts, approval lifecycle, security posture, and hygiene commands. For complete run instructions, read the README.

Reference areas

What's in this guide

Architecture

Three-layer model + queue lifecycle

How Substrate OS, AI Control Plane, and Experience Layer relate to each other — and how jobs flow through the queue from inbox to outcome.

Read section →

Security model

Approval gating, audit artifacts, sandbox posture

How Voxera OS prevents unauthorized actions, records what happened, and isolates execution with rootless Podman.

Read section →

Ops commands

prune · reconcile · doctor · demo · bundle

The hygiene and observability commands operators use to maintain a healthy queue, diagnose failures, and package incidents.

Read section →

Roadmap

v0.1.6 planning — security + ops visibility

What's coming in the next release: panel auth hardening, health degradation signals, and ops visibility improvements.

View roadmap →

Ops contracts

Queue contract summary

Contract Rule
Job drop location notes/queue/inbox/*.json only. Legacy root drops are auto-relocated with an audit event.
Approval-required jobs Move to pending/ — never to failed. Explicit approve or deny required before processing continues.
Failed-job sidecars Written to failed/<job_stem>.error.json with schema_version, job, error, timestamp_ms.
Startup recovery Ambiguous jobs go to quarantine on daemon startup. Never silently re-run. Operator must clear quarantine manually.
Daemon lock Single-writer lock prevents concurrent daemon instances. Stale locks auto-cleared on safe startup; --force available.
Prune safety Always dry-run unless --yes is passed. Reconcile is always report-only and never modifies state.

Security model

Approval gating, audit, and sandbox

Approval gate

  • Skills declare their scope and network needs. Policy decides allow, ask, or deny at runtime.
  • Approval artifacts include policy reason, scope, and are written to pending/approvals/*.approval.json.
  • Approve once or approve-always per skill. Deny moves the job to failed with full audit record.

Audit artifacts

  • Per-job bundles under notes/queue/artifacts/<job_id>/ include plan, action timeline, stdout/stderr, and generated file metadata.
  • Failed-job sidecars carry schema-versioned error details — reader uses explicit supported-version allowlist.
  • Incident bundles: voxera ops bundle system packages queue state + artifacts for handoff.

Sandbox posture

  • Rootless Podman: no root required. Read-only root filesystem with --read-only.
  • Network disabled by default (--network=none) unless explicitly requested and policy-approved.
  • Writable mount limited to ~/.voxera/workspace/<job_id> as /work — no cross-job filesystem access.

Capabilities snapshot

  • Vera operates within a declared capability snapshot — she can't use tools or network access not permitted by operator policy.
  • Config snapshot: voxera config snapshot writes an audit-ready view of active configuration.
  • All sensitive values are redacted in voxera config show — secrets never appear in CLI output.

Ops commands

Hygiene, observability, and diagnostics

Artifact + queue hygiene

# Dry-run preview (safe, no changes)
voxera artifacts prune --max-age-days 30

# Delete entries older than 30 days
voxera artifacts prune --max-age-days 30 --yes

# Keep newest 50, prune the rest
voxera artifacts prune --max-count 50 --yes

# Prune terminal job buckets (done/failed/canceled)
voxera queue prune --max-age-days 30 --yes

# Report-only hygiene diagnostic
voxera queue reconcile

Observability + diagnostics

voxera queue health    # paused flag, lock, counters
voxera queue status    # live bucket counts
voxera doctor          # provider endpoint validation
voxera doctor --quick  # fast local check (no model calls)

# Panel (browser)
voxera panel
# http://127.0.0.1:8844/jobs?bucket=all&n=80

Incident bundles

voxera ops bundle system
voxera ops bundle job job-123.json

# Combined handoff folder
voxera ops bundle system \
  --dir notes/queue/_archive/INCIDENT-001
voxera ops bundle job job-123.json \
  --dir notes/queue/_archive/INCIDENT-001

Demo + validation

# Run end-to-end demo
voxera demo

# Validate before merge
make merge-readiness-check

# Broader local validation
make full-validation-check

The demo flow validates queue init, daemon reliability, and approval gating in a single command.

Next

See what's coming in v0.1.6

Panel auth hardening, ops health dashboard, and health degradation signals — the next stability milestone before broader expansion.

View Roadmap Feature details