Choosing a mode

Every VM runs in one of two modes, and createVM requires you to name it. Both run real x86-64 Linux programs on the same engine. They differ in what sits under those programs.

	Userspace	System
`mode`	`"userspace"`	`"system"`
What runs	Linux programs, with the SDK providing Linux behavior directly	An unmodified Linux kernel, which then runs the programs
Start	A shell is ready almost at once	Linux boots first
Image	A default image with a shell, Node.js and npm	An image you build with its own kernel
Virtual CPUs	Not applicable	1
Typed result	`UserspaceVM`	`SystemVM`

Use Userspace when

your users need a shell, Node.js or other Linux programs quickly, for example in a tutorial, a coding example or a code playground;
the programs are ordinary userspace software: compilers, interpreters, package managers, dev servers;
start time matters more than kernel features.

Use System when

the software needs a real kernel: an init system, kernel-level networking or exact kernel behavior;
you want to boot an existing Linux system image that you build and host yourself;
your users should see a complete machine, boot messages included.

Naming the mode

import { createVM } from "@oxidevm/sdk";

const userspace = await createVM({ mode: "userspace" }); // UserspaceVM
await userspace.dispose();

const system = await createVM({ mode: "system" }); // SystemVM
await system.dispose();

The return type follows the mode, so options and members that exist in only one mode are checked by TypeScript. For example initialUser and rootPersistence are Userspace options, and vcpus is a System option.

What stays with a mode

Workspaces, images and restore points belong to the mode that made them. A restore point captured in Userspace can’t be restored into System; that fails with detail.reason "runtime-mismatch". Keep the mode with any workspaceId you store.