> ## 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 Deployments > Deploy a local agent project as a named Nullspace job or service. 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 machines. 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 machine. 6. Retain failed machines 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: ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install "nullspace-sdk[cli]==1.0.0" 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]==1.0.0"` 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: ```toml theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} 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`: ```toml theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} 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. ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} 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 machine 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. ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} 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. | Need | Command | | ------------------------------ | ------------------------------------------------------------- | | See logs | `nullspace agent logs --run adrun_123` | | Read output metadata | `nullspace agent outputs --run adrun_123` | | Check status | `nullspace agent status --run adrun_123` | | Inspect backing machine | `nullspace agent machine --run adrun_123` | | Run a debug command | `nullspace agent shell --run adrun_123 --cmd "ls -la"` | | Stop a service | `nullspace agent stop ` | | Restart a service after deploy | `nullspace agent restart ` | | Delete a deployment | `nullspace agent delete --yes` | ## Logs, Outputs, And Machines Agent jobs and services expose backing machine IDs. Use normal machine tools to inspect files, run commands, open PTY sessions, create snapshots, or destroy retained debug machines. ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} 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 machine repo-review-agent --run adrun_123 ``` Failed jobs can retain their machine for debugging: ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} nullspace agent run repo-review-agent \ --retain-on-failure \ --retention-seconds 3600 ``` Then attach with [PTY](../access/pty), [SSH](../access/ssh), commands, file downloads, or the desktop viewer when the deployment used a desktop template. See [Debug retained machines](../access/debug-retained-machines) 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=`. ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} 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 machine, 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 machine filesystem for durable conversation state unless the machine 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 Deploy a small Python job and collect `result.json` plus a reports directory. Deploy a small Python HTTP service and fetch its public URL. Deploy an OpenAI Agents SDK app as a finite job. Deploy a Claude Agent SDK app as a finite job. Deploy a LangGraph-backed HTTP service. Deploy a CrewAI project as a bounded job. ## Related * [Agent Primitives](./primitives) * [Agents overview](./overview) * [CLI reference](../reference/cli) * [TypeScript service example](../examples/agent-deployment-typescript-service) * [Environment variables](../reference/env-vars) * [Preview URLs](../networking/preview-urls) * [Volumes](../volumes/overview) * [Templates](../templates/overview) * [Local MCP](./local-mcp)