Machine - Nullspace

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

Create And Connect

Method	Use
`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

Method	Use
`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

Method	Use
`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

Property	Use
`machine.commands`	Foreground commands, streaming, background processes, stdin, logs, list, and kill.
`machine.files`	Read, write, upload, download, search, replace, and watch machine files.
`machine.git`	Clone, branch, diff, commit, push, and configure Git inside the machine.
`machine.pty`	Create and connect to interactive terminal sessions.
`machine.desktop`	Screenshots, mouse/keyboard input, windows, clipboard, viewer streams, and recordings.
`machine.code_interpreter`	Stateful notebook-style code execution, contexts, package installs, runs, and artifacts.

Networking Helpers

Method	Use
`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)