# Nullspace

Nullspace is like Kubernetes, for AI agents — orchestration and on-demand
microVM compute for agent workloads. It provides isolated environments with
command execution, files, preview URLs, templates, volumes, desktop access,
code interpreter, lifecycle events, snapshots, resume, and fork.

This file is a generated index of the Nullspace documentation. See
/llms-full.txt for the fuller page-by-page index.

{/* GENERATED FILE - DO NOT EDIT BY HAND. */}
{/* Rendered by tools/docs/render_llms_txt.py from docs/site/docs.json. */}
{/* Regenerate with: uv run --project sdks/python --extra dev python tools/docs/render_llms_txt.py */}

## Get started

- [Welcome to Nullspace](/introduction): Like Kubernetes, for AI agents — orchestration and on-demand microVM compute that agents create, scale, pause, resume, and fork.
- [First Sandbox](/quickstarts/first-sandbox): Create a hosted Nullspace sandbox with Python in under five minutes.
- [Development Environment](/quickstarts/development-environment): Set up a Nullspace Python environment across common shells.
- [Recipes](/quickstarts/recipes): Common Nullspace tasks shown in every client — Python SDK, CLI, HTTP API, and MCP.
- [Self-Hosted Single-Host](/quickstarts/self-hosted-single-host): Install the OSS single-host appliance, connect with the SDK or CLI, and run the operator checks.

## Sandboxes

- [Sandboxes](/sandboxes/overview): Create isolated Linux runtimes for commands, files, services, agents, and desktop work.
- [Create, Connect, And List Sandboxes](/sandboxes/create-connect-list): Launch sandboxes, reconnect by ID, inspect metadata, and paginate lists.
- [Sandbox Lifecycle](/sandboxes/lifecycle): Understand create, exec, hibernate, resume, fork, and destroy.
- [Create](/concepts/create): Start a new hosted sandbox from a template.
- [Exec](/concepts/exec): Run commands inside a running sandbox.
- [Hibernate](/concepts/hibernate): Snapshot a running sandbox and stop its active VM.
- [Resume](/concepts/resume): Restore hibernated paused state into a running sandbox.
- [Fork](/concepts/fork): Branch a running sandbox into an independent child sandbox.
- [Destroy](/concepts/destroy): Tear down a sandbox when work is complete.
- [Persistence](/sandboxes/persistence): Pause sandboxes, resume paused state, and keep long-running sessions cheap.
- [Auto-Resume](/sandboxes/auto-resume): Pause idle sandboxes and wake them when SDK calls or public traffic arrive.
- [Snapshots](/sandboxes/snapshots): Create reusable sandbox snapshots and spawn independent sandboxes from them.
- [Fork](/sandboxes/fork): Branch a running sandbox into an independent child.
- [Metrics And Timeouts](/sandboxes/metrics-timeouts): Inspect sandbox usage and configure timeout behavior.

## Commands

- [Commands](/commands/overview): Run shell commands, argv commands, streaming work, and background processes inside a sandbox.
- [Streaming Command Output](/commands/streaming): Stream stdout and stderr from long-running commands.
- [Run commands in background](/commands/background): Start long-running commands and manage them by PID.
- [Processes](/commands/processes): List processes, send stdin, inspect logs, and kill work by PID.

## Filesystem

- [Filesystem](/filesystem): Read, write, upload, download, search, and watch sandbox files.
- [Uploads](/filesystem/uploads): Upload files and directories with direct or resumable transfer.
- [Downloads](/filesystem/downloads): Download sandbox files directly or through signed URLs.
- [Search, Replace, And Watch](/filesystem/search-watch): Search file contents, match file names, replace text, and watch directories.

## Code Interpreter

