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

# Hibernate a machine

> Creates a resumable paused-machine snapshot and stops the running machine.
The returned snapshot is for pause/resume persistence; use
`POST /v1/machines/{id}/snapshots` to create a reusable 1-to-many
snapshot template while keeping the source machine running.
For shared volume mounts, live mount leases are released on successful
hibernate while the attachment intent remains durable in paused machine
metadata. Shared volume data is external storage, not part of the VM
snapshot.




## OpenAPI

````yaml /openapi.yaml post /v1/machines/{id}/hibernate
openapi: 3.1.0
info:
  title: Nullspace API
  version: 0.1.0
  description: |
    Cloud machine platform for AI agents. Create on-demand microVMs,
    execute commands, manage files, automate desktop environments,
    and stream output over WebSocket.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://api.13-215-85-171.sslip.io
    description: Private beta
  - url: https://nullspace.example
    description: Self-hosted single-host owned-domain
  - url: http://localhost
    description: Self-hosted single-host localhost/no-domain via Caddy
  - url: http://localhost:3000
    description: Local development direct API
security:
  - bearerAuth: []
tags:
  - name: Health
    description: Public process-liveness check (no auth required)
  - name: Machines
    description: Machine lifecycle, execution, and process management
  - name: Files
    description: Filesystem operations within a machine
  - name: Git
    description: First-class structured git operations within a machine
  - name: Desktop
    description: Desktop automation (mouse, keyboard, screenshots)
  - name: Recording
    description: Screen recording management
  - name: PTY
    description: Pseudo-terminal session management
  - name: Templates
    description: Machine template management
  - name: Agent Deployments
    description: Named, versioned agent deployment control plane
  - name: Volumes
    description: Persistent volume control plane and attached volume actions
  - name: WebSocket
    description: Streaming execution and PTY over WebSocket
  - name: Monitor
    description: In-repo WebSocket stream for machine health, metrics, and process updates
  - name: API Keys
    description: Runtime API key metadata and dormant self-serve key management
  - name: Account
    description: Dormant Supabase-session account profile, export, and deletion routes
  - name: Admin
    description: Supabase-session operator console APIs for account support
  - name: Auth
    description: Dormant self-serve Auth proxy routes gated by deployment config
  - name: Code
    description: Stateful code execution via Jupyter kernels (Code Interpreter)
  - name: Internal Operations
    description: Operator-only internal API surfaces; not part of the public SDK contract
paths:
  /v1/machines/{id}/hibernate:
    parameters:
      - $ref: '#/components/parameters/MachineId'
    post:
      tags:
        - Machines
      summary: Hibernate a machine
      description: >
        Creates a resumable paused-machine snapshot and stops the running
        machine.

        The returned snapshot is for pause/resume persistence; use

        `POST /v1/machines/{id}/snapshots` to create a reusable 1-to-many

        snapshot template while keeping the source machine running.

        For shared volume mounts, live mount leases are released on successful

        hibernate while the attachment intent remains durable in paused machine

        metadata. Shared volume data is external storage, not part of the VM

        snapshot.
      operationId: hibernateMachine
      responses:
        '200':
          description: Snapshot created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotInfo'
components:
  parameters:
    MachineId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Machine ID (e.g. mch_a1b2c3d4)
  schemas:
    SnapshotInfo:
      type: object
      required:
        - id
        - machine_id
        - size_bytes
        - created_at
      properties:
        id:
          type: string
        machine_id:
          type: string
        size_bytes:
          type: integer
          format: uint64
        created_at:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties: true
          description: >-
            User metadata attached to reusable snapshots. Legacy pause snapshots
            may omit this field.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token

````