Native guest runtimes

A workspace has one resource allocation and a default runtime. Most Linux images run directly in that runtime. An image can also boot a native system behind a small Linux bridge: the Mac image selects macOS as the default, so terminal, files, commands and workloads operate inside macOS.

Runtime selection uses the same API for every registered guest. There is no second CPU or memory configuration. Set config.cpus and config.memory_mb once. A driver derives the native system's resources at boot; the Mac driver exposes all assigned vCPUs and keeps an internal 2 GiB RAM reserve for Linux and QEMU, plus Linux kernel overhead.

Discover and select

In the dashboard, the terminal header shows a compact runtime picker when the image provides more than one runtime. It displays the current system beside a layers icon. Switching keeps each system's terminals separate and carries the selected runtime into Files. Ordinary single-runtime images have no picker.

const runtime = await client.workspace(workspaceId).runtime();
console.log(await runtime.targets());

// Omitted target follows the image's default runtime.
console.log(await runtime.info());

// The local runtime is the outer agent, useful for bridge diagnostics.
const bridge = runtime.forTarget('local');
await bridge.exec.run(['/usr/bin/uname', '-s']);
await bridge.files.list({ dirPath: '/var/log' });

GET /runtimes returns registered IDs, availability, native OS, protocol version and capabilities. IDs come from the image and need not name an operating system. default follows the image choice; local selects the outer agent. The Mac image registers macos and retains linux as an alias for local.

All selected-runtime HTTP APIs use /runtimes/{id} before their usual path, including WebSockets, SSE and application proxy traffic. For example, /runtimes/local/runtime reports the bridge and /runtimes/macos/runtime reports the Mac. The SDK applies these paths to files, commands, terminals, search, watchers, transfers and proxies automatically.

Commands and workloads

Task and workload requests accept an optional target. Omit it for the image's default, or select an ID returned by discovery:

{ "cmd": ["/usr/bin/uname", "-s"], "target": "local", "stream": false }

{ "name": "build", "command": ["/bin/zsh", "-lc", "./build.sh"], "target": "macos" }

Commands and paths use the selected system's syntax. A target persists with its workload through daemon restarts and cold workspace starts. Combined workload events and statistics include their runtime target. A command or mutation is never broadcast to multiple runtimes.

An invalid target, unavailable guest or incompatible protocol returns an error instead of executing in another system. Server controls, token rotation and workspace lifecycle stay with the bridge. The same public workspace credential authorizes selected runtime routes; rotation or disabling access closes active sessions across them.

Boot and compatibility

The image declares its guests and boot hooks. Normal creation waits for the native agent before starting configured workloads. wait_for_init: false can return earlier when no workloads or enabled runtime server require readiness. An optional ready_check can test an application after the runtime is ready and can select its own target.

Images without a guest registry keep their existing direct Linux path. They do not start a bridge proxy, additional agent or guest supervisor. The shared protocol currently has native Linux and Darwin implementations; another OS also needs its own runtime implementation and image driver.

Discovery and explicit targets require an image built with runtime protocol v1. Updating the host daemon or SDK does not replace agents inside existing immutable images. Default APIs remain compatible with older images. See macOS workspaces for Mac boot settings, prepared base images and cold-start behavior.