> ## 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. # Agent Primitives > Understand the objects behind agent workspaces and Agent Deployments. Nullspace keeps the agent model small: a machine is the runtime boundary, and an Agent Deployment is a named way to run a local project inside that boundary. Framework sessions, memory, checkpoints, traces, and approvals remain owned by your application or framework. ## Two Ways Agents Use Nullspace | Shape | What Runs In Nullspace | Typical Owner | | ------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | Direct machine workspace | Commands, files, PTY, SSH, desktop, templates, volumes, and preview services. | Your app, CLI script, local MCP agent, or in-machine coding agent. | | Agent Deployment | A bundled local project with install and entrypoint metadata. | Nullspace operates the deployed job or service; your app owns framework state. | Use direct machines when you need fine-grained command and file control. Use [Agent Deployments](./deployments) when you want repeatable deploys, run or service records, logs, outputs, backing machine access, and cleanup commands. ## Deployment Objects | Object | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Agent project | The local directory you deploy. It contains app code, dependencies, and `nullspace.agent.toml`. | | Config | The `nullspace.agent.toml` contract: `name`, `mode`, `template`, `workdir`, `install`, `entrypoint`, env names, permissions, service port, and outputs. | | Bundle | The uploaded file set selected by `[bundle] include` and `exclude`, with local secrets and generated directories excluded. | | Version | The immutable uploaded bundle plus config digest that a deployment can run. | | Deployment | The stable name users operate with `nullspace agent run`, `url`, `logs`, `status`, `machine`, `restart`, `stop`, and `delete`. | | Job run | One finite execution of a `job` deployment. It has a run ID, status, logs, outputs, and a backing machine. | | Service instance | A long-running execution of a `service` deployment. It has a service ID, status, logs, URL metadata, and a backing machine. | | Backing machine | The actual machine created for a run or service. It can be retained for PTY, SSH, command, file, or desktop debugging. | | Outputs | Files or directories declared in `[outputs]` and published as run metadata after a job exits. | | Framework state | OpenAI Agents SDK traces and approvals, Claude sessions, LangGraph thread IDs and checkpoints, CrewAI memory, or custom state. This stays app-owned. | ## Runtime Shapes Current live modes are `job` and `service`. | Mode | Use For | Execution | | --------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `job` | Finite work such as report generation, repository review, evaluation, CrewAI runs, or Claude Agent SDK tasks. | Creates a run record, starts a machine, executes the entrypoint, records logs and outputs, then exits. | | `service` | HTTP/WebSocket servers, LangGraph APIs, chat backends, or custom coordinators. | Starts a process in a machine, checks readiness, and optionally exposes a public URL. | `worker`, `triggered`, `workspace`, and `interactive` are reserved for future deployment models. Do not build public docs or configs that imply they are currently live. ## State Boundary Nullspace run IDs are not conversation session IDs. Framework session, thread, checkpoint, or flow state stays app-owned. Use volumes, retained machines, hibernate/auto-resume, or an external database for durable state. This boundary matters in framework integrations: * OpenAI Agents SDK tracing, handoffs, and approval state stay in the Agents SDK app. * Claude Agent SDK or Claude Code session files should live in a volume or app-managed storage if they must survive machine cleanup. * LangGraph thread IDs and checkpoints stay in your checkpointer storage. * CrewAI flow state and memory remain app-owned. ## Warm Pool Decisions Agents should create and wait for a template warm pool before a burst when many machines should start from the same ready custom template and cold fallback is either expensive or unacceptable. Use fork when agents should branch from one running mutable setup. Use hibernate or auto-resume when one machine should pause and continue later. Use volumes when data must survive machine cleanup. Template warm pools do not preserve per-run mutable state; a checkout becomes a normal machine and is not recycled. Agent recipe: 1. Build or identify the template. 2. Create the pool and wait for `min_ready`. 3. Create machines with explicit `warm_pool=pool.id`. 4. Use `warm_pool_mode="prefer"` for latency improvement, or `warm_pool_mode="require"` when cold fallback is not acceptable. 5. Drain or delete the pool after the burst. ## Debug Surface Every Agent Deployment run or service is backed by a normal machine. When you retain that machine, you can inspect it with the same tools used elsewhere in Nullspace: * [PTY](../access/pty) for an interactive terminal. * [SSH](../access/ssh) when local tools expect OpenSSH. * Commands and files for scripted inspection. * [Desktop Environments](../desktop/overview) when the agent used a GUI. * [Debug retained machines](../access/debug-retained-machines) for the retained failure workflow. ## Related * [Agents overview](./overview) * [Agent Deployments](./deployments) * [Local MCP](./local-mcp) * [Bring your own agent](./bring-your-own-agent)