Skip to main content
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

NeedMachine Pattern
Run untrusted or dependency-heavy codeCreate a short-lived machine with a timeout and destroy it after collecting output.
Keep a repo or service warm between requestsUse hibernate, pause, or auto-resume instead of rebuilding state.
Start many machines from one ready custom templateUse a template warm pool with explicit checkout mode.
Branch from a known setupCreate a snapshot or fork a warm machine.
Give an agent a workspaceStart from an agent, desktop, code-interpreter, or custom template.
Debug failed workRetain 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())

​
Core Model

ConceptWhat It Means
TemplateThe base environment used at create time. Use base for general work or a custom template for repeated setup.
Template warm poolReady capacity for a template. A checkout becomes a normal machine and is not recycled.
Machine IDThe 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.
TimeoutControls what happens when work is idle or runs too long.
LifecycleMachines 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.