OrpheOS / Documentation
OrpheOS docs.
Research workflows, native execution, and the system beneath them.

01 / Get OrpheOS
Run
OrpheOS.
Use the launcher included with a packaged QEMU desktop. It keeps the OS image separate from your persistent workspace.
Launch a QEMU bundle
The current launcher uses Python 3.8+ and qemu-system-aarch64 on Linux or macOS. Install QEMU through its official download instructions. The guest uses 2 GiB of RAM and a sparse 64 GiB workspace disk; host storage grows as data is written.
For bundles containing run_preview.py, extract the complete package and run these commands from its directory:
qemu-system-aarch64 --version
python3 -B run_preview.py --dry-run
python3 -B run_preview.py
--dry-run checks the bundle and workspace state without writing or launching. It does not test QEMU or verify a successful boot. Use the package’s README for its exact requirements.
On WSL or headless Linux, launch with VNC and connect a local viewer to 127.0.0.1:5901:
python3 -B run_preview.py --display vnc
To create a separate workspace, choose a new state directory whose parent already exists:
python3 -B run_preview.py --state-dir /absolute/path/to/new-orpheos-state
Save your work and wait for confirmation before stopping QEMU. Keep the original package, working disk, and ownership record together.
Resolve a launcher error
If QEMU is outside your PATH, pass --qemu /absolute/path/to/qemu-system-aarch64. For a display error, use an installed backend or --display vnc.
A run-lock error can mean another emulator is using the workspace. Check for that process before recovery. If ownership verification fails, preserve the refused state and its ownership record.
02 / Research
From a question
to evidence.
Connect questions, hypotheses, runs, and conclusions in one saved graph. Each execution gets its own attempt and recorded outcome. Choose Show guide for the built-in walkthrough.
- Choose Add record, then Question, write your question, then Add question.
- With the Question selected, choose Add hypothesis. Add your proposed answer; its connection is created automatically.
- Select the Hypothesis and choose Set up a run. Choose Advanced method, enter
affine 2 1 -4,0,5, then Add run. - Choose Save to run. Wait for confirmation, then choose Run. This example produces
[-7, 1, 11]. - Inspect the result, choose Add conclusion, write what you learned, choose Add conclusion again, then Save.
Saving and running are separate actions. Add or discard an unfinished draft before either. Revise adds a linked correction and keeps the original record.
Summarize a CSV file
Save /data.csv with 1 and 3 on separate lines. Select a Hypothesis, choose Set up a run, and use CSV summary.
Set CSV file path to /data.csv, Column to 1, and First row is header to No. Choose Add run, then Save to run, then Run.
The mean is 2, population variance is 1, and sample variance is 2. The exact input snapshot is saved with the attempt, so later file edits do not change that result.
CSV input accepts up to 8 KiB, 128 records including the header, and eight columns. Missing cells are excluded and counted; invalid numbers in the chosen column stop the run.
Inspect, compare, and share results
Select a saved Run to see its latest result and whether it belongs to the current or an earlier graph. Next and Prev browse output. Native stdout and stderr remain distinct, and saved output is verified before display.
Compare examines two saved attempts. Export, Import, and Inspect handle experiment packages. Export to a new root-level filename. Importing or inspecting a package does not execute it.
History holds eight attempts, including failures and interruptions. A Run record ID and an attempt ID identify different things. Not saved means a result is not yet part of confirmed history.
research-list
research-show ATTEMPT_ID
research-output ATTEMPT_ID PAGE
research-compare A B
Move through the graph
Use 1 for Graph, 2 for Timeline, and 0 to fit the graph. Drag to pan and scroll to zoom. Up/Down selects a record; Enter opens its details; Esc returns to the graph.
Back keeps an unfinished draft. Resume draft returns to it. Help or ? shows the controls. The guide’s Next advances its instructions; use the app controls to perform each step.
03 / Native programs
Give work
its own space.
Run a saved program in a fresh execution domain, with explicit input and a resource budget. The supervisor collects its result and reclaims its private resources before reporting completion.
Use trusted programs built for the OrpheOS native command ABI as static AArch64 executables. This interface defines the entry point, arguments, input, output, and exit protocol; language runtimes must support that contract.
Run a native program in Research
With your saved executable at /program, select a Hypothesis, choose Set up a run, then Advanced method, and enter:
native-trusted /program
Choose Add run, Save to run, then Run. This method supplies the program path as its sole argument, without stdin. Select the Run to inspect its outcome and saved output.
Native Research output has a combined stdout/stderr budget of 24,576 bytes across at most eight saved chunks. Smaller writes can reach the chunk limit first. The two-second deadline includes time spent saving output.
A failed or interrupted run is not retried automatically. Captured and saved byte counts can differ when storage fails; use the recorded outcome to interpret incomplete output.
Invoke a program directly
run /program ARGUMENT
Direct invocations accept up to 16 arguments including the program path, 3,072 bytes of stdin, and 3,072 combined stdout/stderr bytes. The executable must fit within 128 KiB, and execution has a two-second deadline.
Input is fixed for the lifetime of the invocation. Programs receive output and heap-service capabilities; file, network, and device access are not granted by this command interface.
Ctrl+C requests cancellation of the active program. Wait for its final status: a cancellation request alone does not confirm resource cleanup.
04 / Workspace & data
Know what
is saved.
Your workspace is stored separately from the OS image. Research resumes /research.orp and its saved run history on first opening after startup. Reopening the app keeps your current work; Open reloads the saved version.
- Saved research
- The graph, recorded attempts, CSV input snapshots, and confirmed native output remain in the workspace.
- Revisions
- Research corrections retain their originals. File saves check the stored revision before publishing a complete replacement.
- Session state
- Unsaved drafts and transient output disappear at restart. Wait for save confirmation before closing the VM.
Workspace ownership and recovery
Keep the original package, working disk, and ownership record together. The launcher checks ownership against that exact disk; copying the files does not create a new valid workspace. Use a new state directory for an independent workspace.
If a save reports an unknown outcome, preserve the disk, restart, and reopen the saved state. Repeated saves or reformatting can destroy the evidence needed to determine what was stored.
If Research reports that its file already exists, open the existing workspace before saving. A result marked Not saved is not confirmed history.
05 / Architecture
seL4
and Rust.
seL4 controls access to memory and kernel objects, with IPC, interrupts, and scheduling. Rust services handle display, input, files, and storage I/O.
The root supervisor starts services and assigns their resources. CPython, musl, and the transformer’s numerical code connect through native-library interfaces.
Device services
Drivers receive assigned registers, interrupts, and buffers. Platform components provide PCI/PCIe discovery, ACPI and ECAM parsing, and Intel VT-d DMA domains. CPU mappings, device DMA, and GPU address spaces have separate permissions and lifetimes.
06 / Security
Secure
by default.
Each service has a separate capability space and virtual address space. The supervisor grants the endpoints, mappings, interrupts, and shared pages required for its role. Desktop application views share the display service.
Filesystem services verify callers through kernel-delivered endpoint badges. Owner and reader permissions control file access; directory traversal is checked.
Desktop native jobs start in fresh execution domains with read-only input pages. Executable loading enforces segment permissions, rejects pages that are both writable and executable, and leaves stack guards unmapped. The supervisor reclaims private resources after completion, cancellation, or faults.
07 / Native intelligence
Native
intelligence.
The CPU inference profile runs a Llama-family transformer under seL4. Its Rust GGUF loader checks model layouts, tensor ranges, vocabulary, finite weights, and allocation budgets before execution.
An isolated worker retains the model and attention state across bounded generation steps. BEGIN starts a session, STEP advances it, and RESET clears the session state.
Runtime and numerical validation
The runtime combines a tokenizer, owned model weights, a budgeted attention cache, and deterministic sampling with the numerical forward pass from llama2.c.
The isolated-worker TinyStories check compared 73,216 logits across 143 forward steps. Every selected token matched the independent upstream reference, with logits within the test’s numerical tolerance. This checks execution correctness; it does not measure answer quality.