- [Code Interpreter](/code-interpreter/overview): Run stateful notebook-style code with structured results and artifacts.
- [Overview](/code-interpreter/analyze-data): Analyze data with stateful notebook-style code in a sandbox.
- [Pre-installed libraries](/code-interpreter/pre-installed-libraries): Python data, ML, plotting, and notebook packages included in the standard code-interpreter template.
- [Overview](/code-interpreter/charts-overview): Produce static and interactive visual outputs from code interpreter runs.
- [Static charts](/code-interpreter/static-charts): Generate PNG and file-based chart outputs with Python plotting libraries.
- [Interactive charts](/code-interpreter/interactive-charts): Create Plotly and other rich notebook outputs from code interpreter runs.
- [Streaming Code Output](/code-interpreter/streaming): Stream stdout, stderr, results, artifacts, and errors from code execution.
- [Code Contexts](/code-interpreter/contexts): Create and manage persistent code execution contexts.
- [Runs And Artifacts](/code-interpreter/runs-artifacts): Manage async code runs and files produced by code execution.
- [Overview](/code-interpreter/languages-overview): Choose a supported code interpreter language and kernel.
- [Python](/code-interpreter/language-python): Run Python code interpreter cells with persistent state and rich outputs.
- [JavaScript And TypeScript](/code-interpreter/language-javascript-typescript): Run JavaScript and TypeScript cells with the code interpreter kernels.
- [R](/code-interpreter/language-r): Run R cells in the standard code interpreter template.
- [Java](/code-interpreter/language-java): Run Java snippets through the code interpreter Java kernel.
- [Bash](/code-interpreter/language-bash): Run shell-oriented notebook cells with the code interpreter Bash kernel.

## Desktop

- [Desktop Environments](/desktop/overview): Run GUI-capable sandboxes for browser, desktop app, and visual-agent workflows.
- [Desktop Automation](/desktop/automation): Automate GUI sandboxes with screenshots, mouse, keyboard, windows, clipboard, and app launch.
- [Managed Desktop Viewer](/desktop/viewer): Start a browser-accessible desktop viewer session.
- [Desktop Recordings](/desktop/recordings): Record, list, download, and delete desktop session videos.

## Templates

- [Templates](/templates/overview): Build reusable sandbox environments from images, Dockerfiles, and builder steps.
- [Quickstart](/templates/quickstart): Build a reusable template and launch a sandbox from it.
- [How it works](/templates/how-it-works): Understand template builders, builds, snapshots, and sandbox startup.
- [Defining template](/templates/defining): Compose template builder steps for packages, files, envs, users, and workdirs.
- [Base image](/templates/base-images): Start templates from standard images, existing templates, custom images, or Dockerfiles.
- [Private registries](/templates/private-registries): Pull private base images from username/password registries, GCP Artifact Registry, or AWS ECR.
- [User and workdir](/templates/user-workdir): Set the default user, working directory, and runtime environment for template sandboxes.
- [Start & ready commands](/templates/start-ready): Start template services during build and snapshot them after readiness.
- [Choose A Per-Template Kernel](/guides/template-kernel-selection): Understand default and FUSE-capable guest kernel lanes.
- [Build](/templates/build): Build templates, wait for completion, and tune build resources.
- [Caching](/templates/caching): Control template build cache behavior and inspect cache events.
- [Logging](/templates/logging): Stream template build logs, reconnect to builds, and poll incrementally.
- [Error handling](/templates/errors): Recover from build failures, upload failures, and terminal template states.
- [Names](/templates/names): Reserve, rename, and inspect template names and namespaces.
- [Tags & versioning](/templates/tags-versioning): Use tags, aliases, visibility, and deletion to manage template versions.
- [Template Warm Pools](/templates/warm-pools): Keep ready capacity for a custom template and create sandboxes from it with bounded fallback behavior.

## Volumes

- [Volumes](/volumes/overview): Create, mount, and manage durable shared filesystems.
- [Managing volumes](/volumes/managing-volumes): Create, list, inspect, field-select, and delete persistent volumes.
- [Mounting volumes](/volumes/mounting-volumes): Attach persistent volumes to sandboxes with mount paths, subpaths, and read-only access.
- [Read & write](/volumes/read-write): Read, write, batch-write, move, remove, chmod, search, replace, and watch volume files.
- [Direct Volume Files](/volumes/files): Manage persistent volume files without starting a sandbox.
- [File & directory metadata](/volumes/file-directory-metadata): List directories, inspect paths, check existence, search names and contents, and watch volume changes.
- [Upload data](/volumes/upload-data): Upload files, directories, stdin streams, and resumable transfers into persistent volumes.
- [Download data](/volumes/download-data): Download files, directories, archives, and signed URLs from persistent volumes.
- [Volume Transfers](/volumes/transfers): Upload and download files or directories directly to persistent volumes.

## Networking

