> ## 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.
# SDK Reference
> Current Python SDK package, imports, and major surfaces.
The current Python SDK distribution is `nullspace-sdk==1.0.0`. The import
package is `nullspace`, and the optional CLI command is `nullspace`.
## Object Reference
Lifecycle, networking helpers, and runtime namespaces.
Foreground commands, streaming, background processes, stdin, logs, and kill.
Machine file CRUD, uploads, downloads, search, replace, and watches.
Builders, builds, logs, tags, aliases, visibility, and deletion.
Persistent volumes, mounts, direct files, and transfers.
Stateful code, contexts, packages, runs, and artifacts.
Desktop automation, viewer streams, recordings, and terminals.
Event history, webhooks, and live monitor streams.
Public exceptions and typed result objects.
## Install
```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
uv pip install "${NULLSPACE_SDK_INSTALL_SPEC:-nullspace-sdk==1.0.0}"
```
During private beta, `NULLSPACE_SDK_INSTALL_SPEC` is the immutable install
source from the operator handout. The default is the pinned PyPI release, but a
hosted wheel URL or private tag is also acceptable for operator patch cycles.
If the install source is the PyPI package name, install the optional CLI extra
with `uv pip install "nullspace-sdk[cli]==1.0.0"`.
Supported Python versions are 3.11, 3.12, and 3.13 on Linux and macOS.
## Core imports
```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
from nullspace import (
AsyncMachine,
AsyncVolume,
CodeInterpreter,
Lifecycle,
Monitor,
PreviewGrantInfo,
PreviewProxyTarget,
PreviewReadiness,
PreviewUrl,
RevokePreviewGrantResponse,
Machine,
Snapshot,
SshAccess,
Template,
TemplateBuild,
Volume,
redact_preview_token,
redact_preview_url,
)
```
## Main surfaces
| Surface | Use it for |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `Machine`, `AsyncMachine` | Create, connect to, snapshot, fork, hibernate, resume, and destroy machines. |
| `machine.commands` | Foreground commands, background processes, logs, stdin, and process cleanup. |
| `machine.files` | Read, write, upload, download, search, replace, and watch machine files. |
| `machine.git` | Clone, pull, branch, commit, diff, push, and configure Git inside a machine. |
| `machine.pty` | Interactive terminal sessions over WebSocket. |
| `machine.desktop` | Screenshots, input automation, displays, windows, and managed viewer sessions. |
| `machine.get_preview_url(...)` | Return typed direct preview URL metadata for a machine port. |
| `machine.create_signed_preview_url(...)` | Create an explicit expiring signed preview grant. |
| `machine.list_preview_urls(...)` / `machine.revoke_preview_url(...)` | Inspect and revoke preview grants. |
| `machine.wait_for_preview(...)` | Wait for route and service readiness before opening a preview link. |
| `machine.create_preview_proxy_target(...)` | Create a header-auth upstream target for a customer-run preview proxy. |
| `machine.create_ssh_access(...)` | Mint short-lived OpenSSH certificate relay access for a machine. |
| `CodeInterpreter` | Stateful notebook-style code execution and package installation. |
| `Template`, `TemplateBuild` | Build reusable machine environments from images, Dockerfiles, and builder steps. |
| `Volume`, `AsyncVolume` | Create persistent shared volumes, manage direct volume files, and mount them into machines. |
| `Monitor`, `Lifecycle` | Subscribe to runtime observations and inspect lifecycle event history or webhooks. |
## Machine methods
| Method | Use |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `Machine.create(...)` | Launch a machine with template, CPU, memory, timeout, metadata, envs, cwd, network policy, volumes, desktop config, and auto-resume options. |
| `Machine.connect(id)` | Reconnect to a running machine, or resume a paused alias and return the running handle. |
| `Machine.create(snapshot_id=...)` | Start a fresh independent machine from a reusable snapshot. |
| `Machine.get_info_by_id(id)` | Read machine status without waking a paused machine. |
| `Machine.list(...)` | Page through machines with state/query filters. |
| `machine.create_snapshot()` | Capture a reusable 1-to-many snapshot while keeping the source machine running. |
| `machine.get_host_info(port)` | Return host, signed HTTP URL, signed WebSocket URL, and signed URL expiration metadata. |
| `machine.get_url(port)` / `get_websocket_url(port)` | Convenience helpers for exposed HTTP and WebSocket ports. |
| `machine.get_preview_url(port)` | Return typed direct preview URL metadata, including grant, HTTP URL, WebSocket URL, and token transport. |
| `machine.create_signed_preview_url(port, expires_in_seconds=...)` | Create an explicit expiring direct preview grant. |
| `machine.list_preview_urls(port=...)` / `machine.revoke_preview_url(grant_id)` | Inspect and revoke preview grants. |
| `machine.wait_for_preview(port, ...)` | Wait for route and service readiness before opening a preview link. |
| `machine.create_preview_proxy_target(port, transports=...)` | Return marker-only upstream URLs, HTTP/WebSocket header tokens, forwarded-header requirements, and traffic-token hints for a custom proxy. |
| `machine.create_ssh_access(public_key=..., expires_in_minutes=...)` | Mint an `SshAccess` record with relay host, certificate, expiration, and generated OpenSSH command metadata. |
| `machine.upload_url(path)` / `download_url(path)` | Convenience wrappers for direct file transfer URLs. |
| `Machine.run_once(command, args, ...)` | Create a machine, run one command, and clean up in one call. |
## Runtime namespaces
| Namespace | Notable methods |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `machine.files` | `read`, `write`, `write_files`, `upload`, `resume_upload`, `upload_url`, `download_url`, `search_files`, `find_files`, `replace_in_files`, `watch_dir`. |
| `machine.pty` | `create_session`, `connect(session_id=...)`, `list_sessions`, `get_session_info`, `resize_session`, `kill_session`. |
| `machine.desktop` | `screenshot`, `screenshot_region`, `screenshot_compressed`, `capabilities`, mouse/keyboard input, windows, clipboard, launch/open, viewer stream, recordings. |
| `machine.code_interpreter` | `run_code`, `create_code_context`, context restart/interrupt/remove, artifact list/get/download/preview/delete, and read-only `list_runs`. Queued run mutation/wait helpers (`create_run`, `get_run`, `cancel_run`, `wait_for_run`) are not part of the hosted private beta launch surface because remote host-agent routing for queued code runs is not implemented yet. |
| `machine.git` | Clone, pull, push, branch, commit, diff, remote, config, SSH key, and HTTPS auth helpers. |
## Persistent and control-plane surfaces
| Surface | Notable methods |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Volume` | `create`, `get`, `get_by_name`, `from_name(create_if_missing=True)`, `from_id`, `list`, `get_info`, instance `delete`, and `mount(read_only, subpath)`. |
| `volume.files` | Direct persistent file CRUD, search, replace with `VolumeReplaceResult`, watch, upload/download, signed URLs, and resumable uploads. |
| `Template` | Builder base images, Dockerfile content, registry auth, file context, package/env/user/workdir/start-ready helpers, render to JSON/Dockerfile, build/connect, tags, aliases, visibility, namespaces, and claims. |
| `Snapshot` | `get`, `list`, and `delete` reusable snapshot records by owner, origin machine, and metadata. |
| `Lifecycle` | Event lists, snapshot event lists, streaming, subscriptions, webhook CRUD, and delivery inspection. |
| `Monitor` | Live snapshot, update, metrics, process, and error callbacks. |
## Feature map
`create`, `connect`, `list`, `kill`, `pause`, `resume`, `fork`, metrics, URLs, and lifecycle.
Blocking commands, background processes, streaming output, stdin, logs, list, and kill.
File CRUD, upload, download, resumable sessions, search, replace, and watch.
Stateful code, contexts, package installs, callbacks, async runs, and artifacts.
Builder steps, Dockerfiles, logs, readiness probes, tags, names, visibility, and errors.
GUI automation, managed viewer, recordings, and desktop-capable machines.
Persistent filesystems, machine mounts, direct files, and transfer helpers.
Lifecycle history, webhooks, monitor streams, and metrics.
## Exceptions
Public typed result objects include `PreviewUrl`, `PreviewGrantInfo`,
`PreviewReadiness`, `PreviewProxyTarget`, `RevokePreviewGrantResponse`, and
`SshAccess`. Public exception types include `MachineError`, `AuthError`,
`NotFoundError`, `TimeoutError`, `BuildError`, `FileUploadError`,
upload-specific subclasses, `GitError`, and `BatchWriteError`.
`PreviewGrantInfo` inventory fields include token-redacted usage counters,
last-error metadata, and disabled timestamps.
See the task guides for copy-pastable usage:
[Python SDK Overview](./guides/python-sdk/overview),
[CLI](./guides/python-sdk/cli), [Templates](./guides/python-sdk/templates),
[Volumes](./guides/python-sdk/volumes), and [API Reference](./api-reference).