> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Machines

> Create isolated Linux runtimes for commands, files, services, agents, and desktop work.

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.

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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())
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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());
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine create --template base --timeout 300
  nullspace machine list
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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}"
  ```
</CodeGroup>

## 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

<CardGroup cols={2}>
  <Card title="Create, connect, and list" href="./create-connect-list">
    Launch machines, reconnect by ID, and paginate running or paused work.
  </Card>

  <Card title="Lifecycle" href="./lifecycle">
    Understand create, exec, hibernate, reusable snapshots, fork, and destroy.
  </Card>

  <Card title="Persistence" href="./persistence">
    Pause machines and resume paused state later.
  </Card>

  <Card title="Snapshots" href="./snapshots">
    Capture reusable baseline state and spawn independent machines from it.
  </Card>

  <Card title="Auto-resume" href="./auto-resume">
    Wake paused machines from SDK calls, HTTP, and WebSocket traffic.
  </Card>

  <Card title="Fork" href="./fork">
    Branch warm state into independent children.
  </Card>

  <Card title="Metrics and timeouts" href="./metrics-timeouts">
    Inspect resource usage and control timeout behavior.
  </Card>

  <Card title="Preview URLs" href="../networking/preview-urls">
    Expose HTTP and WebSocket services from inside a machine.
  </Card>
</CardGroup>

## What To Read Next

* Use [Commands](../commands/overview) to run work inside a machine.
* Use [Filesystem](../filesystem) to move data in and out.
* Use [Templates](../templates/overview) when setup should be reusable.
* Use [Template Warm Pools](../templates/warm-pools) when a custom template needs ready capacity before a burst.
* Use [Volumes](../volumes/overview) when data must outlive the VM.
* Use [PTY](../access/pty) or [SSH](../access/ssh) for human debugging.