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

SurfaceUse it for
Machine, AsyncMachineCreate, connect to, snapshot, fork, hibernate, resume, and destroy machines.
machine.commandsForeground commands, background processes, logs, stdin, and process cleanup.
machine.filesRead, write, upload, download, search, replace, and watch machine files.
machine.gitClone, pull, branch, commit, diff, push, and configure Git inside a machine.
machine.ptyInteractive terminal sessions over WebSocket.
machine.desktopScreenshots, 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.
CodeInterpreterStateful notebook-style code execution and package installation.
Template, TemplateBuildBuild reusable machine environments from images, Dockerfiles, and builder steps.
Volume, AsyncVolumeCreate persistent shared volumes, manage direct volume files, and mount them into machines.
Monitor, LifecycleSubscribe to runtime observations and inspect lifecycle event history or webhooks.

​
Machine methods

MethodUse
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

NamespaceNotable methods
machine.filesread, write, write_files, upload, resume_upload, upload_url, download_url, search_files, find_files, replace_in_files, watch_dir.
machine.ptycreate_session, connect(session_id=...), list_sessions, get_session_info, resize_session, kill_session.
machine.desktopscreenshot, screenshot_region, screenshot_compressed, capabilities, mouse/keyboard input, windows, clipboard, launch/open, viewer stream, recordings.
machine.code_interpreterrun_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.gitClone, pull, push, branch, commit, diff, remote, config, SSH key, and HTTPS auth helpers.

​
Persistent and control-plane surfaces

SurfaceNotable methods
Volumecreate, get, get_by_name, from_name(create_if_missing=True), from_id, list, get_info, instance delete, and mount(read_only, subpath).
volume.filesDirect persistent file CRUD, search, replace with VolumeReplaceResult, watch, upload/download, signed URLs, and resumable uploads.
TemplateBuilder 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.
Snapshotget, list, and delete reusable snapshot records by owner, origin machine, and metadata.
LifecycleEvent lists, snapshot event lists, streaming, subscriptions, webhook CRUD, and delivery inspection.
MonitorLive 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.