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

# Agents on Nullspace

> Four ways agents use Nullspace: local MCP tools, in-machine workspaces, managed deployments, and framework integrations.

Nullspace gives agents isolated compute, files, networking, terminals, and
desktop environments. There are four integration paths — the right one depends
on **where the reasoning loop runs** and **whether Nullspace should operate a
named project for you**.

<CardGroup cols={2}>
  <Card title="Local MCP" icon="plug" href="./local-mcp">
    Your coding agent stays on your machine (Codex, Claude Code, Cursor,
    VS Code) and drives Nullspace through MCP tools.
  </Card>

  <Card title="Agent workspaces" icon="box" href="./codex">
    The coding agent itself runs *inside* a machine — isolated filesystem,
    package installs, terminal, git, optional desktop.
  </Card>

  <Card title="Agent deployments" icon="rocket" href="./deployments">
    Your agent project becomes a named, versioned `job` or `service` that
    Nullspace runs, logs, and cleans up.
  </Card>

  <Card title="Framework integrations" icon="puzzle" href="./openai-agents-sdk">
    Nullspace as a tool inside your app (OpenAI Agents SDK, LangChain) — or
    your framework app deployed onto Nullspace (Claude Agent SDK, LangGraph,
    CrewAI).
  </Card>
</CardGroup>

## Which path fits?

| You want to…                                                            | Use                                                                                                             | Tradeoff to know                                                                  |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Let a local coding agent create machines, run commands, and fetch files | [Local MCP](./local-mcp)                                                                                        | The agent stays on your machine; only the work it launches runs isolated.         |
| Put the coding agent itself in an isolated Linux workspace              | [Codex](./codex), [Claude Code](./claude-code), [Amp](./amp), or [OpenCode](./opencode)                         | Provider credentials enter the machine environment.                               |
| Operate a repeatable agent app with runs, logs, outputs, and cleanup    | [Agent deployments](./deployments)                                                                              | The app must fit the deployment contract: bundle, install, entrypoint, env, mode. |
| Expose machine operations as one tool in a larger agent app             | [OpenAI Agents SDK](./openai-agents-sdk), [LangChain](./langchain), or [bring your own](./bring-your-own-agent) | Your app owns retries, tool schemas, and framework state.                         |
| Run a framework app as the managed process itself                       | [Claude Agent SDK](./claude-agent-sdk), [LangGraph](./langgraph), or [CrewAI](./crewai)                         | Nullspace owns runs and machines; the framework owns sessions and checkpoints.    |
| Give an agent a browser or GUI                                          | [Desktop environments](../desktop/overview)                                                                     | —                                                                                 |
| Let a human inspect the same machine                                    | [PTY](../access/pty), [SSH](../access/ssh), or [retained machines](../access/debug-retained-machines)           | —                                                                                 |

Two notes that save confusion later:

* **Live deployment modes are `job` and `service`.** Other mode names you may
  see referenced (`worker`, `triggered`, `workspace`, `interactive`) are
  reserved for future models — they are not live.
* **Nullspace run IDs are not conversation sessions.** Framework session,
  thread, checkpoint, and flow state stays app-owned. Use
  [volumes](../volumes/overview), retained machines,
  [hibernate/auto-resume](../machines/auto-resume), or an external database
  when state must outlive one machine process.

## The object model

Whichever path you pick, the same building blocks apply — see
[Agent primitives](./primitives) for the full model:

| Primitive              | What it means                                                               |
| ---------------------- | --------------------------------------------------------------------------- |
| Machine workspace      | The isolated VM: commands, files, networking, PTY, SSH, desktop, volumes.   |
| Agent project          | A local directory with your app, `nullspace.agent.toml`, and an entrypoint. |
| Deployment             | A named, uploaded project runnable as a `job` or `service`.                 |
| Run / service instance | One concrete execution, with logs, status, outputs, and a backing machine.  |
| Framework state        | Sessions, threads, checkpoints, memory — owned by your app, not Nullspace.  |

## Start with an example

<CardGroup cols={3}>
  <Card title="Minimal job" icon="play" href="../examples/agent-deployment-job">
    Deploy and run a small project end to end.
  </Card>

  <Card title="HTTP service" icon="server" href="../examples/agent-deployment-service">
    A long-running agent service with a public URL.
  </Card>

  <Card title="Workspace checks" icon="bot" href="../examples/agent">
    Clone a repo in a machine and run checks like an agent.
  </Card>
</CardGroup>