- [Networking And Security](/networking/overview): Expose, secure, and connect to services running inside sandboxes.
- [API Keys](/guides/api-keys): Use beta API keys with the SDK, CLI, and HTTP API.
- [Preview URLs](/networking/preview-urls): Expose sandbox HTTP and WebSocket services through signed preview URLs.
- [Custom Preview Proxy](/networking/custom-preview-proxy): Put your own reverse proxy in front of Nullspace preview targets without exposing edge tokens in browser URLs.
- [Token Model](/networking/token-model): Understand Nullspace API keys, preview tokens, private traffic tokens, desktop viewer tokens, SSH credentials, and file transfer URLs.
- [Access Control](/networking/access-control): Control preview traffic, signed URLs, outbound access, and request host masking.
- [WebSockets](/networking/websockets): Use WebSocket channels for streaming exec, PTY, watches, lifecycle, monitor, and exposed ports.
- [Share A Preview URL](/guides/share-sandbox-url): Expose a sandbox port through a signed temporary preview URL.
- [Tunnel Egress Through Your Own Proxy](/guides/proxy-tunneling): Route sandbox egress through a Shadowsocks proxy with template primitives.
- [Mount An S3/GCS/R2 Bucket](/guides/mount-bucket): Mount cloud buckets inside sandboxes with FUSE-based tools.

## Interactive access

- [Access Overview](/access/overview): Choose PTY, SSH, or retained-sandbox debugging for human inspection and control.
- [PTY Sessions](/access/pty): Create, reconnect, resize, and kill interactive terminal sessions.
- [SSH Access](/access/ssh): Connect to a sandbox with OpenSSH through certificate-backed relay access.
- [Debug Retained Sandboxes](/access/debug-retained-sandboxes): Inspect retained agent, service, and failed workflow sandboxes with PTY, SSH, commands, and files.
- [Connect To Sandbox](/cli/connect-to-sandbox): Reconnect to existing sandboxes with CLI commands, PTY sessions, SSH, and preview URLs.
- [Create Sandbox](/cli/create-sandbox): Create Nullspace sandboxes from templates, snapshots, and volumes with the CLI.
- [Execute Commands In Sandbox](/cli/execute-commands): Run foreground, streaming, background, and process-management commands with the CLI.
- [Manage Files](/cli/manage-files): Read, write, upload, download, search, replace, and watch sandbox files from the CLI.
- [Shutdown Running Sandboxes](/cli/shutdown-running-sandboxes): Pause, hibernate, or destroy running sandboxes from the CLI.

## Observability

- [Observability](/observability/overview): Monitor sandbox lifecycle events, webhooks, and runtime metrics.
- [Lifecycle Events](/observability/lifecycle-events): List and stream sandbox and snapshot lifecycle transitions.
- [Lifecycle Webhooks](/observability/webhooks): Register webhook endpoints and inspect delivery attempts.
- [Monitor Stream](/observability/monitor): Subscribe to live snapshot, update, metrics, process, and error events.

## Overview

- [Examples](/examples): Runnable, self-contained examples for every major Nullspace capability.

## Sandbox patterns

- [Code Interpreter](/examples/code-interpreter): Run stateful notebook-style code, install a package, and render a plot.
- [Agent Workspace](/examples/agent): Clone a repository and run checks inside a sandbox, the way an agent would.
- [Fork](/examples/fork): Branch a running sandbox and watch parent and child diverge.
- [Template Build](/examples/template-build): Build a reusable template and create a sandbox from it.
- [Template Warm Pools](/examples/template-warm-pools): Build a ready custom template, keep pool capacity warm, and create sandboxes with explicit checkout modes.
- [Shared Volume](/examples/shared-volume): Mount one persistent volume into two sandboxes — one writer, one read-only reader.
- [GitHub Actions CI/CD](/use-cases/ci-cd): Run AI-powered code review, testing, and validation in secure Nullspace sandboxes from GitHub Actions workflows.

## Networking and access

- [Port Forwarding](/examples/port-forwarding): Start a web server in a sandbox and fetch it from outside via a signed preview URL.
- [Custom Preview Proxy Example](/examples/custom-preview-proxy): Run a minimal customer-owned proxy in front of a Nullspace preview target.
- [Desktop Viewer](/examples/desktop-viewer): Start a desktop sandbox and open a managed viewer URL.
- [Resumable Upload](/examples/resumable-upload): Upload files and directories with progress and retry recovery.
- [Lifecycle Webhook](/examples/lifecycle-webhook): Register lifecycle webhooks and inspect delivery attempts.

## Agent deployments

