Payloads API ​

Overview ​

The Payloads API manages the installation of different types of payloads (software packages, tools, apps) onto Virtual Machines (VMs).

Endpoints ​

Install Payload (POST /payloads/install/) ​

Installs a payload onto a specified VM. The behavior depends on the tag field, distinguishing between standard payloads, MCP payloads, and Applications (APP).

Request Body ​

{
  "vmid": "target-vm-uuid",
  "payloadid": "payload-uuid-or-name",
  "tag": "PayloadType" 
}

• vmid (string, required): The ID of the VM to install the payload onto.
• payloadid (string, required): The identifier of the payload to install.
• tag (string, required): Determines the type of payload and installation behavior:
  • "MCP": Treats the payload as an MCP tool. Files are copied to the VM's /mcp/servers persistent storage directory (storage/vms/{vmid}/mcp/servers/{payloadid}). If the VM is running, an entrypoint.sh script within the payload directory is executed synchronously inside the container.
  • "APP": Treats the payload as an Application installable via swiftly. payloadid must be a numeric string corresponding to an application index. No files are copied. If the VM is running, the swiftly install {app_name} command is executed asynchronously (in the background) inside the container.
  • Other values (e.g., "Payload", "Tool"): Treats as a standard payload. Files are copied to the VM's Desktop persistent storage directory (storage/vms/{vmid}/Desktop/{payloadid}). No commands are executed.

Behavior Notes ​

• File Copy: For Standard and MCP payloads, files are copied from the central payload store to the designated VM persistent storage path.
• Database Update: Records the installation for the user, associating the payloadid with the vmid and incrementing a per-user installation counter for that payload. If the record already exists, it adds the vmid to the list and increments the counter.
• Synchronous Execution (tag="MCP"): Requires the target VM to be running. The API call waits for the entrypoint.sh script to complete before responding.
• Asynchronous Execution (tag="APP"): Requires the target VM to be running. The API call initiates the swiftly install command in the background and returns a success message immediately. The actual installation continues within the VM container.

Response (Success) ​

// Example for Standard or MCP payload:
{
  "message": "Payload installed successfully",
  "installations": 3 
}

// Example for APP payload:
{
  "message": "Payload processed successfully. App installation initiated in background.",
  "installations": 1 // The user's total installation count for this specific payload/app
}

Report Abuse (POST /payloads/abuse) ​

Reports a malicious or problematic payload.

Request Body ​

{
  "payloadid": "payload_uuid",
  "description": "abuse description"
}

Get Abuse Reports (GET /payloads/abuse/{payloadid}) ​

Retrieves abuse reports for a payload.

Payload Types ​

Available payload categories:

• MCP Tools
• Development Tools
• Security Tools
• Productivity Apps
• Custom Configurations