> ## 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. # Fork (clone) a running machine > Fork creates a new machine from the parent's live machine state. Rootfs state diverges after the fork, but shared volume mounts in the child are remounted with fresh internal leases against the same backing shared volumes before the child becomes ready. Shared volume data does not make the VM snapshot portable across incompatible runtime hosts. ## OpenAPI ````yaml /openapi.yaml post /v1/machines/{id}/fork 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}/fork: parameters: - $ref: '#/components/parameters/MachineId' - $ref: '#/components/parameters/IdempotencyKeyHeader' post: tags: - Machines summary: Fork (clone) a running machine description: | Fork creates a new machine from the parent's live machine state. Rootfs state diverges after the fork, but shared volume mounts in the child are remounted with fresh internal leases against the same backing shared volumes before the child becomes ready. Shared volume data does not make the VM snapshot portable across incompatible runtime hosts. operationId: forkMachine responses: '201': description: Forked machine created content: application/json: schema: $ref: '#/components/schemas/MachineHandle' '404': $ref: '#/components/responses/MachineNotFound' '409': $ref: '#/components/responses/SnapshotCompatibilityConflict' components: parameters: MachineId: name: id in: path required: true schema: type: string description: Machine ID (e.g. mch_a1b2c3d4) IdempotencyKeyHeader: name: Idempotency-Key in: header required: true schema: type: string description: >- 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. schemas: MachineHandle: type: object required: - id - status - config - created_at properties: id: type: string status: $ref: '#/components/schemas/MachineStatus' config: $ref: '#/components/schemas/MachineConfig' cwd: type: string MachineStatus: type: string enum: - creating - running - paused - destroyed - error MachineConfig: type: object properties: vcpus: type: integer memory_mb: type: integer disk_mb: type: integer ErrorResponse: type: object required: - error - code properties: error: type: string description: Human-readable error message code: type: string description: Machine-readable error code enum: - invalid_request - machine_not_found - snapshot_not_found - template_not_found - template_build_not_found - template_name_claim_not_found - machine_not_ready - unauthorized - auth_failed - auth_locked - auth_proxy_error - auth_proxy_unavailable - invalid_auth_redirect - invalid_oauth_provider - captcha_required - captcha_failed - captcha_unavailable - disposable_email - signup_rate_limited - oauth_rate_limited - email_action_rate_limited - database_error - email_not_verified - account_deleted - operator_required - account_not_found - account_not_soft_deleted - account_hard_delete_active_resources - file_upload_error - build_error - exec_timeout - exec_failed - file_error - not_implemented - capacity_exceeded - QUOTA_EXCEEDED - feature_unavailable - snapshot_in_use - no_eligible_runtime_host - same_host_required - incompatible_snapshot - rebuild_required - rate_limit_exceeded - transition_in_progress - transition_conflict - agent_deployment_not_found - agent_deployment_version_not_found - agent_run_not_found - agent_service_instance_not_found - agent_deployment_name_conflict - agent_deployment_idempotency_mismatch - agent_deployment_invalid_config - agent_deployment_invalid_state - volume_beta_restriction - volume_invalid_mount_path - volume_overlapping_mounts - volume_backend_capability_unsupported - volume_quota_exceeded - volume_mount_credential_issue_failed - volume_backend_unavailable - volume_stale_revision - volume_busy - volume_read_only - volume_limit_exceeded - internal_error error_detail: $ref: '#/components/schemas/ErrorDetail' request_id: type: string description: Request correlation ID returned in the `x-request-id` header build_id: type: string description: Template build ID when the error is associated with a tracked build ErrorDetail: oneOf: - $ref: '#/components/schemas/TemplateFailureDetail' - $ref: '#/components/schemas/UploadFailureDetail' TemplateFailureDetail: type: object required: - code - message - phase - retryable - suggested_action properties: code: type: string enum: - unauthorized - file_upload_error - build_error - internal_error message: type: string phase: $ref: '#/components/schemas/TemplateFailurePhase' retryable: type: boolean suggested_action: type: string step_index: type: integer attempt: type: integer max_attempts: type: integer cache_subject: type: string build_id: type: string request_id: type: string description: >- Present on terminal request-originated failures and blocking error responses. details: type: object additionalProperties: true description: >- Stable failure metadata. Includes a `reason` key plus phase-specific fields such as `blob_id`, `path`, digest/size mismatch values, `command`, or `alias`. UploadFailureDetail: type: object required: - reason - message - retryable properties: reason: $ref: '#/components/schemas/UploadFailureReason' message: type: string retryable: type: boolean upload_id: type: string request_id: type: string path: type: string description: >- Normalized absolute machine path associated with the failed upload when available. part_number: type: integer format: uint32 details: type: object additionalProperties: true description: >- Additional failure diagnostics; keys depend on the failure reason, deliberately open. TemplateFailurePhase: type: string enum: - auth - preflight - blob_upload - prepare - build_step - readiness - snapshot - finalize - interrupted UploadFailureReason: type: string enum: - insufficient_staging_space - size_limit_exceeded - invalid_part_checksum - part_out_of_range - part_size_mismatch - whole_checksum_mismatch - upload_expired - upload_aborted - upload_already_completed - target_conflict - directory_extract_invalid_path - directory_extract_invalid_symlink - directory_extract_unsupported_entry - missing_parts responses: MachineNotFound: description: Machine not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' SnapshotCompatibilityConflict: description: >- Snapshot compatibility or lifecycle placement policy prevents the requested restore. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: sameHostRequired: summary: The original/source host is required value: error: Snapshot restore requires the original compatible runtime host code: same_host_required request_id: req_123 incompatibleSnapshot: summary: No compatible runtime host can restore the snapshot value: error: >- Snapshot compatibility class is incompatible with eligible runtime hosts code: incompatible_snapshot request_id: req_123 rebuildRequired: summary: A cold rebuild is required for a rebuild-capable flow value: error: >- Template snapshot is incompatible with the current runtime; rebuild the template code: rebuild_required request_id: req_123 securitySchemes: bearerAuth: type: http scheme: bearer description: API key passed as Bearer token ````