SDK Reference

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

Machine

Lifecycle, networking helpers, and runtime namespaces.

Commands & processes

Foreground commands, streaming, background processes, stdin, logs, and kill.

Filesystem

Machine file CRUD, uploads, downloads, search, replace, and watches.

Templates

Builders, builds, logs, tags, aliases, visibility, and deletion.

Volumes

Persistent volumes, mounts, direct files, and transfers.

Code Interpreter

Stateful code, contexts, packages, runs, and artifacts.

Desktop & PTY

Desktop automation, viewer streams, recordings, and terminals.

Lifecycle & monitor

Event history, webhooks, and live monitor streams.

Errors & types

Public exceptions and typed result objects.

Install

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

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

Machines

create, connect, list, kill, pause, resume, fork, metrics, URLs, and lifecycle.

Commands

Blocking commands, background processes, streaming output, stdin, logs, list, and kill.

Filesystem

File CRUD, upload, download, resumable sessions, search, replace, and watch.

Code Interpreter

Stateful code, contexts, package installs, callbacks, async runs, and artifacts.

Templates

Builder steps, Dockerfiles, logs, readiness probes, tags, names, visibility, and errors.

Desktop Environments

GUI automation, managed viewer, recordings, and desktop-capable machines.

Volumes

Persistent filesystems, machine mounts, direct files, and transfer helpers.

Observability

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, CLI, Templates, Volumes, and API Reference.

Python SDK

Python SDK objects

TypeScript SDK

CLI

Platform reference

Object Reference

Machine

Commands & processes

Filesystem

Templates

Volumes

Code Interpreter

Desktop & PTY

Lifecycle & monitor

Errors & types

Install

Core imports

Main surfaces

Machine methods

Runtime namespaces

Persistent and control-plane surfaces

Feature map

Machines

Commands

Filesystem

Code Interpreter

Templates

Desktop Environments

Volumes

Observability

Exceptions

​Object Reference

Machine

Commands & processes

Filesystem

Templates

Volumes

Code Interpreter

Desktop & PTY

Lifecycle & monitor

Errors & types

​Install

​Core imports

​Main surfaces

​Machine methods

​Runtime namespaces

​Persistent and control-plane surfaces

​Feature map

Machines

Commands

Filesystem

Code Interpreter

Templates

Desktop Environments

Volumes

Observability

​Exceptions

Object Reference

Install

Core imports

Main surfaces

Machine methods

Runtime namespaces

Persistent and control-plane surfaces

Feature map

Exceptions