Examples

Each example is a small browser app or module in the examples directory of the oxidevm-sdk repository. Its README lists what it needs to run, such as the image to stage.

hello-files

Pick Userspace or System, open a VM, run /bin/sh, write and read a text note and a binary file, list and remove files, and reopen a persistent workspace by its ID. The page shows the running image’s identity and the workspace’s persistence, and makes startup cancellation and disposal explicit.

• Mode: Userspace and System
• APIs: createVM with workspaceId, image, signal and onProgress; defineImage; vm.exec; vm.workspace (writeText, readText, writeFile, readFile, list, remove, persistence); vm.image; vm.dispose

terminal

Two interactive shells on real pseudo-terminals in one VM, sharing /workspace. Typing, pasting and resizing reach the guest, Ctrl+C interrupts the foreground program, and closing one terminal leaves the other running. A pipe example shows separate stdout and stderr and exit code 7.

• Mode: Userspace and System
• APIs: vm.spawn with terminal; TerminalHandle (stdin, output, resize, interrupt, kill, exit); vm.exec; vm.dispose

next-workbench

A React app that edits the files of a project in /workspace, installs its dependencies and runs its development, build and start scripts, streaming their output. It lists the guest’s listening ports, shows port 3000 in a preview iframe, keeps the server handle for its Stop button, and opens a guest terminal. Its README describes the image it needs and the current state of the guest workflow.

• Mode: Userspace and System
• APIs: createVM with preview, network and memoryMiB; vm.workspace (list, readText, writeText); vm.spawn; vm.watchListeningPorts; vm.exposePort and PreviewHandle.close

python-image

A custom Userspace image that contains Python and no Node.js, built from an OCI Python image with oxidevm image build. The app computes the count, sum and mean of a CSV file in guest Python, saves the input and results in the workspace, reports a Python syntax error and keeps working after it.

• Mode: Userspace
• APIs: UserspaceImageRecipe; oxidevm image build, image test and assets install --image --reference; createVM with a generated image reference; vm.exec with cwd; vm.workspace (writeText, readText, list)

system-lab

Three pages around a small signed System image. /state works with restore points: capture, restore with undo, rename and delete, app data, reattaching a restored process, backup export, inspection and import, storage usage, automatic saves, and suspend and resume. /raw boots supplied kernel and disk bytes and shows the console. /diagnostics opts in to bounded tracing.

• Mode: System
• APIs: createVM with restorePoint; vm.snapshots (capture, list, restore, rename, delete, usage, setAppData, observe, autoSave, export, inspect, import); vm.start.terminals and attach; vm.suspend; bootMachine from @oxidevm/sdk/machine; getDiagnostics from @oxidevm/sdk/diagnostics

snapshot-authoring

Three source-only recipes for prepared starts, built and checked with the CLI. basic leaves an interactive shell holding a random value on the default Userspace image. next runs an offline frozen install and build, then keeps a Next.js development server running, on a Userspace image you build. linux-tool runs a static BusyBox program on a System image you build and leaves its shell running. Each verification reattaches the original processes and checks their state.

• Mode: Userspace and System
• APIs: SnapshotRecipe, PrepareSnapshot and VerifySnapshot; oxidevm snapshot build, snapshot test and snapshot inspect; oxidevm assets install --snapshot; createVM with shippedSnapshot and restorePoint: "latest"

js-process

A trusted JavaScript worker that runs as a Linux process. It writes a file in the workspace, starts BusyBox nc as a native child process, exchanges TCP data with it through Linux sockets and waits for its exit.

• Mode: Userspace
• APIs: vm.spawnJS; serveProcess from @oxidevm/sdk/js-process with its files, sockets and process operations

container-mounts

A standalone example app. It opens a Userspace VM as root with persistent system files, starts the example’s own guest scripts, which prepare Docker and open a container, attaches a terminal to the container shell, and can restart the example. You supply the signed image with the example’s files; its README lists what that image must contain.

• Mode: Userspace
• APIs: createVM with initialUser: "root", commandInterceptors: "off", rootPersistence: "persistent", limits.maxProcesses, memoryMiB and runtime; defineImage; vm.spawn with and without terminal; vm.exec; vm.dispose

acceleration

A buildProject(image) function that opens a Userspace VM with commandInterceptors: "auto", runs bun run build in /workspace, and returns its output and exit. It needs an image with an acceleration profile and the runtime setup that acceleration requires.

• Mode: Userspace
• APIs: createVM with commandInterceptors; vm.spawn; ProcessHandle streams; vm.dispose