- [Agent Deployment Job](/examples/agent-deployment-job): Deploy a minimal local agent project as a Nullspace job.
- [Agent Deployment Service](/examples/agent-deployment-service): Deploy a minimal local agent project as a Nullspace service.
- [OpenAI Agents SDK Job](/examples/agent-deployment-openai-agents): Deploy an OpenAI Agents SDK app as a Nullspace job.
- [Claude Agent SDK Job](/examples/agent-deployment-claude-agent-sdk): Deploy a Claude Agent SDK app as a Nullspace job.
- [LangGraph Service](/examples/agent-deployment-langgraph-service): Deploy a LangGraph-backed HTTP service on Nullspace.
- [CrewAI Job](/examples/agent-deployment-crewai-job): Deploy a CrewAI project as a Nullspace job.
- [TypeScript Agent Service](/examples/agent-deployment-typescript-service): Deploy a Node/TypeScript HTTP service on Nullspace.

## Overview

- [Agents on Nullspace](/agents/overview): Four ways agents use Nullspace: local MCP tools, in-sandbox workspaces, managed deployments, and framework integrations.
- [Agent Primitives](/agents/primitives): Understand the objects behind agent workspaces and Agent Deployments.
- [Agent Deployments](/agents/deployments): Deploy a local agent project as a named Nullspace job or service.

## Agent workspaces

- [Codex](/agents/codex): Run OpenAI Codex in a secure Nullspace sandbox.
- [Claude Code](/agents/claude-code): Run Claude Code in a secure Nullspace sandbox.
- [Amp](/agents/amp): Run Amp in a secure Nullspace sandbox.
- [OpenCode](/agents/opencode): Run OpenCode in a secure Nullspace sandbox.

## Framework integrations

- [OpenAI Agents SDK](/agents/openai-agents-sdk): Use Nullspace as an Agents SDK tool or deploy an Agents SDK app as a job or service.
- [Claude Agent SDK](/agents/claude-agent-sdk): Deploy a Claude Agent SDK project as a managed Nullspace job.
- [LangGraph](/agents/langgraph): Deploy a LangGraph-backed HTTP service on Nullspace.
- [LangChain](/agents/langchain): Expose Nullspace sandbox operations as LangChain tools.
- [CrewAI](/agents/crewai): Deploy CrewAI projects as managed Nullspace jobs.
- [Bring Your Own Agent](/agents/bring-your-own-agent): Run a custom agent loop with Nullspace as the isolated workspace.

## Local agent tooling

- [Local MCP](/agents/local-mcp): Connect Codex, Claude Code, Cursor, VS Code, or another MCP client to Nullspace CLI tools.
- [Agent Skills](/agents/agent-skills): Install Nullspace instructions for Codex and Claude Code.

## Python SDK

- [SDK Reference](/sdk-reference): Current Python SDK package, imports, and major surfaces.
- [Python SDK Overview](/guides/python-sdk/overview): Install, configure, and choose the right Python SDK surface.
- [SDK Config](/reference/config): Configuration precedence for the Nullspace SDK and CLI.
- [Sandboxes](/guides/python-sdk/sandboxes): Create, inspect, configure, connect to, and clean up sandboxes.
- [Commands And Processes](/guides/python-sdk/commands-processes): Run commands, stream output, manage background processes, and send stdin.
- [Filesystem](/guides/python-sdk/filesystem): Read, write, upload, download, search, and watch sandbox files.
- [Code Interpreter](/guides/python-sdk/code-interpreter): Run stateful notebook-style code in a hosted sandbox.
- [Templates](/guides/python-sdk/templates): Build reusable sandbox environments from images, Dockerfiles, and builder steps.
- [Volumes](/guides/python-sdk/volumes): Create, mount, and manage persistent shared filesystems.
- [Desktop And PTY](/guides/python-sdk/desktop-pty): Automate desktop sessions and interactive terminals.
- [Python SDK Lifecycle](/guides/python-sdk/lifecycle): Read lifecycle events, stream live updates, and inspect webhook deliveries.
- [Monitor And Snapshots](/guides/python-sdk/monitor-snapshots): Subscribe to monitor updates and manage snapshot metadata.
- [Start And Ready Commands](/guides/python-sdk/start-ready-commands): Configure template startup commands and readiness probes.
- [Template Error Handling](/guides/python-sdk/template-error-handling): Handle build failures, upload failures, and terminal template states.
- [Template Build Logging Migration](/guides/python-sdk/template-build-logging-migration): Move older template build code to the current structured logging surface.
- [Errors And Types](/guides/python-sdk/errors-types): Understand SDK error classes and stable recovery signals.
- [CLI](/guides/python-sdk/cli): Install and use the optional nullspace command line for auth, sandboxes, desktop automation, code execution, lifecycle, snapshots, and volumes.

