Machines

A machine is the runtime boundary in Nullspace. It owns a VM, filesystem, process namespace, network routing, lifecycle state, and optional capabilities such as desktop access or mounted volumes. Most Build workflows start by creating a machine and then using commands, files, networking, or lifecycle APIs against that machine ID.

When To Use Machines

Need	Machine Pattern
Run untrusted or dependency-heavy code	Create a short-lived machine with a timeout and destroy it after collecting output.
Keep a repo or service warm between requests	Use hibernate, pause, or auto-resume instead of rebuilding state.
Start many machines from one ready custom template	Use a template warm pool with explicit checkout mode.
Branch from a known setup	Create a snapshot or fork a warm machine.
Give an agent a workspace	Start from an agent, desktop, code-interpreter, or custom template.
Debug failed work	Retain the machine and inspect it with commands, PTY, SSH, files, or desktop viewer.

Quick Example

The SDK, CLI, and HTTP snippets below are alternative control planes. Use one path end-to-end unless you are intentionally passing a machine ID between tools.

from nullspace import Machine

with Machine.create(template="base", timeout=300) as machine:
    result = machine.commands.run("python3 --version", shell=True)
    print(machine.id, result.stdout.strip())

import { Machine } from "nullspace";

await using machine = await Machine.create({ template: "base", timeout: 300 });
const result = await machine.commands.run("python3 --version", { shell: true });
console.log(machine.id, result.stdout.trim());

nullspace machine create --template base --timeout 300
nullspace machine list

curl -X POST "${NULLSPACE_API_URL}/v1/machines" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"template": "base", "timeout_ms": 300000}'

curl "${NULLSPACE_API_URL}/v1/machines" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

Core Model

Concept	What It Means
Template	The base environment used at create time. Use `base` for general work or a custom template for repeated setup.
Template warm pool	Ready capacity for a template. A checkout becomes a normal machine and is not recycled.
Machine ID	The handle for commands, files, preview URLs, metrics, lifecycle, PTY, and SSH.
Workdir	`/workspace` is the default mutable work tree for repo-style and agent workflows.
Timeout	Controls what happens when work is idle or runs too long.
Lifecycle	Machines can be created, paused, hibernated, resumed, forked, snapshotted, and destroyed.

Common Tasks

Create, connect, and list

Launch machines, reconnect by ID, and paginate running or paused work.

Lifecycle

Understand create, exec, hibernate, reusable snapshots, fork, and destroy.

Persistence

Pause machines and resume paused state later.

Snapshots

Capture reusable baseline state and spawn independent machines from it.

Auto-resume

Wake paused machines from SDK calls, HTTP, and WebSocket traffic.

Fork

Branch warm state into independent children.

Metrics and timeouts

Inspect resource usage and control timeout behavior.

Preview URLs

Expose HTTP and WebSocket services from inside a machine.

Get started

Commands

Filesystem

Code Interpreter

Desktop

Templates

Volumes

Networking

Interactive access

Observability

Machines

When To Use Machines

Quick Example

Core Model

Common Tasks

Create, connect, and list

Lifecycle

Persistence

Snapshots

Auto-resume

Fork

Metrics and timeouts

Preview URLs

What To Read Next

​When To Use Machines

​Quick Example

​Core Model

​Common Tasks

Create, connect, and list

Lifecycle

Persistence

Snapshots

Auto-resume

Fork

Metrics and timeouts

Preview URLs

​What To Read Next

When To Use Machines

Quick Example

Core Model

Common Tasks

What To Read Next