Voxera OS Get on GitHub

Get Started · v0.1.9

Submit your first governed job in 5 minutes

The fastest path is voxera demo. It starts services, queues a sample job, walks you through your first approval, and lets you inspect the artifact — 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

1

Clone and set up

cd ~
git clone https://github.com/SeedOfEvil/VoxeraOS.git
cd ~/VoxeraOS
python3 -m venv .venv && source .venv/bin/activate
pip install -U pip
pip install -e ".[dev]"

Requires Python ≥ 3.10 and Git. Clones VoxeraOS to your home directory and installs in a virtual environment.

2

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.

3

Submit a governed job and run

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

The daemon processes one queue job and stops. If approval is required, the job waits in pending approvals. Approve it, run again, and inspect the artifact.

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 on GitHub.

Operator Guide View on GitHub