Solution Model

Execution model

RAS launches the customer-supplied command on the Provider Agent and exchanges one JSON request and one JSON reply per line over stdin/stdout.

Protocol

The framework defines the interface, not the implementation. Customers can implement their logic in PowerShell, Python, or another language, provided the executable adheres to the JSON protocol and returns the expected payloads.

Capability-based behavior

The script declares what it supports. RAS should only invoke flows that the connector advertises as available.

API Reference

The Custom Provider interface is a JSON-based request/response protocol between Parallels RAS and the provider implementation. Each request identifies a method and, where required, a params object. Responses return either a result object on successful execution or an error object on failure. String-based parameter and payload values should be returned as JSON strings so they are correctly ingested by RAS. For example, guest identifiers, control values, IP addresses, and MAC addresses should be encoded as strings.

The sections below describe the currently supported methods, their purposes, expected request structures, expected success responses, and expected error responses.

1. provider/initialize - Used to determine protocol compatibility and the provider’s supported capabilities.

Request	{"method":"provider/initialize"}
Success response	{ "result": { "version": "1.0.0", "capabilities": { "can_suspend_guests": true, "guests_polling_rate": 30 } } }
Error response	{ "error": { "code": 1, "message": "Initialization failed" } }

Notes:

• Expected success response includes the protocol version and a capabilities object, including polling rate and supported optional features.

• guests_polling_rate is expressed in seconds and defines how often Parallels polls guest VMs for state changes.

1. provider/connect - Used to receive custom settings from RAS and establish the provider session.

	Request	{ "method": "provider/connect", "params": { "settings": { "host": "host.example.com", "username": "root@upn", "token_name": "automation", "token_secret": "<secret>" } } }
1	Success response	{ "result": {} }
2	Error response	{ "error": { "code": 1, "message": "Authentication failed" } }

Notes:

• Expected success response includes an empty result object.

• Sensitive settings such as token_secret, passwords, API keys, and access tokens should be treated as secrets. Use least-privilege service credentials, avoid embedding secrets directly in scripts, protect access to the RAS host and script directory, and rotate credentials according to your organization’s security policy.

1. provider/disconnect - Used to close the current provider session and clean up runtime state.

Request	{"method":"provider/disconnect"}
Success response	{ "result": {} }
Error response	{ "error": { "code": 1, "message": "Disconnect failed" } }

Note: Expected success response includes an empty result object.

1. guests/list - Used to retrieve the list of guest VMs known to the provider.

Request	{"method":"guests/list"}
Success response	{ "result": { "guests": ["vm-101", "vm-102", "vm-103"] } }
Error response	{ "error": { "code": 1, "message": "Failed to retrieve guest list" } }

Note: The expected success response includes an array of guest identifiers in the result.guests array.

1. guests/get - Used to retrieve guest information for a specific guest VM.

Request	{ "method": "guests/get", "params": { "id": "vm-123" } }
Success response	{ "result": { "name": "Win11-VDI-01", "state": "powered_on", "mac_addresses": [" 00:15:5d:8a:3c:ff "], "ip_addresses": ["10.0.10.25"], } }
Error response	{ "error": { "code": 1, "message": "Guest vm-123 not found" } }

Notes:

• Expected success response includes a guest object containing name, state, and ip_addresses.

• Power-state values include powered_off, powering_off, powered_on, powering_on, suspended, and suspending.

1. guests/control - Used to execute a lifecycle control action for a specific guest VM.

Request	{ "method": "guests/control", "params": { "id": "vm-123", "control": "stop" } }
Success response	{ "result": {} }
Error response	{ "error": { "code": 1, "message": "Control operation stop failed" } }

Notes:

• Expected success response includes an empty result object.

• Supported control values are start, stop, reset, and restart. The suspend control is requested only when the script advertises suspend capability through provider/initialize (Step 1 above).

• For the full list of standard error codes, see Appendix A.

1. tasks/get - Used to get the state of a running task

Request	{ "method": "tasks/get", "params": { "id": "vm-123" } }
Success response	{ "output": {} }
Error response	{ "error": {} }

Note: The state in the response can be:

• running: The task is still running.

• completed: The task has been completed.

• failed: The task has failed.

1. guests/convert - Used to convert a VM to a template

Request	{ "method": "guests/convert", "params": { "id": "vm-123", “is_template”: true } }
Success response	{ "task_id": {} }
Error response	{ "error": {} }

Note: is_template can be

• true: convert from VM to template

• false: convert from template to VM

1. guests/clone- Used to clone a VM from a template

Request	{ "method": "guests/clone", "params": { "id": "vm-123", “name”: “template1” “snapshot”: “RAS_TEMPLATE_VERSION_1” “is_link_clone”: true } }
Success response	{ "task_id": {} }
Error response	{ "error": {} }

Notes:

• Template VM snapshot name (only used by link clones and template versions).

• Is_link_clone only used by template versions, true create a link clone, false create a full clone.

1. guests/snapshots/create – Used to create a new snapshot

Request	{ "method": "guests/snapshots/create", "params": { "id": "vm-123", “name”: “RAS_TEMPLATE_VERSION_1” } }
Success response	{ "task_id": {} }
Error response	{ "error": {} }

Notes:

• Method required for creating link clones and template versions.

• Snapshots are identified by their name:

  • RAS Template Snapshot for link clones without template versions (RAS only creates this snapshot on the template VM).

  • RAS_TEMPLATE_VERSION_X for template versions, where X is the version number (RAS creates from 1 to 5 snapshots on the template VM).

1. guests/snapshots/exists– Used to check for the existence of a snapshot

Request	{ "method": "guests/snapshots/exists", "params": { "id": "vm-123", “name”: “RAS_TEMPLATE_VERSION_1” } }
Success response	{ true the snapshot exists false otherwise }
Error response	{ "error": {} }

Note: Snapshots are identified by their name:

• RAS Template Snapshot for link clones without template versions (RAS only creates this snapshot on the template VM).

• RAS_TEMPLATE_VERSION_X for template versions, where X is the version number (RAS creates from 1 to 5 snapshots on the template VM).

1. guests/snapshots/delete– Used to delete an existing snapshot

Request	{ "method": "guests/snapshots/delete", "params": { "id": "vm-123", “name”: “RAS_TEMPLATE_VERSION_1” } }
Success response	{ "task_id": {} }
Error response	{ "error": {} }

Note: Snapshots are identified by their name:

• RAS Template Snapshot for link clones without template versions (RAS only creates this snapshot on the template VM).

• RAS_TEMPLATE_VERSION_X for template versions, where X is the version number (RAS creates from 1 to 5 snapshots on the template VM).

1. guests/snapshots/revert– Used to switch the template VM to an existing snapshot

Request	{ "method": "guests/snapshots/revert", "params": { "id": "vm-123", “name”: “RAS_TEMPLATE_VERSION_1” } }
Success response	{ "task_id": {} }
Error response	{ "error": {} }

Notes:

• Switches the template VM to an existing snapshot (used when entering maintenance mode).

• Snapshots are identified by their name. Only required for template versions:

  • RAS Template Snapshot for link clones without template versions (RAS only creates this snapshot on the template VM).

  • RAS_TEMPLATE_VERSION_X for template versions, where X is the version number (RAS creates from 1 to 5 snapshots on the template VM).