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

# Build

> Choose the Nullspace primitive for isolated developer workflows.

Build is the developer surface for creating isolated runtime environments,
running work inside them, moving files, exposing services, and keeping state
when a workflow needs to continue. Start here when you know what you want to
build but are not sure which Nullspace primitive owns the job.

## Choose The Primitive

| Goal                                               | Start With                                      | Why                                                                                              |
| -------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Run code or install dependencies in a clean VM     | [Machines](./machines/overview)                 | Machines are the runtime boundary for commands, files, networking, desktop, and lifecycle.       |
| Execute commands, stream logs, or manage processes | [Commands](./commands/overview)                 | Commands are the process API inside a machine.                                                   |
| Read, write, upload, download, or search files     | [Filesystem](./filesystem)                      | Filesystem APIs are for machine-local paths such as `/workspace`.                                |
| Run notebook-style code with structured results    | [Code Interpreter](./code-interpreter/overview) | Code Interpreter adds stateful cells, artifacts, and language contexts.                          |
| Automate a browser or GUI app                      | [Desktop Environments](./desktop/overview)      | Desktop machines expose screenshots, input, windows, clipboard, viewer sessions, and recordings. |
| Avoid repeating setup on every machine create      | [Templates](./templates/overview)               | Templates turn setup steps or images into reusable machine environments.                         |
| Persist shared files outside VM memory             | [Volumes](./volumes/overview)                   | Volumes are durable filesystems that can mount into one or more machines.                        |
| Expose an HTTP or WebSocket service                | [Networking](./networking/overview)             | Preview URLs and WebSockets route traffic to services inside machines.                           |
| Track long-running work and lifecycle state        | [Observability](./observability/overview)       | Lifecycle events, webhooks, and monitor streams show what changed and why.                       |

## Common Workflows

| Workflow                                                      | Path                                                                                                         |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Create a machine, run a command, read a file, then destroy it | [Machines](./machines/overview) -> [Commands](./commands/overview) -> [Filesystem](./filesystem)             |
| Start a web app and share it with a signed URL                | [Commands](./commands/background) -> [Preview URLs](./networking/preview-urls)                               |
| Build a reusable Python or Node environment                   | [Templates](./templates/quickstart) -> [Template build](./templates/build) -> [Logging](./templates/logging) |
| Keep generated data across machine lifetimes                  | [Volumes](./volumes/overview) -> [Mounting volumes](./volumes/mounting-volumes)                              |
| Let an agent use a browser or desktop app                     | [Desktop automation](./desktop/automation) -> [Managed viewer](./desktop/viewer)                             |
| Debug a retained or long-running machine                      | [Monitor](./observability/monitor) -> [PTY](./access/pty) or [SSH](./access/ssh)                             |

## First Working Shape

Most Build workflows start with a machine and then opt into the primitives they
need:

```python 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)
    machine.files.write("/workspace/result.txt", result.stdout)
    print(machine.id, machine.files.read("/workspace/result.txt").strip())
```

Use a custom [Template](./templates/overview) when this setup becomes
repeatable, a [Volume](./volumes/overview) when output must outlive the VM, and
a [Preview URL](./networking/preview-urls) when a process inside the machine
needs inbound traffic.

## Build Areas

<CardGroup cols={2}>
  <Card title="Machines" href="./machines/overview">
    Create isolated runtimes and choose lifecycle behavior.
  </Card>

  <Card title="Commands" href="./commands/overview">
    Run foreground, streaming, and background work.
  </Card>

  <Card title="Filesystem" href="./filesystem">
    Move data in and out of machine paths.
  </Card>

  <Card title="Networking" href="./networking/overview">
    Expose services and connect over HTTP, WebSockets, or SSH.
  </Card>

  <Card title="Templates" href="./templates/overview">
    Build reusable environments for faster starts.
  </Card>

  <Card title="Volumes" href="./volumes/overview">
    Persist and share files outside VM memory.
  </Card>

  <Card title="Desktop Environments" href="./desktop/overview">
    Automate GUI workflows and supervise them in a viewer.
  </Card>

  <Card title="Observability" href="./observability/overview">
    Subscribe to lifecycle events, webhooks, and metrics.
  </Card>
</CardGroup>

## Related

* [First Machine](./quickstarts/first-machine)
* [Examples](./examples)
* [Python SDK](./guides/python-sdk/overview)
* [CLI](./guides/python-sdk/cli)