## Python SDK objects

- [Sandbox](/reference/python-sdk/sandbox): Python SDK object reference for sandbox lifecycle, networking, files, and namespaces.
- [Commands And Processes](/reference/python-sdk/commands): Python SDK object reference for running commands and managing processes.
- [Filesystem](/reference/python-sdk/filesystem): Python SDK object reference for sandbox files, uploads, downloads, search, and watches.
- [Templates](/reference/python-sdk/templates): Python SDK object reference for reusable sandbox templates and builds.
- [Volumes](/reference/python-sdk/volumes): Python SDK object reference for persistent volumes and direct volume files.
- [Code Interpreter](/reference/python-sdk/code-interpreter): Python SDK object reference for stateful code execution, contexts, runs, and artifacts.
- [Desktop And PTY](/reference/python-sdk/desktop-pty): Python SDK object reference for desktop automation, managed viewer streams, recordings, and terminal sessions.
- [Lifecycle And Monitor](/reference/python-sdk/lifecycle-monitor): Python SDK object reference for lifecycle events, webhooks, and live monitor streams.
- [Errors And Types](/reference/python-sdk/errors-types): Python SDK object reference for public exception classes and typed result objects.

## TypeScript SDK

- [TypeScript SDK](/guides/typescript-sdk/overview): Create and drive cloud sandboxes for AI agents from TypeScript.

## CLI

- [Installation](/cli/installation): Install the Nullspace CLI and verify it can reach hosted or self-hosted APIs.
- [Authentication](/cli/authentication): Configure API credentials for the Nullspace CLI.
- [List Sandboxes](/cli/list-sandboxes): List, filter, and inspect hosted Nullspace sandboxes from the CLI.
- [Manage Templates](/cli/manage-templates): Build, inspect, tag, rename, and delete sandbox templates from the CLI.
- [Manage Volumes](/cli/manage-volumes): Create, mount, inspect, transfer, and edit persistent volumes from the CLI.
- [CLI Reference](/reference/cli): Nullspace command line surfaces for auth, sandboxes, files, desktop automation, code execution, lifecycle, snapshots, templates, and volumes.
- [CLI Schema](/reference/cli-schema): Machine-readable command metadata emitted by nullspace schema.

## Platform reference

- [Supported Clients](/reference/clients): Choose between the Python SDK, CLI, local MCP, and raw HTTP API.
- [Environment Variables](/reference/env-vars): User-facing environment variables for the SDK, CLI, console, hosted beta, sandbox runtime, and agent secrets.
- [WebSocket Protocol](/reference/websocket-protocol): Raw WebSocket channels for streaming exec, PTY, file watches, lifecycle, monitor, volumes, and desktop viewer.
- [Error Codes](/error-codes): Stable CLI exit codes and JSON error-code anchors.
- [API Error Catalog](/reference/error-codes): Machine-readable error codes from the ErrorResponse schema in specs/openapi.yaml.
- [CLI Exit Codes](/reference/cli-exit-codes): Stable exit codes returned by the nullspace CLI, generated from the SDK source of truth.
- [Hosted Endpoints](/reference/hosted-endpoints): Current hosted private-beta endpoint values and how examples reference them.
- [Single-Host Release Artifacts](/reference/single-host-release-artifacts): Manifest, artifact, compatibility, install, and upgrade contract for the OSS single-host appliance.
- [Git Helpers](/reference/git): Clone, branch, diff, commit, and push repositories inside a sandbox.
- [Account](/account): Dormant self-serve account surface for profile, quota, keys, export, and deletion.
- [Guides](/guides/index): Task guides for the hosted Nullspace private beta.
- [Sandbox Lifecycle](/guides/sandbox-lifecycle): Legacy guide pointer for sandbox lifecycle documentation.
- [Status](/status): Private-beta service status and health-check entrypoints.
- [Changelog](/changelog): Public release notes for the private-beta SDK and docs surface.

## Overview

- [API Reference](/api-reference): Use the Nullspace HTTP API directly from curl, JavaScript, or any language without a first-party SDK.
- [API Reference Scope](/reference/api-scope): Understand which generated OpenAPI operations are public integration surfaces.

## Endpoints

- [API Reference](/api-reference): Use the Nullspace HTTP API directly from curl, JavaScript, or any language without a first-party SDK.