Skip to main content
Machine is the synchronous handle for a running Nullspace machine. AsyncMachine mirrors the same lifecycle and namespace methods with await.

​
Create And Connect

MethodUse
Machine.create(...)Launch from a template or reusable snapshot with sizing, timeout, metadata, envs, cwd, network, volumes, desktop config, and auto-resume options.
Machine.connect(id)Reconnect to a running machine or resume a paused alias and return a running handle.
Machine.list(...)Page through machines with state, template, metadata, and field filters.
Machine.get_info_by_id(id)Read machine status without waking a paused machine.
Machine.run_once(command, args, ...)Create a machine, run one command, and clean up.
from nullspace import Machine

with Machine.create(template="base", timeout=300) as machine:
    print(machine.id)
    print(machine.commands.run("echo ready", shell=True).stdout)

​
Lifecycle

MethodUse
machine.kill()Destroy the machine and release runtime resources.
machine.pause() / machine.hibernate()Save paused state and stop the running VM.
Machine.resume(snapshot_id)Start a new running machine from a pause/resume snapshot.
machine.create_snapshot()Capture reusable baseline state while the source keeps running.
machine.fork()Branch the running machine into an independent child.
machine.set_timeout(...)Update timeout duration and timeout action.

​
Runtime Volumes

MethodUse
machine.list_volumes()List volume attachments for the running machine.
machine.attach_volume(volume, mount_path, read_only=False, subpath=None)Attach a volume ID, volume name, VolumeMount, or dictionary at runtime.
machine.detach_volume(attachment_id)Detach one runtime volume attachment.
machine.get_volume_health(attachment_id)Refresh and return runtime health for an attachment.
machine.remount_volume(attachment_id)Remount an attachment in place.

​
Namespaces

PropertyUse
machine.commandsForeground commands, streaming, background processes, stdin, logs, list, and kill.
machine.filesRead, write, upload, download, search, replace, and watch machine files.
machine.gitClone, branch, diff, commit, push, and configure Git inside the machine.
machine.ptyCreate and connect to interactive terminal sessions.
machine.desktopScreenshots, mouse/keyboard input, windows, clipboard, viewer streams, and recordings.
machine.code_interpreterStateful notebook-style code execution, contexts, package installs, runs, and artifacts.

​
Networking Helpers

MethodUse
machine.get_host_info(port)Return host mapping, signed HTTP URL, signed WebSocket URL, and expiration metadata.
machine.get_url(port)Return a signed browser HTTP URL for a machine port.
machine.get_websocket_url(port)Return a signed WebSocket URL for a machine port.
machine.get_preview_url(port)Return typed direct preview URL metadata, including HTTP and WebSocket signed URLs and grant metadata.
machine.create_signed_preview_url(port, ...)Create an explicit signed preview grant with optional expiry.
machine.list_preview_urls(port=...)List preview grants for a machine, optionally filtered by port.
machine.revoke_preview_url(grant_id)Revoke one preview grant and return revocation metadata.
machine.wait_for_preview(port, ...)Wait for route and service readiness before opening or sharing a preview link.
machine.create_preview_proxy_target(port, ...)Return marker-only upstream URLs plus header tokens for a customer-run preview proxy.
machine.create_ssh_access(public_key=..., expires_in_minutes=...)Mint short-lived OpenSSH certificate relay metadata for this machine.
machine.upload_url(path) / machine.download_url(path)Return signed file transfer URLs.
from nullspace import Machine, redact_preview_url

preview = machine.create_signed_preview_url(8080, expires_in_seconds=900)
readiness = machine.wait_for_preview(8080, timeout_secs=30)
print(readiness.ready)
print(redact_preview_url(preview.url))
SDK methods return raw URLs and header tokens so callers can open browsers or configure proxies intentionally. Use redact_preview_url(...) and redact_preview_token(...) before writing preview credentials to terminal logs, application logs, or support bundles. See Token model for the related credential families. 
from pathlib import Path

access = machine.create_ssh_access(
    public_key=Path("~/.ssh/id_ed25519.pub").expanduser().read_text(),
    expires_in_minutes=10,
)
print(access.command)