Quickstart

This page takes an existing Vite app to a working Userspace VM: one file written into the VM’s workspace and read back by a Linux program. It takes about five minutes.

Local development needs no account or token. Before publishing this app, register a public license and pass its token as runtime.license.

1. Install the SDK.

   npm install @oxidevm/sdk

   The package holds no engine. The engine and the default Linux image load from the hosted runtime frame, so there is nothing else to install or serve.

2. Serve with the right headers. The engine needs a cross-origin isolated page, so every response needs two headers. In Vite:

   vite.config.ts

   import { defineConfig } from "vite";
   
   const headers = {
     "Cross-Origin-Opener-Policy": "same-origin",
     "Cross-Origin-Embedder-Policy": "require-corp",
   };
   
   export default defineConfig({
     optimizeDeps: { exclude: ["@oxidevm/sdk"] }, // keeps the SDK's worker URLs intact
     worker: { format: "es" },
     server: { headers },
     preview: { headers },
   });

   Restart the dev server, open your app and check that crossOriginIsolated is true in the browser console.

3. Create your first VM. Call createVM from browser code, never during server rendering:

   src/main.ts

   import { createVM } from "@oxidevm/sdk";
   
   const vm = await createVM({ mode: "userspace", runtime: { hosting: "frame" } });
   try {
     await vm.workspace.writeText("hello.txt", "Hello from Linux\n");
     const result = await vm.exec({ command: "cat", args: ["hello.txt"] });
     console.log(new TextDecoder().decode(result.stdout), result.exit);
   } finally {
     await vm.dispose();
   }

   runtime: { hosting: "frame" } runs the engine in a hidden frame from https://run.oxidevm.dev, which also serves the default image.

   Run the same two steps on this page’s own VM:

   Write a file, read it backUserspaceNot startedRun againStop

   Hello from Linuxexit: {"kind":"exited","code":0}

   Run this exampleDownloads Linux into this tab when you click.

What you have now

• vm.workspace reads and writes files under /workspace in the VM. See Workspace files.
• vm.exec runs a short command and returns its output and exit status. See Run commands.
• result.exit is { kind: "exited", code } or { kind: "signaled", signal, signalNumber }. A non-zero exit code is a normal result, not an error.
• Your site serves only your app. Deploying covers the headers on your host, a Content Security Policy, and serving the engine yourself.

Next, open an interactive terminal or decide between Userspace and System.