Agent Primitives

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 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:

Build or identify the template.
Create the pool and wait for min_ready.
Create machines with explicit warm_pool=pool.id.
Use warm_pool_mode="prefer" for latency improvement, or warm_pool_mode="require" when cold fallback is not acceptable.
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 for an interactive terminal.
SSH when local tools expect OpenSSH.
Commands and files for scripted inspection.
Desktop Environments when the agent used a GUI.
Debug retained machines for the retained failure workflow.

Overview

Agent workspaces

Framework integrations

Local agent tooling

Two Ways Agents Use Nullspace

Deployment Objects

Runtime Shapes

State Boundary

Warm Pool Decisions

Debug Surface

​Two Ways Agents Use Nullspace

​Deployment Objects

​Runtime Shapes

​State Boundary

​Warm Pool Decisions

​Debug Surface

​Related

Two Ways Agents Use Nullspace

Deployment Objects

Runtime Shapes

State Boundary

Warm Pool Decisions

Debug Surface

Related