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

# Welcome to Nullspace

> Composable machines for AI agents — on-demand microVM compute that agents create, scale, pause, resume, and fork.

Nullspace gives AI agents **composable machines**: on-demand Firecracker
microVMs with first-class lifecycle primitives, all driven from one Python SDK,
CLI, HTTP API, or MCP. This is what it looks like:

<Tabs>
  <Tab title="Run a command">
    ```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("echo 'hello from a microVM'", shell=True)
        print(result.stdout)

        machine.files.write("/workspace/app.py", "print('hi')\n")
        print(machine.commands.run("python3 /workspace/app.py", shell=True).stdout)
    ```

    Commands run inside an isolated VM with its own filesystem — see
    [Commands](./commands/overview) and [Filesystem](./filesystem).
  </Tab>

  <Tab title="Run code">
    ```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
    from nullspace import Machine

    with Machine.create(template="code-interpreter", timeout=300) as machine:
        machine.run_code("value = 21")                     # state persists
        result = machine.run_code("value * 2")
        print(result.results[0].text)                      # "42"

        machine.install_packages(["pandas"])
        machine.run_code("import pandas; print(pandas.__version__)")
    ```

    A live Jupyter kernel with stateful cells, runtime installs, and rich
    results — see [Code Interpreter](./code-interpreter/overview).
  </Tab>

  <Tab title="Expose a port">
    ```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
    from nullspace import Machine

    with Machine.create(template="base", timeout=300) as machine:
        machine.commands.run(
            "cd /workspace && python3 -m http.server 8080 --bind 0.0.0.0",
            shell=True, background=True,
        )
        print(machine.get_url(8080))   # signed public URL into the machine
    ```

    Any port becomes a signed public URL — see
    [Preview URLs](./networking/preview-urls).
  </Tab>

  <Tab title="Pause, resume & fork">
    ```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
    from nullspace import Machine

    machine = Machine.create(template="base", timeout=300)
    snapshot = machine.hibernate()          # full VM state, pauses billing
    machine = Machine.resume(snapshot.id)   # wakes exactly where it stopped

    child = machine.fork()                  # branch the *running* machine
    ```

    State survives exactly; wakes are near-instant via lazy memory loading —
    see [Persistence](./machines/persistence) and [Fork](./machines/fork).
  </Tab>
</Tabs>

<Note>
  **Private beta — signup is closed for now.** Public availability timing
  will be announced when capacity opens. If you have a beta key, you can be
  running these snippets in about five minutes: [create your first
  machine](./quickstarts/first-machine). The full stack is
  [open source](https://github.com/catamaran-research/nullspace) and can be
  [self-hosted on a single host](./quickstarts/self-hosted-single-host).
</Note>

## Get started

<CardGroup cols={3}>
  <Card title="First machine in 5 minutes" icon="rocket" href="./quickstarts/first-machine">
    Install the CLI, save your key, and run `nullspace quickstart`.
  </Card>

  <Card title="Copy a runnable example" icon="code" href="./examples">
    Code interpreter, agents, fork, templates, volumes, desktop, and more.
  </Card>

  <Card title="Self-host the OSS stack" icon="server" href="./quickstarts/self-hosted-single-host">
    Run the whole platform on one Ubuntu/KVM host.
  </Card>
</CardGroup>

## The lifecycle primitives

Everything in Nullspace builds on six explicit operations. Pause/resume and
fork are what set it apart: full VM state is preserved exactly, wakes use lazy
memory loading so they feel instant, and forks branch a *running* machine.

| Primitive                         | What it does                                                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| [Create](./concepts/create)       | Boot a fresh microVM from a template, image, or snapshot — or claim a pre-booted one from a [warm pool](./templates/warm-pools) |
| [Exec](./concepts/exec)           | Run commands and processes, stream output                                                                                       |
| [Hibernate](./concepts/hibernate) | Pause and persist full VM state                                                                                                 |
| [Resume](./concepts/resume)       | Wake exactly where it paused, near-instantly                                                                                    |
| [Fork](./concepts/fork)           | Branch a running machine into independent children                                                                              |
| [Destroy](./concepts/destroy)     | Tear down and release everything                                                                                                |

## Explore the platform

<CardGroup cols={2}>
  <Card title="Machines" icon="box" href="./machines/overview">
    The microVM lifecycle end to end.
    <br />[Create & connect](./machines/create-connect-list) ·
    [Persistence](./machines/persistence) ·
    [Fork example](./examples/fork)
  </Card>

  <Card title="Code Interpreter" icon="square-terminal" href="./code-interpreter/overview">
    Stateful notebook-style execution.
    <br />[Analyze data](./code-interpreter/analyze-data) ·
    [Charts](./code-interpreter/charts-overview) ·
    [Example](./examples/code-interpreter)
  </Card>

  <Card title="Agents" icon="bot" href="./agents/overview">
    Coding agents in machines, or your agent as a managed service.
    <br />[Deployments](./agents/deployments) ·
    [Local MCP](./agents/local-mcp) ·
    [Job example](./examples/agent-deployment-job)
  </Card>

  <Card title="Templates & warm pools" icon="layers" href="./templates/overview">
    Bake dependencies once; start instantly.
    <br />[Quickstart](./templates/quickstart) ·
    [Warm pools](./templates/warm-pools) ·
    [Build example](./examples/template-build)
  </Card>

  <Card title="Filesystem & volumes" icon="hard-drive" href="./filesystem">
    Machine files plus durable shared storage.
    <br />[Uploads](./filesystem/uploads) ·
    [Volumes](./volumes/overview) ·
    [Shared-volume example](./examples/shared-volume)
  </Card>

  <Card title="Networking" icon="globe" href="./networking/overview">
    Signed URLs, WebSockets, custom proxies.
    <br />[Preview URLs](./networking/preview-urls) ·
    [Access control](./networking/access-control) ·
    [Port example](./examples/port-forwarding)
  </Card>

  <Card title="Desktop" icon="monitor" href="./desktop/overview">
    GUI environments for agents and humans.
    <br />[Automation](./desktop/automation) ·
    [Viewer](./desktop/viewer) ·
    [Viewer example](./examples/desktop-viewer)
  </Card>

  <Card title="Observability & access" icon="activity" href="./observability/overview">
    Watch and debug long-running work.
    <br />[Lifecycle events](./observability/lifecycle-events) ·
    [Webhooks](./observability/webhooks) ·
    [SSH & PTY](./access/overview)
  </Card>
</CardGroup>

## Reference

<CardGroup cols={3}>
  <Card title="Python SDK" icon="terminal" href="./sdk-reference">
    One-page tour of the SDK surface, plus per-object references.
  </Card>

  <Card title="CLI" icon="chevron-right" href="./cli/installation">
    `nullspace` commands for machines, templates, volumes, and agents.
  </Card>

  <Card title="HTTP API" icon="braces" href="./api-reference">
    The full REST contract with an interactive playground.
  </Card>
</CardGroup>