Create a new machine
Authorizations
API key passed as Bearer token
Headers
Reuse the same key to safely retry the same create, reusable snapshot create, fork, upload create/complete, or agent deployment create operation without duplicating work.
Body
Durable reusable snapshot ID to restore into a fresh machine. When provided, sizing, template, environment, filesystem, and VM egress policy are taken from the snapshot; each create idempotency key creates at most one child machine and the snapshot remains reusable for additional create requests.
Optional custom template warm-pool selector for machine create. V1 requires an explicit id for prefer and require modes; bypass may omit id to force cold create.
Template name or Docker image
x >= 1Guest memory in MiB. When omitted, the default is template-aware: the heavyweight code-interpreter and desktop templates default to 2048MB (their GUI/kernel stacks exhaust a smaller allocation), and all other templates default to 256MB.
x >= 1Minimum rootfs size in MiB. On cold create the rootfs is grown to this size before boot. For snapshot-backed templates the disk size is fixed at build time, so disk_mb must not exceed the template's built-in size (rebuild the template with a larger disk_mb instead). Omit to use the default headroom. Not permitted with snapshot_id.
512 <= x <= 131072Machine auto-destroy timeout in milliseconds
destroy, hibernate Opt-in idle timeout in milliseconds. When set, the machine runs timeout_action (hibernate or destroy) once it has been idle this long. Activity is edge ingress or exec/file/pty/process traffic; guest-internal idle egress does not count. Composes with the absolute timeout_ms (whichever fires first wins). Omit to keep the existing absolute-only behavior. Not a cap — purely opt-in ergonomics.
x >= 1Opt-in window in milliseconds after which a hibernated/paused machine is destroyed. Acts only on terminal/hibernated machines; never deletes a running machine out from under active traffic.
x >= 1When true the machine is never hibernated/snapshotted on inactivity; it is destroyed instead (forces timeout_action: destroy). Cannot be combined with auto_resume.
When true, a hibernated machine is automatically resumed when a
command, file, PTY, desktop, or proxy route targets its original
machine ID. Requires timeout_action: hibernate or
lifecycle.on_timeout: pause.
Arbitrary user-supplied metadata attached to the machine; stored verbatim (any JSON object), deliberately open.
When false, the machine has no network connectivity.
Optional default working directory for machine commands. Must be an absolute machine path that stays within the machine root. Accepted values are normalized before persistence, and reserved runtime paths under /workspace/.nullspace are rejected. When omitted, commands inherit the template default workdir; the standard agent-oriented templates default to /workspace. Clients may send an explicit null, which is treated the same as omitting the field.
Create-time shared-volume mount requests. ref is the canonical selector and accepts either an exact volume name or a volume id. On snapshot resume and fork, shared mounts are remounted with fresh internal leases before the new machine becomes ready; that storage remount does not make VM memory or mutable rootfs state portable across incompatible runtime hosts.
8Response
Machine created
"mch_a1b2c3d4"
creating, running, paused, destroyed, error Machine metadata. Attached volume state is exposed under volume_attachments in request order. Free-form user-supplied object stored verbatim; deliberately open.
Alias of timeout_at for clients that expect an expiry timestamp field.
destroy, hibernate Normalized default working directory for this machine when one was configured.
Opaque token returned at create time. Send it as x-nullspace-traffic-access-token when network.allow_public_traffic is false.
Create-time warm-pool checkout result. Omitted when create did not consider a warm pool.