> For the complete documentation index, see [llms.txt](https://docs.parallels.com/landing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parallels.com/landing/ras-cpf-integration-guide/custom-provider-framework/solution-model.md). # 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"
}
}

| {% hint style="info" %} **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. {% endhint %} 2. **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": "\"
}
}
}

| | - | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Success response |

{
"result": {}
}

| | 2 | Error response |

{
"error": {
"code": 1,
"message": "Authentication failed"
}
}

| {% hint style="info" %} **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. {% endhint %} 3. **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"
}
}

| {% hint style="info" %} **Note**: Expected success response includes an empty result object. {% endhint %} 4. **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"
}
}

| {% hint style="info" %} **Note**: The expected success response includes an array of guest identifiers in the **result.guests** array. {% endhint %} 5. **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"
}
}

| {% hint style="info" %} **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`. {% endhint %} 6. **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"
}
}

| {% hint style="info" %} **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**. {% endhint %} 7. **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": {}
}

| {% hint style="info" %} **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. {% endhint %} 8. **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": {}
}

| {% hint style="info" %} **Note**: **is\_template** can be * `true`: convert from VM to template * `false`: convert from template to VM {% endhint %} 9. **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": {}
}

| {% hint style="info" %} **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. {% endhint %} 10. **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": {}
}

| {% hint style="info" %} **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). {% endhint %} 11. **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": {}
}

| {% hint style="info" %} **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). {% endhint %} 12. **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": {}
}

| {% hint style="info" %} **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). {% endhint %} 13. **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": {}
}

| {% hint style="info" %} **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). {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.parallels.com/landing/ras-cpf-integration-guide/custom-provider-framework/solution-model.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.