> ## Documentation Index > Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt > Use this file to discover all available pages before exploring further. # Machine > Python SDK object reference for machine lifecycle, networking, files, and namespaces. `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. | ```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} 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. | ```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} 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](../../networking/token-model) for the related credential families. ```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} 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) ``` ## Related * [Machines guide](../../guides/python-sdk/machines) * [Machine lifecycle](../../machines/lifecycle) * [Custom preview proxy](../../networking/custom-preview-proxy) * [Commands reference](./commands)