Userspace

Developer image

motor-os-dev.qcow2 is the standard image plus everything needed to build and test programs inside the VM: native C, C++, and Rust compilers, Lorry, Gears, curl, Lua, mdbg, the test suites, and source snapshots. It is 4 GB and is normally started with run-dev.sh (8 vCPUs, 8 GiB).

Layout

Path	Contents
`/devtools/bin`	`cc`, `c++`, `rustc` (launcher scripts), `lorry`, `gears`, `mdbg`, `lua`, and `www`, the script that serves this website. On `PATH`.
`/devtools/llvm`	The LLVM multicall binary (clang, lld, and the tools), headers, and static libraries: mlibc, libc++, libc++abi, libunwind, compiler-rt, and the C ABI shim over the runtime.
`/devtools/rust`	Native rustc with a full `x86_64-unknown-motor` sysroot. There is no cargo on the image; Lorry is the build driver.
`/devtools/src`	Writable workspace with sample sources (`hello.c`, `hello.cpp`, `hello.rs`) and snapshots of red, lorry, gears, moto-rt, and moto-sys, so that those can be rebuilt natively.
`/devtools/tests`	`systest`, `mio-test`, `tokio-tests`, `crossterm-smoke`, `crossbench`, `rnetbench`, and `gears/gears-mock-provider`.
`/devtools/tmp`	Build and test scratch, writable by every role.
`/devtools/cfg`, `/devtools/lorry`	Clang driver configuration and Lorry's installed state.
`/system/bin/curl`	A curl-compatible HTTPS client, the network tool Lorry uses to fetch crates.

/devtools itself is System-owned; Interactive sessions write under /devtools/src and /devtools/tmp, and may edit the launcher scripts in /devtools/bin in place but not add or remove entries there.

Compiling natively

cd /devtools/src
cc hello.c -o /devtools/tmp/hello && /devtools/tmp/hello
c++ hello.cpp -o /devtools/tmp/hello-cpp && /devtools/tmp/hello-cpp
rustc hello.rs -o /devtools/tmp/hello-rs && /devtools/tmp/hello-rs

The compilers target x86_64-unknown-motor, a real Clang target whose defaults are emulated TLS and static position-independent executables, so no special flags are needed. What the C library and libc++ support is on the C/C++ on Motor OS page; the compilers, their sysroots, and Lorry are described on the Toolchains page.

Lorry

Lorry is Motor OS's Rust package manager: a smaller, stricter Cargo replacement for security-sensitive environments. It is Cargo-compatible, taking a package's Cargo.toml and Cargo.lock as they are and aiming for byte-identical binaries, but it builds offline, from dependencies that were fetched once, checked, and approved explicitly by lorry vendor, and code that runs at build time (build scripts, procedural macros) needs a recorded grant. It never invokes Cargo, and it is the Rust build driver on the developer image, which has no Cargo.

lorry new hello
cd hello
lorry vendor --accept-all   # once, with network access
lorry build --release
lorry run

The full description, including the admission policy, the configuration files, and how procedural macros and build scripts run on Motor OS, is on the Lorry page.

Gears

Gears is a small, extensible agent harness for working with a language model from the terminal, on Linux and on Motor OS. Its core owns provider streaming, one agent loop, cancellation, sessions, a full-screen and a line-mode UI, command hooks, and one built-in tool, sh, which runs a command through /system/bin/rush -c in the selected workspace. It does not prescribe a coding workflow.

gears --model provider/model
gears -p "answer once" --model provider/model

Configuration is /user/cfg/gears.toml: an OpenAI-compatible base_url (OpenRouter by default), the model, a key file, an optional egress allowlist, timeouts, and context-window limits. Permission hooks run before every tool call; any deny wins, then any allow, otherwise an attended session asks. The sh tool is not a sandbox: an approved command has the same filesystem authority as Gears. Sessions are append-only JSONL trees under /user/cfg/gears/sessions/, with --continue, --resume, --fork, and in-session /new, /resume, /fork, /tree, and /compact. gears-mock-provider, installed under /devtools/tests/gears/, is a deterministic local TLS provider so that Gears can be tested without an Internet provider.

mdbg

mdbg print-stacks PID pauses a process through the kernel's debug interface and prints the stack of every thread as raw addresses, to be symbolized on the host with addr2line. It is not a breakpoint or source-level debugger; it is the tool for finding out where a hung process is. See Logs and diagnostics.

Test suites

Binary	Covers
`systest`	The main acceptance suite, about forty modules: filesystem and permissions, locks, TCP, UDP, ICMP, TLS, DNS, I/O channels, threads and channels, poll, stats, logging, Ctrl+C, spawn/wait/kill, stdio and terminal behavior, the sysbox applets, memory admission and pressure. Ends with `systest: ALL PASS`.
`mio-test`	The mio port: TCP, UDP, poll, and wakers.
`tokio-tests`	The Tokio runtime and process tests.
`crossterm-smoke`	The crossterm backend: keys, screen, and panic restore, under rmux and over plain SSH.
`crossbench`	A filesystem read benchmark.
`rnetbench`	A TCP throughput benchmark: `rnetbench -s -p PORT` in the VM, `rnetbench -c host:port` on the host.

On the host, src/tests/full-test.sh builds the images, runs the host-side unit tests, boots VMs for the console and terminal legs, and then drives the suites above over SSH in one QEMU VM; full-test-dev.sh does the same against the developer image and adds the native-toolchain and Lorry legs. stress-soak.sh keeps one VM busy with concurrent looping workloads and collects forensics if something stalls.

Serving this website

/devtools/bin/www starts httpd-axum on port 443 with the shipped test certificate, serving /devtools/www, the directory these pages live in. Edit the script to serve plain HTTP with httpd instead.