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

ShapeWhat Runs In NullspaceTypical Owner
Direct machine workspaceCommands, files, PTY, SSH, desktop, templates, volumes, and preview services.Your app, CLI script, local MCP agent, or in-machine coding agent.
Agent DeploymentA 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 when you want repeatable deploys, run or service records, logs, outputs, backing machine access, and cleanup commands.

​
Deployment Objects

ObjectDescription
Agent projectThe local directory you deploy. It contains app code, dependencies, and nullspace.agent.toml.
ConfigThe nullspace.agent.toml contract: name, mode, template, workdir, install, entrypoint, env names, permissions, service port, and outputs.
BundleThe uploaded file set selected by [bundle] include and exclude, with local secrets and generated directories excluded.
VersionThe immutable uploaded bundle plus config digest that a deployment can run.
DeploymentThe stable name users operate with nullspace agent run, url, logs, status, machine, restart, stop, and delete.
Job runOne finite execution of a job deployment. It has a run ID, status, logs, outputs, and a backing machine.
Service instanceA long-running execution of a service deployment. It has a service ID, status, logs, URL metadata, and a backing machine.
Backing machineThe actual machine created for a run or service. It can be retained for PTY, SSH, command, file, or desktop debugging.
OutputsFiles or directories declared in [outputs] and published as run metadata after a job exits.
Framework stateOpenAI 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.
ModeUse ForExecution
jobFinite 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.
serviceHTTP/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: