Skip to main content
Agent Deployments turn a local agent project into an operated Nullspace process. You provide a source bundle, install command, entrypoint, env var names, optional service port, and declared outputs. Nullspace creates named deployments, versions, job runs, service instances, logs, output metadata, and backing sandboxes. Use this path when the agent is a product workflow, not a one-off terminal session. Current live modes are job and service. worker, triggered, workspace, and interactive are reserved for future deployment models. Nullspace run IDs are not conversation session IDs.

​
Lifecycle

  1. Create nullspace.agent.toml with nullspace agent init.
  2. Select project files with [bundle] include and exclude.
  3. Deploy the project with nullspace agent deploy ..
  4. Run a job or start a service.
  5. Inspect logs, status, outputs, and the backing sandbox.
  6. Retain failed sandboxes when you need PTY, SSH, desktop, command, or file debugging.
  7. Deploy a new version or delete the deployment when it is no longer needed.

​
Setup

From a local project directory: 
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "nullspace-sdk[cli]==0.1.9"
nullspace auth login --api-url https://api.13-215-85-171.sslip.io

nullspace agent init
nullspace agent deploy --dry-run --json
nullspace agent deploy --json
If uv is already part of the project, uv pip install "nullspace-sdk[cli]==0.1.9" is equivalent after the environment is active. For CI or non-interactive deploys, use NULLSPACE_API_KEY and NULLSPACE_API_URL instead of auth login.

​
What You Deploy

nullspace agent init writes nullspace.agent.toml. Keep runtime secret values out of this file; store only env var names. For a finite job: 
name = "repo-review-agent"
mode = "job"
template = "base"
workdir = "/workspace/project"
install = "python -m pip install -e ."
entrypoint = "python main.py"

[env]
required = ["OPENAI_API_KEY"]
optional = ["SERPER_API_KEY"]

[outputs]
paths = ["result.json", "reports"]
For a long-running service, set mode = "service" and bind the process to 0.0.0.0: 
name = "repo-review-service"
mode = "service"
template = "base"
workdir = "/workspace/project"
install = "python -m pip install -e ."
entrypoint = "python -m uvicorn app:app --host 0.0.0.0 --port 8000"

[service]
port = 8000
readiness = { type = "http", path = "/health", timeout_seconds = 30 }

[permissions]
public_url = true

​
Run A Job

Use job when the agent has finite work: code review, report generation, benchmarking, data extraction, evaluation, or a one-shot framework run. 
nullspace agent run repo-review-agent \
  --input-json '{"repo":"https://github.com/acme/repo"}' \
  --env OPENAI_API_KEY="$OPENAI_API_KEY" \
  --json

nullspace agent logs repo-review-agent --run adrun_123
nullspace agent outputs repo-review-agent --run adrun_123
nullspace agent status repo-review-agent --run adrun_123
nullspace agent sandbox repo-review-agent --run adrun_123

​
Start A Service

Use service when the agent exposes HTTP, WebSocket, or another long-running server: an API wrapper around a graph, a web preview service, a chat backend, or a custom coordinator. 
nullspace agent url repo-review-service \
  --env OPENAI_API_KEY="$OPENAI_API_KEY"

nullspace agent status repo-review-service --service adsvc_123
nullspace agent logs repo-review-service --service adsvc_123
nullspace agent restart repo-review-service
nullspace agent stop repo-review-service

​
Operate A Deployment

Keep the deployment name stable. Deploy new bundles from the same project, then use run or service IDs for individual executions.
NeedCommand
See logsnullspace agent logs <name> --run adrun_123
Read output metadatanullspace agent outputs <name> --run adrun_123
Check statusnullspace agent status <name> --run adrun_123
Inspect backing sandboxnullspace agent sandbox <name> --run adrun_123
Run a debug commandnullspace agent shell <name> --run adrun_123 --cmd "ls -la"
Stop a servicenullspace agent stop <name>
Restart a service after deploynullspace agent restart <name>
Delete a deploymentnullspace agent delete <name> --yes

​
Logs, Outputs, And Sandboxes

Agent jobs and services expose backing sandbox IDs. Use normal sandbox tools to inspect files, run commands, open PTY sessions, create snapshots, or destroy retained debug sandboxes. 
nullspace agent logs repo-review-agent --run adrun_123 --tail 100
nullspace agent outputs repo-review-agent --run adrun_123 --json
nullspace agent shell repo-review-agent --run adrun_123 --cmd "ls -la"
nullspace agent sandbox repo-review-agent --run adrun_123
Failed jobs can retain their sandbox for debugging: 
nullspace agent run repo-review-agent \
  --retain-on-failure \
  --retention-seconds 3600
Then attach with PTY, SSH, commands, file downloads, or the desktop viewer when the deployment used a desktop template. See Debug retained sandboxes for the human debugging workflow.

​
Secrets And Env Vars

Declare env var names in [env], then pass values at runtime with --env, --env-file, or SDK envs=. 
nullspace agent run repo-review-agent \
  --env OPENAI_API_KEY="$OPENAI_API_KEY" \
  --env SERPER_API_KEY="$SERPER_API_KEY"
Runtime values are injected into the agent process. They are not stored in deployment config, run rows, service rows, or platform-owned event metadata. Application code can still print or write secrets, so treat logs, output files, and .env files as sensitive.

​
State And Sessions

Framework session, thread, checkpoint, or flow state stays app-owned. Store durable state in a mounted volume, a retained or auto-resumed sandbox, or an external database. For example, keep LangGraph checkpoints in your checkpointer storage, keep Claude session files in a volume if they must survive cleanup, and let CrewAI flows own their state and output artifacts. Do not rely on the ephemeral sandbox filesystem for durable conversation state unless the sandbox is retained or the state is written to a mounted volume.

​
Cache And Templates

agent deploy reports deployment build cache state in human output and JSON. The default auto policy falls back to running install inside each job run or service start when no ready artifact exists. Use nullspace agent deploy --rebuild to build a fresh reusable deployment artifact during upload, or --no-cache to bypass cache lookup and artifact writes for one deploy. Use a custom template for heavy system dependencies or slow base setup.

​
Examples

Minimal Job

Deploy a small Python job and collect result.json plus a reports directory.

Minimal Service

Deploy a small Python HTTP service and fetch its public URL.

OpenAI Agents SDK Job

Deploy an OpenAI Agents SDK app as a finite job.

Claude Agent SDK Job

Deploy a Claude Agent SDK app as a finite job.

LangGraph Service

Deploy a LangGraph-backed HTTP service.

CrewAI Job

Deploy a CrewAI project as a bounded job.