Skip to main content
Nullspace keeps the agent model small: a sandbox 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 sandbox workspaceCommands, files, PTY, SSH, desktop, templates, volumes, and preview services.Your app, CLI script, local MCP agent, or in-sandbox 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 sandboxes when you need fine-grained command and file control. Use Agent Deployments when you want repeatable deploys, run or service records, logs, outputs, backing sandbox 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, sandbox, restart, stop, and delete.
Job runOne finite execution of a job deployment. It has a run ID, status, logs, outputs, and a backing sandbox.
Service instanceA long-running execution of a service deployment. It has a service ID, status, logs, URL metadata, and a backing sandbox.
Backing sandboxThe actual sandbox 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 sandbox, executes the entrypoint, records logs and outputs, then exits.
serviceHTTP/WebSocket servers, LangGraph APIs, chat backends, or custom coordinators.Starts a process in a sandbox, 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 sandboxes, 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 sandbox 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 sandboxes 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 sandbox should pause and continue later. Use volumes when data must survive sandbox cleanup. Template warm pools do not preserve per-run mutable state; a checkout becomes a normal sandbox and is not recycled. Agent recipe:
  1. Build or identify the template.
  2. Create the pool and wait for min_ready.
  3. Create sandboxes 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 sandbox. When you retain that sandbox, you can inspect it with the same tools used elsewhere in Nullspace: