Skip to main content
The current Python SDK distribution is nullspace-sdk==0.1.9. The import package is nullspace, and the optional CLI command is nullspace.

​
Object Reference

Sandbox

Lifecycle, networking helpers, and runtime namespaces.

Commands & processes

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

Filesystem

Sandbox 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==0.1.9}"
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]==0.1.9". Supported Python versions are 3.11, 3.12, and 3.13 on Linux and macOS.

​
Core imports

from nullspace import (
    AsyncSandbox,
    AsyncVolume,
    CodeInterpreter,
    Lifecycle,
    Monitor,
    PreviewGrantInfo,
    PreviewProxyTarget,
    PreviewReadiness,
    PreviewUrl,
    RevokePreviewGrantResponse,
    Sandbox,
    Snapshot,
    SshAccess,
    Template,
    TemplateBuild,
    Volume,
    redact_preview_token,
    redact_preview_url,
)

​
Main surfaces

SurfaceUse it for
Sandbox, AsyncSandboxCreate, connect to, snapshot, fork, hibernate, resume, and destroy sandboxes.
sandbox.commandsForeground commands, background processes, logs, stdin, and process cleanup.
sandbox.filesRead, write, upload, download, search, replace, and watch sandbox files.
sandbox.gitClone, pull, branch, commit, diff, push, and configure Git inside a sandbox.
sandbox.ptyInteractive terminal sessions over WebSocket.
sandbox.desktopScreenshots, input automation, displays, windows, and managed viewer sessions.
sandbox.get_preview_url(...)Return typed direct preview URL metadata for a sandbox port.
sandbox.create_signed_preview_url(...)Create an explicit expiring signed preview grant.
sandbox.list_preview_urls(...) / sandbox.revoke_preview_url(...)Inspect and revoke preview grants.
sandbox.wait_for_preview(...)Wait for route and service readiness before opening a preview link.
sandbox.create_preview_proxy_target(...)Create a header-auth upstream target for a customer-run preview proxy.
sandbox.create_ssh_access(...)Mint short-lived OpenSSH certificate relay access for a sandbox.
CodeInterpreterStateful notebook-style code execution and package installation.
Template, TemplateBuildBuild reusable sandbox environments from images, Dockerfiles, and builder steps.
Volume, AsyncVolumeCreate persistent shared volumes, manage direct volume files, and mount them into sandboxes.
Monitor, LifecycleSubscribe to runtime observations and inspect lifecycle event history or webhooks.

​
Sandbox methods

MethodUse
Sandbox.create(...)Launch a sandbox with template, CPU, memory, timeout, metadata, envs, cwd, network policy, volumes, desktop config, and auto-resume options.
Sandbox.connect(id)Reconnect to a running sandbox, or resume a paused alias and return the running handle.
Sandbox.create(snapshot_id=...)Start a fresh independent sandbox from a reusable snapshot.
Sandbox.get_info_by_id(id)Read sandbox status without waking a paused sandbox.
Sandbox.list(...)Page through sandboxes with state/query filters.
sandbox.create_snapshot()Capture a reusable 1-to-many snapshot while keeping the source sandbox running.
sandbox.get_host_info(port)Return host, signed HTTP URL, signed WebSocket URL, and signed URL expiration metadata.
sandbox.get_url(port) / get_websocket_url(port)Convenience helpers for exposed HTTP and WebSocket ports.
sandbox.get_preview_url(port)Return typed direct preview URL metadata, including grant, HTTP URL, WebSocket URL, and token transport.
sandbox.create_signed_preview_url(port, expires_in_seconds=...)Create an explicit expiring direct preview grant.
sandbox.list_preview_urls(port=...) / sandbox.revoke_preview_url(grant_id)Inspect and revoke preview grants.
sandbox.wait_for_preview(port, ...)Wait for route and service readiness before opening a preview link.
sandbox.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.
sandbox.create_ssh_access(public_key=..., expires_in_minutes=...)Mint an SshAccess record with relay host, certificate, expiration, and generated OpenSSH command metadata.
sandbox.upload_url(path) / download_url(path)Convenience wrappers for direct file transfer URLs.
Sandbox.run_once(command, args, ...)Create a sandbox, run one command, and clean up in one call.

​
Runtime namespaces

NamespaceNotable methods
sandbox.filesread, write, write_files, upload, resume_upload, upload_url, download_url, search_files, find_files, replace_in_files, watch_dir.
sandbox.ptycreate_session, connect(session_id=...), list_sessions, get_session_info, resize_session, kill_session.
sandbox.desktopscreenshot, screenshot_region, screenshot_compressed, capabilities, mouse/keyboard input, windows, clipboard, launch/open, viewer stream, recordings.
sandbox.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.
sandbox.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 sandbox, and metadata.
LifecycleEvent lists, snapshot event lists, streaming, subscriptions, webhook CRUD, and delivery inspection.
MonitorLive snapshot, update, metrics, process, and error callbacks.

​
Feature map

Sandboxes

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 sandboxes.

Volumes

Persistent filesystems, sandbox 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 SandboxError, 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.