Get Started

From zero to first approved job in 5 minutes

The fastest path is voxera demo. It bootstraps the queue, runs a sample job, and walks you through your first approval — no pre-configuration required. For complete run instructions, read the Operator Guide.

Fastest path

Run the demo

voxera — demo mode

$ voxera demo
✓ Queue initialized
✓ Daemon running
✓ Demo job queued — approval required
→ voxera queue approvals list   # review pending approval
→ voxera queue approvals approve <job_id>   # approve to run

voxera demo sets up everything in one command. No manual folder creation or config required. The demo walks you through a real queue + approval cycle.

Manual install

Install in 3 steps

Set up environment + install

python3 -m venv .venv && source .venv/bin/activate
pip install -U pip
pip install -e ".[dev]"

Requires Python ≥ 3.10. Run inside the VoxeraOS project directory.

Install services + verify

make update
make services-install
voxera --version
voxera queue status

Installs systemd user units and confirms the queue is healthy before proceeding.

Queue your first job + run

voxera inbox add "Write a daily check-in note"
voxera daemon --once
voxera queue approvals list

The daemon processes one job and stops. If an approval is needed, it shows up in approvals list.

After your first job runs

Review and approve

Approve a pending job

voxera queue approvals list
voxera queue approvals approve <job_id>
# or: approve permanently for this skill
voxera queue approvals approve <job_id> --always

Check what happened

voxera queue status
voxera queue health
# view artifacts for a job:
ls notes/queue/artifacts/<job_id>/

Each completed job has a structured bundle: plan, timeline, stdout, stderr, and generated file metadata.

Show full operator quickstart

Provider validation

voxera setup           # interactive wizard
voxera doctor          # validate provider endpoints
voxera doctor --quick  # fast local check (no model calls)

Config inspection

voxera config show      # redacted view
voxera config validate  # non-zero exit on errors
voxera config snapshot  # write audit snapshot

Queue bootstrap (manual)

voxera queue init
# or manually:
mkdir -p ~/VoxeraOS/notes/queue/{inbox,pending/approvals,done,failed,artifacts,_archive}

Artifact hygiene

# Dry-run preview
voxera artifacts prune --max-age-days 30
# Delete stale artifacts
voxera artifacts prune --max-age-days 30 --yes
# Clean terminal job buckets
voxera queue prune --max-age-days 30 --yes

Full queue lifecycle commands

voxera queue status
voxera queue approvals list
voxera queue approvals approve <job_id>
voxera queue approvals approve <job_id> --always
voxera queue approvals deny <job_id>
voxera queue cancel <job_id>
voxera queue retry <job_id>
voxera queue pause
voxera queue resume
voxera queue unlock            # safe: stale/dead locks only
voxera queue unlock --force    # override live lock (dangerous)
voxera queue health            # operator health snapshot
voxera queue reconcile         # report-only hygiene diagnostic

Next steps

Explore the operator reference

For contracts, hygiene commands, sandbox posture, and ops observability — read the Operator Guide. For full run instructions, see the README.

Operator Guide Features overview