# Create a backup job (/en/docs/api/backup-jobs/create-backup-job) `POST https://api.hostd.cloud/v1/cloud/project/{uuid}/cluster/backup-jobs/` Creates a scheduled backup job for the listed VMs. The start time is assigned automatically between 00:00 and 06:00 (Europe/Warsaw). Each VM can be in one job only, and the number of jobs per project is limited. ## Parameters - `uuid` (path, required) `string`: Project UUID. ## Request (required) `application/json` ```json { "type": "object", "description": "Backup job to create.", "properties": { "weekdays": { "type": "array", "items": { "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "type": "string" }, "description": "Days of the week the job runs. At least one.", "minItems": 1 }, "retention": { "description": "Retention policy; periods left out or set to 0 are not kept. Empty or all zeros uses the default: 3 latest, 7 daily and 4 weekly backups.", "anyOf": [ { "type": "object", "properties": { "keep_last": { "type": "integer", "maximum": 99, "minimum": 0, "description": "Most recent backups to keep." }, "keep_hourly": { "type": "integer", "maximum": 24, "minimum": 0, "description": "Hourly backups to keep." }, "keep_daily": { "type": "integer", "maximum": 180, "minimum": 0, "description": "Daily backups to keep." }, "keep_weekly": { "type": "integer", "maximum": 52, "minimum": 0, "description": "Weekly backups to keep." }, "keep_monthly": { "type": "integer", "maximum": 24, "minimum": 0, "description": "Monthly backups to keep." }, "keep_yearly": { "type": "integer", "maximum": 5, "minimum": 0, "description": "Yearly backups to keep." } } }, { "type": "null" } ] }, "comment": { "type": "string", "default": "", "description": "Job name. Defaults to `{project name} backup`.", "maxLength": 512 }, "vmids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "VMIDs to back up. Each VM can be in one job only.", "minItems": 1 }, "enabled": { "type": "boolean", "default": true, "description": "Whether the job runs on schedule." } }, "required": [ "vmids", "weekdays" ] } ``` ## Responses ### 201 `application/json` ```json { "type": "object", "description": "Scheduled backup job of a project.", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "Backup job UUID." }, "comment": { "type": "string", "readOnly": true, "description": "Job name." }, "enabled": { "type": "boolean", "readOnly": true, "description": "Whether the job runs on schedule." }, "weekdays": { "type": "array", "items": { "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "type": "string" }, "readOnly": true, "description": "Days of the week the job runs." }, "schedule_slot": { "type": [ "string", "null" ], "readOnly": true, "description": "Start time (`HH:MM`, Europe/Warsaw) between 00:00 and 06:00. Assigned automatically." }, "retention": { "allOf": [ { "type": "object", "description": "How many backups are kept per period. `0` means the period is not kept; all zeros keeps every backup.", "properties": { "keep_last": { "type": "integer", "readOnly": true, "description": "Most recent backups to keep." }, "keep_hourly": { "type": "integer", "readOnly": true, "description": "Hourly backups to keep." }, "keep_daily": { "type": "integer", "readOnly": true, "description": "Daily backups to keep." }, "keep_weekly": { "type": "integer", "readOnly": true, "description": "Weekly backups to keep." }, "keep_monthly": { "type": "integer", "readOnly": true, "description": "Monthly backups to keep." }, "keep_yearly": { "type": "integer", "readOnly": true, "description": "Yearly backups to keep." } }, "required": [ "keep_daily", "keep_hourly", "keep_last", "keep_monthly", "keep_weekly", "keep_yearly" ] } ], "readOnly": true }, "vmids": { "type": "array", "items": { "type": "integer" }, "readOnly": true, "description": "VMIDs backed up by this job." } }, "required": [ "comment", "enabled", "retention", "schedule_slot", "uuid", "vmids", "weekdays" ] } ``` ### 400 The request is invalid, the job limit is reached, or a VM is already in another backup job. ### 403 You are not a member of this project, your role cannot write, a VM is not part of this project, or write access is blocked (card verification or billing hold). ### 404 Project not found. ### 502 The cluster could not complete the request. ### 503 No cluster servers available. # Delete a backup job (/en/docs/api/backup-jobs/delete-backup-job) `DELETE https://api.hostd.cloud/v1/cloud/project/{uuid}/cluster/backup-jobs/manage/{cloud_job_uuid}/` Removes the backup job and its schedule. Backups it already created stay on the backup server. ## Parameters - `cloud_job_uuid` (path, required) `string`: Backup job UUID (`uuid` from the backup job list). - `uuid` (path, required) `string`: Project UUID. ## Responses ### 204 The backup job was deleted. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 Project or backup job not found. ### 502 The cluster could not complete the request. ### 503 No cluster servers available. # List backup jobs (/en/docs/api/backup-jobs/list-backup-jobs) `GET https://api.hostd.cloud/v1/cloud/project/{uuid}/cluster/backup-jobs/` Returns the scheduled backup jobs of this project. Jobs always run between 00:00 and 06:00 (Europe/Warsaw); the start time is assigned automatically. ## Parameters - `uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "Scheduled backup job of a project.", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "Backup job UUID." }, "comment": { "type": "string", "readOnly": true, "description": "Job name." }, "enabled": { "type": "boolean", "readOnly": true, "description": "Whether the job runs on schedule." }, "weekdays": { "type": "array", "items": { "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "type": "string" }, "readOnly": true, "description": "Days of the week the job runs." }, "schedule_slot": { "type": [ "string", "null" ], "readOnly": true, "description": "Start time (`HH:MM`, Europe/Warsaw) between 00:00 and 06:00. Assigned automatically." }, "retention": { "allOf": [ { "type": "object", "description": "How many backups are kept per period. `0` means the period is not kept; all zeros keeps every backup.", "properties": { "keep_last": { "type": "integer", "readOnly": true, "description": "Most recent backups to keep." }, "keep_hourly": { "type": "integer", "readOnly": true, "description": "Hourly backups to keep." }, "keep_daily": { "type": "integer", "readOnly": true, "description": "Daily backups to keep." }, "keep_weekly": { "type": "integer", "readOnly": true, "description": "Weekly backups to keep." }, "keep_monthly": { "type": "integer", "readOnly": true, "description": "Monthly backups to keep." }, "keep_yearly": { "type": "integer", "readOnly": true, "description": "Yearly backups to keep." } }, "required": [ "keep_daily", "keep_hourly", "keep_last", "keep_monthly", "keep_weekly", "keep_yearly" ] } ], "readOnly": true }, "vmids": { "type": "array", "items": { "type": "integer" }, "readOnly": true, "description": "VMIDs backed up by this job." } }, "required": [ "comment", "enabled", "retention", "schedule_slot", "uuid", "vmids", "weekdays" ] } } ``` ### 403 You are not a member of this project. ### 404 Project not found. # List VMs without backup jobs (/en/docs/api/backup-jobs/list-vms-without-backups) `GET https://api.hostd.cloud/v1/cloud/project/{uuid}/cluster/vms-without-backups/` Returns the VMs of this project that are not included in any backup job. ## Parameters - `uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "A VM that no backup job of the project covers.", "properties": { "vmid": { "type": "integer", "description": "VM ID." }, "name": { "type": [ "string", "null" ], "description": "VM name; null when not set." } }, "required": [ "name", "vmid" ] } } ``` ### 403 You are not a member of this project. ### 404 Project not found. ### 502 The VM list could not be read from the cluster. ### 503 No cluster servers are available. # Update a backup job (/en/docs/api/backup-jobs/update-backup-job) `PATCH https://api.hostd.cloud/v1/cloud/project/{uuid}/cluster/backup-jobs/manage/{cloud_job_uuid}/` Changes the schedule days, retention, name, enabled state or VMs of a backup job. Only the fields you send are changed. Each VM can be in one job only. ## Parameters - `cloud_job_uuid` (path, required) `string`: Backup job UUID (`uuid` from the backup job list). - `uuid` (path, required) `string`: Project UUID. ## Request `application/json` ```json { "type": "object", "description": "Fields to change on a backup job. Omitted fields stay as they are.", "properties": { "weekdays": { "type": "array", "items": { "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "type": "string" }, "description": "Days of the week the job runs. At least one.", "minItems": 1 }, "retention": { "description": "Retention policy. Replaces the current one; periods left out or set to 0 are not kept. Empty or all zeros uses the default: 3 latest, 7 daily and 4 weekly backups.", "anyOf": [ { "type": "object", "properties": { "keep_last": { "type": "integer", "maximum": 99, "minimum": 0, "description": "Most recent backups to keep." }, "keep_hourly": { "type": "integer", "maximum": 24, "minimum": 0, "description": "Hourly backups to keep." }, "keep_daily": { "type": "integer", "maximum": 180, "minimum": 0, "description": "Daily backups to keep." }, "keep_weekly": { "type": "integer", "maximum": 52, "minimum": 0, "description": "Weekly backups to keep." }, "keep_monthly": { "type": "integer", "maximum": 24, "minimum": 0, "description": "Monthly backups to keep." }, "keep_yearly": { "type": "integer", "maximum": 5, "minimum": 0, "description": "Yearly backups to keep." } } }, { "type": "null" } ] }, "comment": { "type": "string", "description": "Job name. Empty resets it to `{project name} backup`.", "maxLength": 512 }, "vmids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "VMIDs backed up by this job. Replaces the current list; each VM can be in one job only." }, "enabled": { "type": "boolean", "description": "Whether the job runs on schedule." } } } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Scheduled backup job of a project.", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "Backup job UUID." }, "comment": { "type": "string", "readOnly": true, "description": "Job name." }, "enabled": { "type": "boolean", "readOnly": true, "description": "Whether the job runs on schedule." }, "weekdays": { "type": "array", "items": { "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "type": "string" }, "readOnly": true, "description": "Days of the week the job runs." }, "schedule_slot": { "type": [ "string", "null" ], "readOnly": true, "description": "Start time (`HH:MM`, Europe/Warsaw) between 00:00 and 06:00. Assigned automatically." }, "retention": { "allOf": [ { "type": "object", "description": "How many backups are kept per period. `0` means the period is not kept; all zeros keeps every backup.", "properties": { "keep_last": { "type": "integer", "readOnly": true, "description": "Most recent backups to keep." }, "keep_hourly": { "type": "integer", "readOnly": true, "description": "Hourly backups to keep." }, "keep_daily": { "type": "integer", "readOnly": true, "description": "Daily backups to keep." }, "keep_weekly": { "type": "integer", "readOnly": true, "description": "Weekly backups to keep." }, "keep_monthly": { "type": "integer", "readOnly": true, "description": "Monthly backups to keep." }, "keep_yearly": { "type": "integer", "readOnly": true, "description": "Yearly backups to keep." } }, "required": [ "keep_daily", "keep_hourly", "keep_last", "keep_monthly", "keep_weekly", "keep_yearly" ] } ], "readOnly": true }, "vmids": { "type": "array", "items": { "type": "integer" }, "readOnly": true, "description": "VMIDs backed up by this job." } }, "required": [ "comment", "enabled", "retention", "schedule_slot", "uuid", "vmids", "weekdays" ] } ``` ### 400 The request is invalid, or a VM is already in another backup job. ### 403 You are not a member of this project, your role cannot write, a VM is not part of this project, or write access is blocked (card verification or billing hold). ### 404 Project or backup job not found. ### 502 The cluster could not complete the request. ### 503 No cluster servers available. # Run a VM backup now (/en/docs/api/backups/create-vm-backup) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/backups/` Starts a backup of this VM right away; it works while the VM is running. Old backups are removed only by the retention of a backup job that includes this VM; without a job they are kept (and billed) until the VM is deleted. Returns 409 if a backup of this VM is already running and 429 after 2 backups started in the last 24 hours. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of a VM power action.", "properties": { "task_id": { "type": [ "string", "null" ], "description": "Cluster task ID, or null when HA applies the state change immediately." }, "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 409 A backup of this VM is already running. ### 429 2 backups of this VM were started in the last 24 hours. ### 500 The cluster could not complete the request. # Download a file from a backup (/en/docs/api/backups/download-backup-file) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/backup/datastore/file-restore/download/` Streams a file from a VM backup. For a directory or virtual disk, returns an archive: `.zip` by default, `.tar.zst` when `tar=1`. ## Parameters - `filepath` (query, required) `string`: Base64-encoded path (`filepath` from the file listing). - `project_uuid` (path, required) `string`: Project UUID. - `tar` (query) `boolean`: If true, archive directories as `.tar.zst` instead of `.zip`. Defaults to false. - `volume` (query, required) `string`: Backup ID (`volid` from the backup list). ## Responses ### 200 ### 400 The request is invalid. ### 403 You are not a member of this project. ### 404 The project has no backup datastore, or the backup was not found. ### 409 The backup is not ready to browse yet. Try again later. ### 500 No cluster servers available. ### 502 The backup server could not complete the request. # Get backup datastore usage (/en/docs/api/backups/get-datastore-status) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/backup/datastore/status/` Returns the number of backups and the space used by the project backup datastore. The figures come from the last garbage collection and may not match the sum of backup sizes until the next run. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Usage of the project backup datastore. Refreshed about every 12 hours.", "properties": { "vm_groups": { "type": [ "integer", "null" ], "readOnly": true, "description": "Number of VMs that have backups." }, "vm_snapshots": { "type": [ "integer", "null" ], "readOnly": true, "description": "Number of VM backups." }, "logical_bytes": { "type": [ "integer", "null" ], "readOnly": true, "description": "Size of the original data before deduplication, in bytes." }, "chunk_disk_bytes": { "type": [ "integer", "null" ], "readOnly": true, "description": "Space used on the backup server after deduplication and compression, in bytes. This is the billed size." }, "dedup_ratio": { "type": [ "number", "null" ], "format": "double", "readOnly": true, "description": "Original data size divided by on-disk size." } }, "required": [ "chunk_disk_bytes", "dedup_ratio", "logical_bytes", "vm_groups", "vm_snapshots" ] } ``` ### 403 You are not a member of this project. ### 404 The project has no backup datastore, or the backup was not found. ### 502 The backup server could not complete the request. # List files in a backup (/en/docs/api/backups/list-backup-files) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/backup/datastore/file-restore/list/` Browses the contents of a VM backup: virtual disks at the root, then directories and files. Pass the `filepath` of an entry to list what is inside it. ## Parameters - `filepath` (query) `string`: Base64-encoded path (`filepath` from a previous listing). Defaults to the backup root. - `project_uuid` (path, required) `string`: Project UUID. - `volume` (query, required) `string`: Backup ID (`volid` from the backup list). ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "File, directory or virtual disk inside a backup.", "properties": { "filepath": { "type": "string", "readOnly": true, "description": "Base64-encoded path. Pass it as `filepath` to list a directory or download an entry." }, "leaf": { "type": [ "boolean", "null" ], "readOnly": true, "description": "`true` for a file; otherwise a directory or virtual disk that can be listed." }, "mtime": { "type": [ "integer", "null" ], "readOnly": true, "description": "Modification time (Unix seconds)." }, "size": { "type": [ "integer", "null" ], "readOnly": true, "description": "Size in bytes." }, "text": { "type": "string", "readOnly": true, "description": "Entry name." }, "type": { "type": "string", "readOnly": true, "description": "Entry type: `v` virtual disk, `d` directory, `f` file." } }, "required": [ "filepath", "leaf", "mtime", "size", "text", "type" ] } } ``` ### 400 The request is invalid. ### 403 You are not a member of this project. ### 404 The project has no backup datastore, or the backup was not found. ### 409 The backup is not ready to browse yet. Try again later. ### 500 No cluster servers available. ### 502 The backup server could not complete the request. # List project backups (/en/docs/api/backups/list-datastore-backups) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/backup/datastore/content/` Returns every backup in the project backup datastore, across all VMs (including VMs that no longer exist). ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "One backup in the project backup datastore.", "properties": { "volid": { "type": "string", "readOnly": true, "description": "Backup ID. Pass it as `volid` or `volume` to the backup endpoints." }, "name": { "type": "string", "readOnly": true, "description": "Backup name: `{type}/{id}/{timestamp}`, e.g. `vm/100/2026-01-15T02:00:00Z`." }, "vmid": { "type": [ "integer", "null" ], "readOnly": true, "description": "VMID the backup was taken from. Null for non-VM backups." }, "size": { "type": [ "integer", "null" ], "readOnly": true, "description": "Backup size in bytes." }, "format": { "type": "string", "readOnly": true, "description": "Backup format, e.g. `pbs-vm`." }, "ctime": { "type": "integer", "readOnly": true, "description": "Backup creation time (Unix seconds)." }, "notes": { "type": [ "string", "null" ], "readOnly": true, "description": "Backup notes (the VM name at backup time)." }, "content": { "type": "string", "readOnly": true, "description": "Always `backup`." } }, "required": [ "content", "ctime", "format", "name", "notes", "size", "vmid", "volid" ] } } ``` ### 403 You are not a member of this project. ### 404 The project has no backup datastore, or the backup was not found. ### 502 The backup server could not complete the request. # List VM backups (/en/docs/api/backups/list-vm-backups) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/backups/` Returns backups of this VM on the project backup server, newest first. Returns 400 if the project has no backup storage. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "One backup of this VM on the project backup server.", "properties": { "created": { "type": "string", "format": "date-time", "description": "When the backup was created." }, "size": { "type": [ "string", "null" ], "description": "On-disk size as a human-readable string (IEC units)." }, "slug": { "type": "string", "description": "Backup identifier used in restore and delete URLs." }, "notes": { "type": [ "string", "null" ], "description": "First line of backup notes, when present." } }, "required": [ "created", "slug" ] } } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Restore a VM backup (/en/docs/api/backups/restore-vm-backup) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/backups/{backup_slug}/restore/` Restores this VM from the named backup. The VM must be stopped. `autostart` is not allowed for high-availability VMs. ## Parameters - `backup_slug` (path, required) `string`: Backup identifier (`slug` from the backup list). - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Request `application/json` ```json { "type": "object", "description": "Restore options. The VM must be stopped.", "properties": { "autostart": { "type": "boolean", "default": true, "description": "If true, start the VM after restore completes. Not allowed for high-availability VMs. Defaults to true." } } } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of a VM power action.", "properties": { "task_id": { "type": [ "string", "null" ], "description": "Cluster task ID, or null when HA applies the state change immediately." }, "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 409 The action is not allowed in the current VM or HA state. ### 500 The cluster could not complete the request. # Get a cluster (/en/docs/api/clusters/get-cluster) `GET https://api.hostd.cloud/v1/cloud/cluster/{name}/` Returns a single active Public Cloud cluster by name, including hourly pricing. ## Parameters - `name` (path, required) `string`: Cluster name (zone identifier), e.g. `waw-1`. ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Public Cloud cluster (zone) with location and hourly pricing.", "properties": { "name": { "type": "string", "description": "Cluster name (zone identifier), e.g. `waw-1`.", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Short description of the cluster." }, "location": { "type": "string", "description": "Physical location of the cluster, e.g. Warsaw.", "maxLength": 255 }, "price_model": { "readOnly": true, "description": "Hourly prices in PLN for this cluster.", "anyOf": [ { "type": "object", "description": "Hourly prices in PLN for Public Cloud resources on a cluster.", "properties": { "vcore_regular": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Regular vCPU price, PLN per vCPU-hour." }, "vcore_light": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Light vCPU price, PLN per vCPU-hour." }, "vcore_off": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Stopped vCPU price, PLN per vCPU-hour." }, "ram": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "RAM price, GiB/hour" }, "ram_off": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "RAM price for disabled VM, GiB/hour" }, "storage_fast": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "readOnly": true, "description": "Fast block storage (NVMe) price, GiB/hour." }, "public_ip": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Public IP price, IP/hour" }, "private_network_tag": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Private network (tag) price, network/hour" }, "private_network_external_vlan": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Private network (external VLAN) price, network/hour" }, "cloud_gateway_standard": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Cloud Gateway (standard tier) price, gateway/hour" }, "pbs_pool": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "PBS datastore real usage price, GiB/hour" } }, "required": [ "pbs_pool", "public_ip", "ram", "ram_off", "storage_fast", "vcore_off" ] }, { "type": "null" } ] } }, "required": [ "location", "name", "price_model" ] } ``` ### 404 Cluster not found or not available. # List clusters (/en/docs/api/clusters/list-clusters) `GET https://api.hostd.cloud/v1/cloud/cluster/` Returns active Public Cloud clusters (zones) that accept new projects, including location and hourly pricing. Authentication is not required. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "Public Cloud cluster (zone) with location and hourly pricing.", "properties": { "name": { "type": "string", "description": "Cluster name (zone identifier), e.g. `waw-1`.", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Short description of the cluster." }, "location": { "type": "string", "description": "Physical location of the cluster, e.g. Warsaw.", "maxLength": 255 }, "price_model": { "readOnly": true, "description": "Hourly prices in PLN for this cluster.", "anyOf": [ { "type": "object", "description": "Hourly prices in PLN for Public Cloud resources on a cluster.", "properties": { "vcore_regular": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Regular vCPU price, PLN per vCPU-hour." }, "vcore_light": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Light vCPU price, PLN per vCPU-hour." }, "vcore_off": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Stopped vCPU price, PLN per vCPU-hour." }, "ram": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "RAM price, GiB/hour" }, "ram_off": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "RAM price for disabled VM, GiB/hour" }, "storage_fast": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "readOnly": true, "description": "Fast block storage (NVMe) price, GiB/hour." }, "public_ip": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Public IP price, IP/hour" }, "private_network_tag": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Private network (tag) price, network/hour" }, "private_network_external_vlan": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Private network (external VLAN) price, network/hour" }, "cloud_gateway_standard": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Cloud Gateway (standard tier) price, gateway/hour" }, "pbs_pool": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "PBS datastore real usage price, GiB/hour" } }, "required": [ "pbs_pool", "public_ip", "ram", "ram_off", "storage_fast", "vcore_off" ] }, { "type": "null" } ] } }, "required": [ "location", "name", "price_model" ] } } ``` # Create a VM firewall rule (/en/docs/api/firewall/create-vm-firewall-rule) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/firewall/rules/` Adds an inbound/outbound rule, or attaches a project security group (`type=group`). ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Request (required) `application/json` ```json { "type": "object", "description": "Create or update a VM firewall rule, or attach a security group.", "properties": { "pos": { "type": "integer", "description": "Rule position to update (required for PUT)." }, "position": { "type": "integer", "description": "Insert at this position (POST). Omit to append." }, "type": { "allOf": [ { "enum": [ "in", "out", "group" ], "type": "string" } ], "description": "`in` / `out` for a packet filter, or `group` to attach a security group." }, "action": { "type": "string", "description": "`ACCEPT` or `DROP`, or the security-group identifier when `type` is `group`." }, "proto": { "allOf": [ { "enum": [ "tcp", "udp", "icmp" ], "type": "string" } ], "description": "Required for `in` / `out` rules." }, "source": { "type": "string", "description": "Source IPv4 or IPv6 address, CIDR (IPv4 up to /26, IPv6 up to /64), IPv4 range, or IP set as `+`." }, "dest": { "type": "string", "description": "Destination IPv4 or IPv6 address, CIDR (IPv4 up to /26, IPv6 up to /64), IPv4 range, or IP set as `+`." }, "sport": { "type": "string", "description": "Source port or range." }, "dport": { "type": "string", "description": "Destination port or range." }, "comment": { "type": "string", "description": "Optional comment." }, "enable": { "type": "boolean", "description": "Whether the rule is enabled." } }, "required": [ "action", "enable", "type" ] } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a VM write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Delete a VM firewall rule (/en/docs/api/firewall/delete-vm-firewall-rule) `DELETE https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/firewall/rules/` Deletes the rule at `pos`. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a VM write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM or firewall rule not found in this project. ### 500 The cluster could not complete the request. # Get the project firewall (/en/docs/api/firewall/get-project-firewall) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/map/` Returns the whole firewall setup of the project in one request: security groups with their rules, IP sets with their members, and the firewall options and rules of every VM. Use it to see which VMs use a security group (a rule with `type` `group` has the group's `pve_group_name` as `action`) or an IP set (`+` in `source` or `dest`). A `null` value means that state is temporarily unavailable. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "object", "description": "The firewall setup of a project: security groups, IP sets, and the firewall of every VM.", "properties": { "security_groups": { "type": "array", "items": { "type": "object", "description": "A security group with its rules.", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "Security group UUID." }, "display_name": { "type": "string", "readOnly": true, "description": "Group name." }, "pve_group_name": { "type": "string", "readOnly": true, "description": "Identifier that VM firewall rules use as `action` when `type` is `group`." }, "comment": { "type": "string", "readOnly": true, "description": "Free-text comment." }, "rules": { "type": [ "array", "null" ], "items": { "type": "object", "description": "One packet-filter rule of a security group.", "properties": { "pos": { "type": "integer", "description": "Rule position (0-based)." }, "type": { "type": "string", "description": "`in` or `out`." }, "action": { "type": "string", "description": "`ACCEPT` or `DROP`." }, "proto": { "type": "string", "description": "`tcp`, `udp`, or `icmp`." }, "source": { "type": [ "string", "null" ], "description": "Source address, CIDR, or IP set as `+`." }, "dest": { "type": [ "string", "null" ], "description": "Destination address, CIDR, or IP set as `+`." }, "sport": { "type": [ "string", "null" ], "description": "Source port or range." }, "dport": { "type": [ "string", "null" ], "description": "Destination port or range." }, "comment": { "type": [ "string", "null" ], "description": "Optional comment." }, "enable": { "type": [ "boolean", "null" ], "description": "Whether the rule is enabled." } }, "required": [ "action", "pos", "proto", "type" ] }, "description": "Group rules. `null` when the state is temporarily unavailable." } }, "required": [ "comment", "display_name", "pve_group_name", "rules", "uuid" ] }, "description": "Project security groups." }, "ip_sets": { "type": "array", "items": { "type": "object", "description": "An IP set with its members.", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "IP set UUID." }, "display_name": { "type": "string", "readOnly": true, "description": "IP set name." }, "pve_ipset_name": { "type": "string", "readOnly": true, "description": "Identifier that firewall rules use to reference the set, as `+`." }, "comment": { "type": "string", "readOnly": true, "description": "Free-text comment." }, "members": { "type": [ "array", "null" ], "items": { "type": "object", "description": "One address or network in an IP set.", "properties": { "cidr": { "type": "string", "description": "IPv4 or IPv6 address or CIDR." }, "comment": { "type": "string", "description": "Optional comment." }, "nomatch": { "type": "boolean", "description": "If true, the entry is excluded from the set instead of included." } }, "required": [ "cidr", "comment", "nomatch" ] }, "description": "Addresses and networks in the set. `null` when the list is temporarily unavailable." } }, "required": [ "comment", "display_name", "members", "pve_ipset_name", "uuid" ] }, "description": "Project IP sets." }, "vms": { "type": "array", "items": { "type": "object", "description": "Firewall options and rules of one VM.", "properties": { "vmid": { "type": "integer", "description": "VM ID." }, "options": { "description": "Firewall options. `null` when the state is temporarily unavailable.", "anyOf": [ { "type": "object", "description": "VM firewall options the portal can read and set.", "properties": { "enable": { "type": [ "boolean", "null" ], "description": "Whether the VM firewall is enabled." }, "policy_in": { "nullable": true, "description": "Default policy for inbound traffic.", "oneOf": [ { "enum": [ "ACCEPT", "DROP" ], "type": "string" }, { "enum": [ null ] } ] }, "policy_out": { "nullable": true, "description": "Default policy for outbound traffic.", "oneOf": [ { "enum": [ "ACCEPT", "DROP" ], "type": "string" }, { "enum": [ null ] } ] } } }, { "type": "null" } ] }, "rules": { "type": [ "array", "null" ], "items": { "type": "object", "description": "One VM firewall rule or an attached security group.", "properties": { "pos": { "type": "integer", "description": "Rule position (0-based)." }, "type": { "type": "string", "description": "`in`, `out`, or `group`." }, "action": { "type": [ "string", "null" ], "description": "`ACCEPT` or `DROP`, or the security-group name when `type` is `group`." }, "proto": { "type": [ "string", "null" ], "description": "`tcp`, `udp`, or `icmp`. Empty for a security-group rule." }, "source": { "type": [ "string", "null" ], "description": "Source address, CIDR, or IP set as `+`." }, "dest": { "type": [ "string", "null" ], "description": "Destination address, CIDR, or IP set as `+`." }, "sport": { "type": [ "string", "null" ], "description": "Source port or range." }, "dport": { "type": [ "string", "null" ], "description": "Destination port or range." }, "comment": { "type": [ "string", "null" ], "description": "Optional comment." }, "enable": { "type": [ "boolean", "null" ], "description": "Whether the rule is enabled." } }, "required": [ "pos", "type" ] }, "description": "VM rules. `null` when the state is temporarily unavailable." } }, "required": [ "options", "rules", "vmid" ] }, "description": "Firewall of each VM in the project." } }, "required": [ "ip_sets", "security_groups", "vms" ] } ``` ### 403 You are not a member of this project. # Get VM firewall options (/en/docs/api/firewall/get-vm-firewall-config) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/firewall/config/` Returns whether the VM firewall is enabled and the default inbound/outbound policies. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "VM firewall options the portal can read and set.", "properties": { "enable": { "type": [ "boolean", "null" ], "description": "Whether the VM firewall is enabled." }, "policy_in": { "nullable": true, "description": "Default policy for inbound traffic.", "oneOf": [ { "enum": [ "ACCEPT", "DROP" ], "type": "string" }, { "enum": [ null ] } ] }, "policy_out": { "nullable": true, "description": "Default policy for outbound traffic.", "oneOf": [ { "enum": [ "ACCEPT", "DROP" ], "type": "string" }, { "enum": [ null ] } ] } } } ``` ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # List VM firewall rules (/en/docs/api/firewall/list-vm-firewall-rules) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/firewall/rules/` Returns packet-filter rules and attached security groups for this VM. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "One VM firewall rule or an attached security group.", "properties": { "pos": { "type": "integer", "description": "Rule position (0-based)." }, "type": { "type": "string", "description": "`in`, `out`, or `group`." }, "action": { "type": [ "string", "null" ], "description": "`ACCEPT` or `DROP`, or the security-group name when `type` is `group`." }, "proto": { "type": [ "string", "null" ], "description": "`tcp`, `udp`, or `icmp`. Empty for a security-group rule." }, "source": { "type": [ "string", "null" ], "description": "Source address, CIDR, or IP set as `+`." }, "dest": { "type": [ "string", "null" ], "description": "Destination address, CIDR, or IP set as `+`." }, "sport": { "type": [ "string", "null" ], "description": "Source port or range." }, "dport": { "type": [ "string", "null" ], "description": "Destination port or range." }, "comment": { "type": [ "string", "null" ], "description": "Optional comment." }, "enable": { "type": [ "boolean", "null" ], "description": "Whether the rule is enabled." } }, "required": [ "pos", "type" ] } } ``` ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Reorder a VM firewall rule (/en/docs/api/firewall/move-vm-firewall-rule) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/firewall/rules/move/` Moves the rule at `from_pos` to `to_pos`. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Request (required) `application/json` ```json { "type": "object", "description": "Reorder a VM firewall rule.", "properties": { "from_pos": { "type": "integer", "description": "Current rule position." }, "to_pos": { "type": "integer", "description": "New rule position." } }, "required": [ "from_pos", "to_pos" ] } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a VM write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM or firewall rule not found in this project. ### 500 The cluster could not complete the request. # Replace all VM firewall rules (/en/docs/api/firewall/replace-vm-firewall-rules) `PUT https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/firewall/rules/replace/` Sets the full ordered list of rules and attached security groups. Every rule is validated first; nothing changes if one is invalid. Unchanged positions are kept, and a changed rule is replaced without leaving a gap. Returns the resulting rules. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Request (required) `application/json` ```json { "type": "object", "description": "The full VM rule list.", "properties": { "rules": { "type": "array", "items": { "type": "object", "description": "One rule in the full VM rule list.", "properties": { "type": { "allOf": [ { "enum": [ "in", "out", "group" ], "type": "string" } ], "description": "`in` / `out` for a packet filter, or `group` to attach a security group." }, "action": { "type": "string", "description": "`ACCEPT` or `DROP`, or the security-group identifier when `type` is `group`." }, "proto": { "allOf": [ { "enum": [ "tcp", "udp", "icmp" ], "type": "string" } ], "description": "Required for `in` / `out` rules." }, "source": { "type": "string", "description": "Source IPv4 or IPv6 address, CIDR (IPv4 up to /26, IPv6 up to /64), IPv4 range, or IP set as `+`." }, "dest": { "type": "string", "description": "Destination IPv4 or IPv6 address, CIDR (IPv4 up to /26, IPv6 up to /64), IPv4 range, or IP set as `+`." }, "sport": { "type": "string", "description": "Source port or range." }, "dport": { "type": "string", "description": "Destination port or range." }, "comment": { "type": "string", "description": "Optional comment." }, "enable": { "type": "boolean", "description": "Whether the rule is enabled." } }, "required": [ "action", "enable", "type" ] }, "description": "All rules and attached security groups in evaluation order. An empty list removes every rule." } }, "required": [ "rules" ] } ``` ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "One VM firewall rule or an attached security group.", "properties": { "pos": { "type": "integer", "description": "Rule position (0-based)." }, "type": { "type": "string", "description": "`in`, `out`, or `group`." }, "action": { "type": [ "string", "null" ], "description": "`ACCEPT` or `DROP`, or the security-group name when `type` is `group`." }, "proto": { "type": [ "string", "null" ], "description": "`tcp`, `udp`, or `icmp`. Empty for a security-group rule." }, "source": { "type": [ "string", "null" ], "description": "Source address, CIDR, or IP set as `+`." }, "dest": { "type": [ "string", "null" ], "description": "Destination address, CIDR, or IP set as `+`." }, "sport": { "type": [ "string", "null" ], "description": "Source port or range." }, "dport": { "type": [ "string", "null" ], "description": "Destination port or range." }, "comment": { "type": [ "string", "null" ], "description": "Optional comment." }, "enable": { "type": [ "boolean", "null" ], "description": "Whether the rule is enabled." } }, "required": [ "pos", "type" ] } } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Set VM firewall options (/en/docs/api/firewall/update-vm-firewall-config) `PUT https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/firewall/config/` Sets enable and default inbound/outbound policies. Other Proxmox firewall flags are fixed by the platform. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Request (required) `application/json` ```json { "type": "object", "description": "Set VM firewall options. Other Proxmox flags are fixed by the platform.", "properties": { "enable": { "type": "boolean", "description": "Whether the VM firewall is enabled." }, "policy_in": { "allOf": [ { "enum": [ "ACCEPT", "DROP" ], "type": "string" } ], "description": "Default policy for inbound traffic." }, "policy_out": { "allOf": [ { "enum": [ "ACCEPT", "DROP" ], "type": "string" } ], "description": "Default policy for outbound traffic." } }, "required": [ "enable", "policy_in", "policy_out" ] } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a VM write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Update a VM firewall rule (/en/docs/api/firewall/update-vm-firewall-rule) `PUT https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/firewall/rules/` Updates the rule at `pos`. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Request (required) `application/json` ```json { "type": "object", "description": "Create or update a VM firewall rule, or attach a security group.", "properties": { "pos": { "type": "integer", "description": "Rule position to update (required for PUT)." }, "position": { "type": "integer", "description": "Insert at this position (POST). Omit to append." }, "type": { "allOf": [ { "enum": [ "in", "out", "group" ], "type": "string" } ], "description": "`in` / `out` for a packet filter, or `group` to attach a security group." }, "action": { "type": "string", "description": "`ACCEPT` or `DROP`, or the security-group identifier when `type` is `group`." }, "proto": { "allOf": [ { "enum": [ "tcp", "udp", "icmp" ], "type": "string" } ], "description": "Required for `in` / `out` rules." }, "source": { "type": "string", "description": "Source IPv4 or IPv6 address, CIDR (IPv4 up to /26, IPv6 up to /64), IPv4 range, or IP set as `+`." }, "dest": { "type": "string", "description": "Destination IPv4 or IPv6 address, CIDR (IPv4 up to /26, IPv6 up to /64), IPv4 range, or IP set as `+`." }, "sport": { "type": "string", "description": "Source port or range." }, "dport": { "type": "string", "description": "Destination port or range." }, "comment": { "type": "string", "description": "Optional comment." }, "enable": { "type": "boolean", "description": "Whether the rule is enabled." } }, "required": [ "action", "enable", "type" ] } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a VM write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM or firewall rule not found in this project. ### 500 The cluster could not complete the request. # Create an HA rule (/en/docs/api/high-availability/create-ha-rule) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/ha/rules/` Creates a placement rule for 2 to 3 VMs of the project: keep them on separate nodes (`negative`, the default) or on the same node (`positive`). HA is enabled on the listed VMs if it is not yet. Each VM can be in one rule only. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Request (required) `application/json` ```json { "type": "object", "description": "HA rule to create.", "properties": { "vmids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "VMIDs the rule applies to: 2 to 3, no duplicates. Each VM can be in one rule only. HA is enabled on these VMs if it is not yet." }, "affinity": { "allOf": [ { "enum": [ "positive", "negative" ], "type": "string" } ], "default": "negative", "description": "`negative` keeps the VMs on separate nodes, `positive` keeps them on the same node. Defaults to `negative`." } }, "required": [ "vmids" ] } ``` ## Responses ### 201 `application/json` ```json { "type": "object", "description": "HA placement rule for VMs of a project.", "properties": { "rule": { "type": "string", "description": "Rule ID." }, "affinity": { "allOf": [ { "enum": [ "positive", "negative" ], "type": "string" } ], "description": "`negative` keeps the VMs on separate nodes, `positive` keeps them on the same node." }, "enabled": { "type": "boolean", "description": "Whether the rule is applied." }, "vmids": { "type": "array", "items": { "type": "integer" }, "description": "VMIDs the rule applies to." }, "managed": { "type": "boolean", "description": "True for rules created through the portal or API. Only these can have their VMs or affinity changed." } }, "required": [ "affinity", "enabled", "managed", "rule", "vmids" ] } ``` ### 400 The request is invalid, a VM is not part of this project, a VM is already in another rule, or a VM has rescue mode on. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 Project not found. ### 500 The cluster could not complete the request. # Delete an HA rule (/en/docs/api/high-availability/delete-ha-rule) `DELETE https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/ha/rules/{rule_id}/` Removes the rule. HA stays enabled on its VMs. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `rule_id` (path, required) `string`: HA rule ID (`rule` from the HA overview). ## Responses ### 204 The rule was deleted. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 Project or HA rule not found. ### 500 The cluster could not complete the request. # Disable HA for a VM (/en/docs/api/high-availability/disable-vm-ha) `DELETE https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/ha/` Removes the VM from high availability and from its HA rules. Returns 409 if HA is not enabled. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a VM write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 409 The action is not allowed in the current VM or HA state. ### 500 The cluster could not complete the request. # Enable HA for a VM (/en/docs/api/high-availability/enable-vm-ha) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/ha/` Places the VM under high availability (`state=started`). Returns 409 if HA is already enabled. Returns 400 while rescue mode is on. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a VM write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 Disable rescue mode before enabling high availability. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 409 The action is not allowed in the current VM or HA state. ### 500 The cluster could not complete the request. # Get project HA state (/en/docs/api/high-availability/get-project-ha) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/ha/` Returns the VMs that have HA enabled and the HA placement rules of the project. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "object", "description": "High availability state of a project.", "properties": { "ha_vmids": { "type": "array", "items": { "type": "integer" }, "description": "VMIDs with HA enabled." }, "affinity_rules": { "type": "array", "items": { "type": "object", "description": "HA placement rule for VMs of a project.", "properties": { "rule": { "type": "string", "description": "Rule ID." }, "affinity": { "allOf": [ { "enum": [ "positive", "negative" ], "type": "string" } ], "description": "`negative` keeps the VMs on separate nodes, `positive` keeps them on the same node." }, "enabled": { "type": "boolean", "description": "Whether the rule is applied." }, "vmids": { "type": "array", "items": { "type": "integer" }, "description": "VMIDs the rule applies to." }, "managed": { "type": "boolean", "description": "True for rules created through the portal or API. Only these can have their VMs or affinity changed." } }, "required": [ "affinity", "enabled", "managed", "rule", "vmids" ] } } }, "required": [ "affinity_rules", "ha_vmids" ] } ``` ### 403 You are not a member of this project. ### 404 Project not found. ### 500 The cluster could not complete the request. # Update an HA rule (/en/docs/api/high-availability/update-ha-rule) `PATCH https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/ha/rules/{rule_id}/` Changes the VMs, the affinity or the enabled state of a rule. Only the fields you send are changed. VMs and affinity can be changed only on rules created through the portal or API (`managed`). ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `rule_id` (path, required) `string`: HA rule ID (`rule` from the HA overview). ## Request `application/json` ```json { "type": "object", "description": "Fields to change on an HA rule. Omitted fields stay as they are.", "properties": { "vmids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "VMIDs the rule applies to: 2 to 3, no duplicates. Each VM can be in one rule only. HA is enabled on these VMs if it is not yet." }, "affinity": { "allOf": [ { "enum": [ "positive", "negative" ], "type": "string" } ], "description": "`negative` keeps the VMs on separate nodes, `positive` keeps them on the same node." }, "enabled": { "type": "boolean", "description": "Whether the rule is applied." } } } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "HA placement rule for VMs of a project.", "properties": { "rule": { "type": "string", "description": "Rule ID." }, "affinity": { "allOf": [ { "enum": [ "positive", "negative" ], "type": "string" } ], "description": "`negative` keeps the VMs on separate nodes, `positive` keeps them on the same node." }, "enabled": { "type": "boolean", "description": "Whether the rule is applied." }, "vmids": { "type": "array", "items": { "type": "integer" }, "description": "VMIDs the rule applies to." }, "managed": { "type": "boolean", "description": "True for rules created through the portal or API. Only these can have their VMs or affinity changed." } }, "required": [ "affinity", "enabled", "managed", "rule", "vmids" ] } ``` ### 400 The request is invalid, a VM is not part of this project, a VM is already in another rule, or a VM has rescue mode on. ### 403 You are not a member of this project, your role cannot write, the rule is not `managed` (VMs and affinity cannot be changed), or write access is blocked (card verification or billing hold). ### 404 Project or HA rule not found. ### 500 The cluster could not complete the request. # API documentation (/en/docs/api) The hostd API lets you manage your account programmatically. Base URL: `https://api.hostd.cloud/v1`. ## Authentication [#authentication] Most endpoints require an API key. Create a key in the portal under [Settings → API Keys](https://hostd.cloud/app/settings/api-keys) and send it as a Bearer token: ```http Authorization: Bearer ``` ```bash curl -H "Authorization: Bearer " https://api.hostd.cloud/v1/network/ips/ ``` Listing clusters is public and does not require authentication. A key acts on your behalf and never exceeds your role in a project (including projects shared with you). When you create or edit a key, choose what it can reach: - **Projects** – choose projects one by one, with **Read** (reads only), **Write** (everything except deleting), or **Full** (also deletes VMs, the project, and public IPs) access. A new key has no access until you choose. - **Create new projects** – allowed separately. The key gets **Full** access to the projects it creates. - **SSH keys** – **No access**, **Read**, or **Write**. - **Expiration** – 30 days, 90 days, 1 year, a custom date, or no expiration. We email you 7 days before a key expires. IP addresses of dedicated servers and VPS are not available with API keys. A key works only with the endpoints in this reference – account settings, billing, support, and API key management are available only in the portal. The same access applies to the [MCP server](/en/docs/mcp). ## Limits [#limits] Requests with an API key are limited per account (all keys share the limit): - 10 requests per second; - 90 write requests (`POST`, `PUT`, `PATCH`, `DELETE`) per minute. Above the limit the API returns `429 Too Many Requests` with a `Retry-After` header (seconds). Wait that long before retrying. ## AI agents [#ai-agents] The [MCP server](/en/docs/mcp) gives AI agents (Cursor, Claude Code) access to the same API. ## Endpoints [#endpoints] - [Clusters](/en/docs/api/clusters/list-clusters) – Public Cloud zones and hourly pricing. - [Projects](/en/docs/api/projects/list-projects) – projects, account usage, and cluster tasks. - [Virtual machines](/en/docs/api/virtual-machines/list-vms) – create, delete, inventory, OS images, configuration, metrics, power, resize, and notes. - [High availability](/en/docs/api/high-availability/get-project-ha) – enable HA per VM and manage placement rules. - [SSH keys](/en/docs/api/ssh-keys/list-ssh-keys) – SSH public keys on your account, used when creating VMs. - [Private networks](/en/docs/api/private-networks/list-private-network-ips) – free and used addresses in a private network. - [Snapshots](/en/docs/api/snapshots/list-vm-snapshots) – one snapshot per VM. - [Backups](/en/docs/api/backups/list-vm-backups) – run a VM backup now, restore VM backups, browse the project backup datastore, and download files from a backup. - [Backup jobs](/en/docs/api/backup-jobs/list-backup-jobs) – scheduled backup jobs of a project. - [Firewall](/en/docs/api/firewall/get-vm-firewall-config) – the project firewall in one request, and per-VM firewall options and rules, one at a time or the whole ordered list in one request. - [Security groups](/en/docs/api/security-groups/list-security-groups) – project security groups and their rules, one at a time or the whole ordered list in one request. - [IP sets](/en/docs/api/ip-sets/list-ip-sets) – project IP sets and their members. - [IP addresses](/en/docs/api/ip-addresses/list-ip-addresses) – assigned IP addresses and PTR records (account-wide and per project). # Get an IP address (/en/docs/api/ip-addresses/get-ip-address) `GET https://api.hostd.cloud/v1/network/ips/{ip}/` Returns a single IP address with its PTR record. ## Parameters - `ip` (path, required) `string`: IPv4 or IPv6 address assigned to one of your services (URL-encoded). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "IP address with its PTR record.", "properties": { "ip": { "type": [ "string", "null" ], "readOnly": true, "description": "IPv4 address." }, "content": { "type": [ "string", "null" ], "readOnly": true, "description": "Current PTR record (reverse DNS hostname); null when not set." }, "comment": { "type": [ "string", "null" ], "readOnly": true, "description": "Internal comment shown in the portal." }, "can_update_ptr": { "type": "boolean", "readOnly": true, "description": "Whether you may change the PTR record." } }, "required": [ "can_update_ptr", "comment", "content", "ip" ] } ``` ### 403 The IP is not assigned to any of your services. ### 404 Invalid IP address format. # List IP addresses (/en/docs/api/ip-addresses/list-ip-addresses) `GET https://api.hostd.cloud/v1/network/ips/` Returns IP addresses assigned to your services (dedicated servers, VPS, cloud projects) together with their current PTR record. `can_update_ptr` shows whether you may change the PTR record (service owner, shared access with the rDNS permission, or a cloud project role with network write). ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "IP address assigned to one of your services, with its current PTR record.", "properties": { "ip": { "type": [ "string", "null" ], "readOnly": true, "description": "IPv4 address." }, "content": { "type": [ "string", "null" ], "readOnly": true, "description": "Current PTR record (reverse DNS hostname); null when not set." }, "comment": { "type": [ "string", "null" ], "readOnly": true, "description": "Internal comment shown in the portal." }, "can_update_ptr": { "type": "boolean", "readOnly": true, "description": "Whether you may change the PTR record." }, "service_kind": { "type": [ "string", "null" ], "readOnly": true, "description": "Service the IP is attached to: \"ds\", \"vps\" or \"cloud\"." }, "service_name": { "type": "string", "readOnly": true, "description": "Name of the service the IP is attached to." }, "service_sid": { "type": [ "string", "null" ], "readOnly": true, "description": "Service SID for dedicated/VPS; null when service_kind is \"cloud\"." }, "service_uuid": { "type": [ "string", "null" ], "readOnly": true, "description": "UUID of the dedicated server, VPS or cloud project." }, "status": { "type": "string", "readOnly": true, "description": "`attached` when in use (dedicated server, VPS, cloud VM or Cloud Gateway); `reserved` when a cloud IP is reserved in the project without being used." }, "vm": { "readOnly": true, "description": "Cloud only: project VM the IP is attached to; otherwise null.", "anyOf": [ { "type": "object", "description": "Project VM a cloud IP is attached to.", "properties": { "vmid": { "type": "integer", "description": "VMID." }, "name": { "type": [ "string", "null" ], "description": "VM name; null when not set." } }, "required": [ "name", "vmid" ] }, { "type": "null" } ] }, "can_release": { "type": "boolean", "readOnly": true, "description": "Whether you may release the IP back to the pool (reserved cloud IPs only)." } }, "required": [ "can_release", "can_update_ptr", "comment", "content", "ip", "service_kind", "service_name", "service_sid", "service_uuid", "status", "vm" ] } } ``` # List project public IPs (/en/docs/api/ip-addresses/list-project-public-ips) `GET https://api.hostd.cloud/v1/cloud/project/{uuid}/public-ips/` Returns public IPv4 and IPv6 addresses reserved on this project, including PTR, comment, and whether the address is attached to a VM or Cloud Gateway. Complements the account-wide `/network/ips/` list. ## Parameters - `uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "A public IPv4 or IPv6 address reserved on this project.", "properties": { "ip": { "type": [ "string", "null" ], "description": "Public IPv4 or IPv6 address." }, "content": { "type": [ "string", "null" ], "description": "Current PTR record (reverse DNS hostname); null when not set.", "maxLength": 64000 }, "comment": { "type": [ "string", "null" ], "description": "Optional comment.", "maxLength": 120 }, "vmid": { "type": [ "integer", "null" ], "readOnly": true, "description": "VMID when the address is attached to a project VM; null when reserved only." }, "status": { "type": "string", "readOnly": true, "description": "`attached` when in use (VM or Cloud Gateway), otherwise `reserved`." }, "attachment": { "type": [ "string", "null" ], "readOnly": true, "description": "`vm` for a regular VM, `router` for Cloud Gateway, null when reserved only." } }, "required": [ "attachment", "status", "vmid" ] } } ``` ### 403 You are not a member of this project. ### 404 Project not found. # Release a project public IP (/en/docs/api/ip-addresses/release-project-public-ip) `DELETE https://api.hostd.cloud/v1/cloud/project/{uuid}/public-ips/{ip}/` Returns a reserved public IP to the pool and stops billing for it. The IP must not be attached to a VM; the PTR record is reset. An API key needs Full access to the project. ## Parameters - `ip` (path, required) `string`: Public IPv4 or IPv6 address. - `uuid` (path, required) `string`: Project UUID. ## Responses ### 204 The public IP was released. ### 400 Invalid IP address, or the IP is still in use. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 Project or public IP not found. # Update a project public IP PTR (/en/docs/api/ip-addresses/update-project-public-ip-ptr) `PATCH https://api.hostd.cloud/v1/cloud/project/{uuid}/public-ips/{ip}/` Sets the reverse DNS (PTR) hostname for a public IP on this project. Send an empty `content` string to restore the default hostname. Optionally update `comment`. ## Parameters - `ip` (path, required) `string`: Public IPv4 or IPv6 address. - `uuid` (path, required) `string`: Project UUID. ## Request `application/json` ```json { "type": "object", "description": "Set the PTR hostname and optional comment for a project public IP.", "properties": { "content": { "type": "string", "description": "PTR hostname. Send an empty string to restore the default hostname.", "maxLength": 255 }, "comment": { "type": "string", "description": "Optional comment. Omit to leave the current comment unchanged.", "maxLength": 120 } } } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "A public IPv4 or IPv6 address reserved on this project.", "properties": { "ip": { "type": [ "string", "null" ], "description": "Public IPv4 or IPv6 address." }, "content": { "type": [ "string", "null" ], "description": "Current PTR record (reverse DNS hostname); null when not set.", "maxLength": 64000 }, "comment": { "type": [ "string", "null" ], "description": "Optional comment.", "maxLength": 120 }, "vmid": { "type": [ "integer", "null" ], "readOnly": true, "description": "VMID when the address is attached to a project VM; null when reserved only." }, "status": { "type": "string", "readOnly": true, "description": "`attached` when in use (VM or Cloud Gateway), otherwise `reserved`." }, "attachment": { "type": [ "string", "null" ], "readOnly": true, "description": "`vm` for a regular VM, `router` for Cloud Gateway, null when reserved only." } }, "required": [ "attachment", "status", "vmid" ] } ``` ### 400 Invalid IP address or PTR hostname. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 Project or public IP not found. # Update PTR record (/en/docs/api/ip-addresses/update-ptr-record) `PATCH https://api.hostd.cloud/v1/network/ips/{ip}/` Sets the reverse DNS (PTR) hostname for the IP address. Send an empty string to restore the default hostname. Requires permission (`can_update_ptr`, see the list endpoint). PTR TTL is always set to 3600 seconds. ## Parameters - `ip` (path, required) `string`: IPv4 or IPv6 address assigned to one of your services (URL-encoded). ## Request `application/json` ```json { "type": "object", "properties": { "content": { "type": "string", "description": "Reverse DNS (PTR) hostname. Send an empty string to restore the default hostname." }, "comment": { "type": "string", "description": "Internal comment shown in the portal." } } } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "IP address with its PTR record.", "properties": { "ip": { "type": [ "string", "null" ], "readOnly": true, "description": "IPv4 address." }, "content": { "type": [ "string", "null" ], "readOnly": true, "description": "Current PTR record (reverse DNS hostname); null when not set." }, "comment": { "type": [ "string", "null" ], "readOnly": true, "description": "Internal comment shown in the portal." }, "can_update_ptr": { "type": "boolean", "readOnly": true, "description": "Whether you may change the PTR record." } }, "required": [ "can_update_ptr", "comment", "content", "ip" ] } ``` ### 403 The IP is not assigned to any of your services, or you do not have permission to edit its PTR record. ### 404 Invalid IP address format. # Add an IP set member (/en/docs/api/ip-sets/add-ip-set-member) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/ipsets/{uuid}/members/` Adds an address or network to the IP set. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `uuid` (path, required) `string`: IP set UUID. ## Request (required) `application/json` ```json { "type": "object", "description": "Add or update an IP set member.", "properties": { "cidr": { "type": "string", "description": "IPv4 address or CIDR up to /24, or IPv6 address or CIDR up to /64. Identifies the member on update." }, "comment": { "type": "string", "description": "Optional comment." }, "nomatch": { "type": "boolean", "description": "If true, exclude this entry from the set instead of including it." } }, "required": [ "cidr" ] } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a firewall write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot manage the network, or write access is blocked (card verification or billing hold). ### 404 IP set not found in this project. ### 500 The cluster could not complete the request. # Create an IP set (/en/docs/api/ip-sets/create-ip-set) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/ipsets/` Creates an empty IP set. Add addresses with the member endpoints, then reference it in rules. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Request (required) `application/json` ```json { "type": "object", "description": "Create an IP set.", "properties": { "display_name": { "type": "string", "description": "IP set name. Latin letters, digits, hyphens and underscores, starting with a letter, at most 15 characters. Stored in lower case; spaces become underscores." }, "comment": { "type": "string", "description": "Free-text comment." } }, "required": [ "display_name" ] } ``` ## Responses ### 201 `application/json` ```json { "type": "object", "description": "A project IP set: a named list of addresses that firewall rules can reference.", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "IP set UUID." }, "display_name": { "type": "string", "readOnly": true, "description": "IP set name." }, "pve_ipset_name": { "type": "string", "readOnly": true, "description": "Identifier that firewall rules use to reference the set, as `+`." }, "comment": { "type": "string", "readOnly": true, "description": "Free-text comment." }, "members": { "type": [ "array", "null" ], "items": { "type": "object", "description": "One address or network in an IP set.", "properties": { "cidr": { "type": "string", "description": "IPv4 or IPv6 address or CIDR." }, "comment": { "type": "string", "description": "Optional comment." }, "nomatch": { "type": "boolean", "description": "If true, the entry is excluded from the set instead of included." } }, "required": [ "cidr", "comment", "nomatch" ] }, "description": "Addresses and networks in the set. `null` when the list is temporarily unavailable." } }, "required": [ "comment", "display_name", "members", "pve_ipset_name", "uuid" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot manage the network, or write access is blocked (card verification or billing hold). ### 500 The cluster could not complete the request. # Delete an IP set member (/en/docs/api/ip-sets/delete-ip-set-member) `DELETE https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/ipsets/{uuid}/members/` Removes the member identified by `cidr` from the IP set. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `uuid` (path, required) `string`: IP set UUID. ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a firewall write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot manage the network, or write access is blocked (card verification or billing hold). ### 404 IP set not found in this project. ### 500 The cluster could not complete the request. # Delete an IP set (/en/docs/api/ip-sets/delete-ip-set) `DELETE https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/ipsets/{uuid}/` Removes every VM and security-group rule that references the set, then deletes it. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `uuid` (path, required) `string`: IP set UUID. ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of deleting an IP set.", "properties": { "message": { "type": "string", "description": "Short status message." }, "cleared_vm_rule_count": { "type": "integer", "description": "VM firewall rules that used the set and were removed." }, "cleared_group_rule_count": { "type": "integer", "description": "Security-group rules that used the set and were removed." } }, "required": [ "cleared_group_rule_count", "cleared_vm_rule_count", "message" ] } ``` ### 403 You are not a member of this project, your role cannot manage the network, or write access is blocked (card verification or billing hold). ### 404 IP set not found in this project. ### 500 The cluster could not complete the request. # List IP set members (/en/docs/api/ip-sets/list-ip-set-members) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/ipsets/{uuid}/members/` Returns the addresses and networks in the IP set. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `uuid` (path, required) `string`: IP set UUID. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "One address or network in an IP set.", "properties": { "cidr": { "type": "string", "description": "IPv4 or IPv6 address or CIDR." }, "comment": { "type": "string", "description": "Optional comment." }, "nomatch": { "type": "boolean", "description": "If true, the entry is excluded from the set instead of included." } }, "required": [ "cidr", "comment", "nomatch" ] } } ``` ### 403 You are not a member of this project. ### 404 IP set not found in this project. ### 500 The cluster could not complete the request. # List IP sets (/en/docs/api/ip-sets/list-ip-sets) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/ipsets/` Returns the IP sets of the project, each with its addresses. `members` is `null` when that list is temporarily unavailable. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "A project IP set: a named list of addresses that firewall rules can reference.", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "IP set UUID." }, "display_name": { "type": "string", "readOnly": true, "description": "IP set name." }, "pve_ipset_name": { "type": "string", "readOnly": true, "description": "Identifier that firewall rules use to reference the set, as `+`." }, "comment": { "type": "string", "readOnly": true, "description": "Free-text comment." }, "members": { "type": [ "array", "null" ], "items": { "type": "object", "description": "One address or network in an IP set.", "properties": { "cidr": { "type": "string", "description": "IPv4 or IPv6 address or CIDR." }, "comment": { "type": "string", "description": "Optional comment." }, "nomatch": { "type": "boolean", "description": "If true, the entry is excluded from the set instead of included." } }, "required": [ "cidr", "comment", "nomatch" ] }, "description": "Addresses and networks in the set. `null` when the list is temporarily unavailable." } }, "required": [ "comment", "display_name", "members", "pve_ipset_name", "uuid" ] } } ``` ### 403 You are not a member of this project. # Update an IP set member (/en/docs/api/ip-sets/update-ip-set-member) `PUT https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/ipsets/{uuid}/members/` Updates the comment or `nomatch` of the member identified by `cidr`. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `uuid` (path, required) `string`: IP set UUID. ## Request (required) `application/json` ```json { "type": "object", "description": "Add or update an IP set member.", "properties": { "cidr": { "type": "string", "description": "IPv4 address or CIDR up to /24, or IPv6 address or CIDR up to /64. Identifies the member on update." }, "comment": { "type": "string", "description": "Optional comment." }, "nomatch": { "type": "boolean", "description": "If true, exclude this entry from the set instead of including it." } }, "required": [ "cidr" ] } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a firewall write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot manage the network, or write access is blocked (card verification or billing hold). ### 404 IP set not found in this project. ### 500 The cluster could not complete the request. # Update an IP set comment (/en/docs/api/ip-sets/update-ip-set) `PATCH https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/ipsets/{uuid}/` Changes the comment of an IP set. The name cannot be changed. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `uuid` (path, required) `string`: IP set UUID. ## Request `application/json` ```json { "type": "object", "description": "Change an IP set comment. The name cannot be changed.", "properties": { "comment": { "type": "string", "description": "Free-text comment." } } } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "A project IP set: a named list of addresses that firewall rules can reference.", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "IP set UUID." }, "display_name": { "type": "string", "readOnly": true, "description": "IP set name." }, "pve_ipset_name": { "type": "string", "readOnly": true, "description": "Identifier that firewall rules use to reference the set, as `+`." }, "comment": { "type": "string", "readOnly": true, "description": "Free-text comment." }, "members": { "type": [ "array", "null" ], "items": { "type": "object", "description": "One address or network in an IP set.", "properties": { "cidr": { "type": "string", "description": "IPv4 or IPv6 address or CIDR." }, "comment": { "type": "string", "description": "Optional comment." }, "nomatch": { "type": "boolean", "description": "If true, the entry is excluded from the set instead of included." } }, "required": [ "cidr", "comment", "nomatch" ] }, "description": "Addresses and networks in the set. `null` when the list is temporarily unavailable." } }, "required": [ "comment", "display_name", "members", "pve_ipset_name", "uuid" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot manage the network, or write access is blocked (card verification or billing hold). ### 404 IP set not found in this project. ### 500 The cluster could not complete the request. # Create private network (/en/docs/api/private-networks/create-private-network) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/sdn/private-network/` Creates an internal VLAN (`tag`) with a /24 subnet, the gateway on `.1` and DHCP. Pick a free `cidr` from Get private network options. Attach a VM to the network with `lan_interfaces` (or `lan_vnets`) when creating or resizing it. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Request (required) `application/json` ```json { "type": "object", "description": "Private network to create.", "properties": { "lan_type": { "allOf": [ { "enum": [ "tag", "cross_dc", "external_vlan" ], "type": "string" } ], "description": "Network type. Only `tag` (internal VLAN) can be created." }, "cidr": { "type": "string", "description": "Free /24 subnet from the private network options, e.g. `10.20.5.0/24`." }, "cloud_gateway": { "type": "boolean", "default": false, "description": "Also create a Cloud Gateway router VM for this network." }, "tier": { "allOf": [ { "enum": [ "standard", "performance" ], "type": "string" } ], "default": "standard", "description": "Cloud Gateway tier. Used only with `cloud_gateway`." }, "wan_ip": { "type": "string", "description": "Public IPv4 for the Cloud Gateway. Omit to assign the next free one. Used only with `cloud_gateway`." } }, "required": [ "cidr", "lan_type" ] } ``` `application/x-www-form-urlencoded` ```json { "type": "object", "description": "Private network to create.", "properties": { "lan_type": { "allOf": [ { "enum": [ "tag", "cross_dc", "external_vlan" ], "type": "string" } ], "description": "Network type. Only `tag` (internal VLAN) can be created." }, "cidr": { "type": "string", "description": "Free /24 subnet from the private network options, e.g. `10.20.5.0/24`." }, "cloud_gateway": { "type": "boolean", "default": false, "description": "Also create a Cloud Gateway router VM for this network." }, "tier": { "allOf": [ { "enum": [ "standard", "performance" ], "type": "string" } ], "default": "standard", "description": "Cloud Gateway tier. Used only with `cloud_gateway`." }, "wan_ip": { "type": "string", "description": "Public IPv4 for the Cloud Gateway. Omit to assign the next free one. Used only with `cloud_gateway`." } }, "required": [ "cidr", "lan_type" ] } ``` `multipart/form-data` ```json { "type": "object", "description": "Private network to create.", "properties": { "lan_type": { "allOf": [ { "enum": [ "tag", "cross_dc", "external_vlan" ], "type": "string" } ], "description": "Network type. Only `tag` (internal VLAN) can be created." }, "cidr": { "type": "string", "description": "Free /24 subnet from the private network options, e.g. `10.20.5.0/24`." }, "cloud_gateway": { "type": "boolean", "default": false, "description": "Also create a Cloud Gateway router VM for this network." }, "tier": { "allOf": [ { "enum": [ "standard", "performance" ], "type": "string" } ], "default": "standard", "description": "Cloud Gateway tier. Used only with `cloud_gateway`." }, "wan_ip": { "type": "string", "description": "Public IPv4 for the Cloud Gateway. Omit to assign the next free one. Used only with `cloud_gateway`." } }, "required": [ "cidr", "lan_type" ] } ``` ## Responses ### 201 `application/json` ```json { "type": "object", "description": "Private network created by the request.", "properties": { "vnet": { "type": "string", "description": "VNet name. Use it as `vnet` in `lan_interfaces`, or in `lan_vnets`, when creating or resizing a VM." }, "subnet": { "type": "string", "description": "IPv4 subnet in CIDR notation." }, "gateway": { "type": "string", "description": "Gateway IPv4 address of the subnet." } }, "required": [ "gateway", "subnet", "vnet" ] } ``` ### 400 Invalid or used `cidr`, or the project's private network limit is reached. ### 403 No write access to this project, or `lan_type` is not `tag`. ### 404 Project not found. # Get private network options (/en/docs/api/private-networks/get-private-network-options) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/sdn/private-network/options/` Returns up to 10 free /24 subnets for new private networks. Pass one as `cidr` to Create private network. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Free subnets for new private networks.", "properties": { "options": { "type": "array", "items": { "type": "object", "description": "Free subnet for a new private network.", "properties": { "cidr": { "type": "string", "description": "Subnet to pass as `cidr` when creating the network." }, "vnet": { "type": "string", "description": "VNet name the network gets." }, "gateway": { "type": "string", "description": "Gateway IPv4 address of the subnet." } }, "required": [ "cidr", "gateway", "vnet" ] } } }, "required": [ "options" ] } ``` ### 403 You are not a member of this project. ### 404 Project not found. # List private network IPs (/en/docs/api/private-networks/list-private-network-ips) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/sdn/private-network/vnet/{vnet}/ips/` Returns every host address in the private network with a `free` flag. Use a free address as `ip` in `lan_interfaces` (mode `select`) when creating or resizing a VM. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vnet` (path, required) `string`: Private network (VNet) name. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "Host address in a private network.", "properties": { "ip": { "type": "string", "description": "IPv4 address." }, "free": { "type": "boolean", "description": "True when no VM or Cloud Gateway uses this address." } }, "required": [ "free", "ip" ] } } ``` ### 400 The private network has no IPv4 subnet. ### 404 Project or private network not found. # List private networks (/en/docs/api/private-networks/list-private-networks) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/sdn/` Returns the private networks of this project. Attach a VM to one with `lan_interfaces` (or `lan_vnets`) when creating or resizing it; List private network IPs shows which addresses are free. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "Private network (VNet) of a project.", "properties": { "vnet": { "type": [ "string", "null" ], "readOnly": true, "description": "VNet name. Use it as `vnet` in `lan_interfaces`, or in `lan_vnets`, when creating or resizing a VM." }, "type": { "type": "string", "readOnly": true, "description": "Network type; `tag` is an internal VLAN." }, "lan_identifier": { "type": "integer", "readOnly": true, "description": "Network interface index on VMs: `1` is `net1`, `2` is `net2`, and so on." }, "cidr": { "type": [ "string", "null" ], "readOnly": true, "description": "IPv4 subnet in CIDR notation." }, "gateway": { "type": [ "string", "null" ], "readOnly": true, "description": "Gateway IPv4 address of the subnet." }, "has_router": { "type": "boolean", "readOnly": true, "description": "Whether a Cloud Gateway is attached to this network." } }, "required": [ "cidr", "gateway", "has_router", "lan_identifier", "type", "vnet" ] } } ``` ### 403 You are not a member of this project. ### 404 Project not found. # Create a project (/en/docs/api/projects/create-project) `POST https://api.hostd.cloud/v1/cloud/project/` Creates a Public Cloud project on the given cluster. You become the project owner (`superadmin`). New accounts must verify a card before creating a project; a prepaid hold or a suspended account also blocks creation. The number of projects you can own on a cluster is limited by your account. The API key must be allowed to create projects; it gets write access to the new project. The response matches the single-project endpoint (role, limits, and pricing). ## Request (required) `application/json` ```json { "type": "object", "description": "Fields required to create a Public Cloud project.", "properties": { "cluster_name": { "type": "string", "description": "Cluster (zone) name, e.g. `waw-1`. Must be an active cluster.", "maxLength": 255 }, "name": { "type": "string", "description": "Project name.", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Optional project description." } }, "required": [ "cluster_name", "name" ] } ``` `application/x-www-form-urlencoded` ```json { "type": "object", "description": "Fields required to create a Public Cloud project.", "properties": { "cluster_name": { "type": "string", "description": "Cluster (zone) name, e.g. `waw-1`. Must be an active cluster.", "maxLength": 255 }, "name": { "type": "string", "description": "Project name.", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Optional project description." } }, "required": [ "cluster_name", "name" ] } ``` `multipart/form-data` ```json { "type": "object", "description": "Fields required to create a Public Cloud project.", "properties": { "cluster_name": { "type": "string", "description": "Cluster (zone) name, e.g. `waw-1`. Must be an active cluster.", "maxLength": 255 }, "name": { "type": "string", "description": "Project name.", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Optional project description." } }, "required": [ "cluster_name", "name" ] } ``` ## Responses ### 201 `application/json` ```json { "type": "object", "description": "Single Public Cloud project: identity and role, plus resource caps and hourly pricing.", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "Project UUID." }, "name": { "type": "string", "description": "Project name.", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Optional project description." }, "cluster": { "type": "string", "readOnly": true, "description": "Cluster (zone) name, e.g. `waw-1`." }, "cluster_location": { "type": [ "string", "null" ], "readOnly": true, "description": "Physical location of the cluster, e.g. Warsaw." }, "role": { "type": [ "string", "null" ], "readOnly": true, "description": "Your role in this project: `superadmin`, `admin`, or `auditor`." }, "limit": { "allOf": [ { "type": "object", "description": "Resource caps that apply to this project (from the billing account / project settings).", "properties": { "max_cores": { "type": "integer", "readOnly": true, "description": "Account vCPU budget. Every CPU class counts 1:1 (shared across projects)." }, "max_sdn_lan_bridges": { "type": "integer", "readOnly": true, "description": "Maximum private networks (LAN) in this project." }, "max_cores_per_vm": { "type": "integer", "readOnly": true, "description": "Maximum raw vCPUs allowed on a single VM." }, "max_backup_jobs": { "type": "integer", "readOnly": true, "description": "Maximum backup jobs in this project." } }, "required": [ "max_backup_jobs", "max_cores", "max_cores_per_vm", "max_sdn_lan_bridges" ] } ], "readOnly": true, "description": "Resource caps that apply when creating or resizing VMs in this project." }, "price_model": { "readOnly": true, "description": "Effective hourly prices in PLN for this project.", "anyOf": [ { "type": "object", "description": "Project-facing hourly prices (same public names as PriceModelPublicSerializer).", "properties": { "vcore_regular": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Regular vCPU price, PLN per vCPU-hour." }, "vcore_light": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Light vCPU price, PLN per vCPU-hour." }, "ram": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "RAM price, GiB/hour" }, "storage_fast": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "readOnly": true, "description": "Fast block storage (NVMe) price, GiB/hour." }, "public_ip": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Public IP price, IP/hour" }, "private_network_tag": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Private network (tag) price, network/hour" }, "private_network_external_vlan": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Private network (external VLAN) price, network/hour" }, "cloud_gateway_standard": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Cloud Gateway (standard tier) price, gateway/hour" } }, "required": [ "public_ip", "ram", "storage_fast" ] }, { "type": "null" } ] } }, "required": [ "cluster", "cluster_location", "limit", "name", "price_model", "role", "uuid" ] } ``` ### 400 Invalid cluster or name, the cluster is not available, or your project limit for this cluster has been reached. ### 403 Card verification is required, the account is on hold (top up the prepaid balance), or the API key is not allowed to create projects. ### 500 The project could not be provisioned. Try again later. # Delete a project (/en/docs/api/projects/delete-project) `DELETE https://api.hostd.cloud/v1/cloud/project/{uuid}/` Removes a Public Cloud project from the portal (soft-delete). Only the project owner (`superadmin`) can delete it; an API key needs Full access to the project. Delete all virtual machines and private networks first; backup jobs are removed automatically. Metered usage history and the project row (including pool ids) are kept for billing. Write access is also blocked when the owner's account is on hold or card verification is still required. ## Parameters - `uuid` (path, required) `string`: Project UUID. ## Responses ### 204 Project deleted. ### 400 The project still has virtual machines or private networks. ### 403 You are not the project owner (`superadmin`), or write access is blocked (card verification or billing hold). ### 404 Project not found or you are not a member. ### 500 The project could not be deleted. Try again later. # Get account usage (/en/docs/api/projects/get-account-usage) `GET https://api.hostd.cloud/v1/cloud/account-usage/` Returns account-wide Public Cloud resource usage and limits for the billing account of the API key owner. `used.cores` is the allocated vCPU sum and counts 1:1 against `limits.max_cores` (all CPU classes). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Account-wide Public Cloud resource usage and limits for the API key owner.", "properties": { "limits": { "type": "object", "properties": { "max_cores": { "type": "integer", "description": "Account vCPU budget. Every CPU class counts 1:1 against this limit." }, "max_cores_per_vm": { "type": "integer", "description": "Maximum raw vCPUs allowed on a single VM." } }, "required": [ "max_cores", "max_cores_per_vm" ] }, "used": { "type": "object", "properties": { "cores": { "type": "integer", "description": "Allocated vCPUs across all VMs on this account. Every CPU class counts 1:1." }, "ram_gb": { "type": "integer", "description": "Sum of RAM in GiB across all VMs on this account." }, "storage_fast_gb": { "type": "integer", "description": "Sum of fast storage (NVMe) in GiB across all VMs on this account." } }, "required": [ "cores", "ram_gb", "storage_fast_gb" ] } }, "required": [ "limits", "used" ] } ``` # Get a project (/en/docs/api/projects/get-project) `GET https://api.hostd.cloud/v1/cloud/project/{uuid}/` Returns a single Public Cloud project by UUID, including your role, resource limits, cluster, and hourly pricing. ## Parameters - `uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Single Public Cloud project: identity and role, plus resource caps and hourly pricing.", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "Project UUID." }, "name": { "type": "string", "description": "Project name.", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Optional project description." }, "cluster": { "type": "string", "readOnly": true, "description": "Cluster (zone) name, e.g. `waw-1`." }, "cluster_location": { "type": [ "string", "null" ], "readOnly": true, "description": "Physical location of the cluster, e.g. Warsaw." }, "role": { "type": [ "string", "null" ], "readOnly": true, "description": "Your role in this project: `superadmin`, `admin`, or `auditor`." }, "limit": { "allOf": [ { "type": "object", "description": "Resource caps that apply to this project (from the billing account / project settings).", "properties": { "max_cores": { "type": "integer", "readOnly": true, "description": "Account vCPU budget. Every CPU class counts 1:1 (shared across projects)." }, "max_sdn_lan_bridges": { "type": "integer", "readOnly": true, "description": "Maximum private networks (LAN) in this project." }, "max_cores_per_vm": { "type": "integer", "readOnly": true, "description": "Maximum raw vCPUs allowed on a single VM." }, "max_backup_jobs": { "type": "integer", "readOnly": true, "description": "Maximum backup jobs in this project." } }, "required": [ "max_backup_jobs", "max_cores", "max_cores_per_vm", "max_sdn_lan_bridges" ] } ], "readOnly": true, "description": "Resource caps that apply when creating or resizing VMs in this project." }, "price_model": { "readOnly": true, "description": "Effective hourly prices in PLN for this project.", "anyOf": [ { "type": "object", "description": "Project-facing hourly prices (same public names as PriceModelPublicSerializer).", "properties": { "vcore_regular": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Regular vCPU price, PLN per vCPU-hour." }, "vcore_light": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Light vCPU price, PLN per vCPU-hour." }, "ram": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "RAM price, GiB/hour" }, "storage_fast": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "readOnly": true, "description": "Fast block storage (NVMe) price, GiB/hour." }, "public_ip": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Public IP price, IP/hour" }, "private_network_tag": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Private network (tag) price, network/hour" }, "private_network_external_vlan": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Private network (external VLAN) price, network/hour" }, "cloud_gateway_standard": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Cloud Gateway (standard tier) price, gateway/hour" } }, "required": [ "public_ip", "ram", "storage_fast" ] }, { "type": "null" } ] } }, "required": [ "cluster", "cluster_location", "limit", "name", "price_model", "role", "uuid" ] } ``` ### 404 Project not found or you are not a member. # List project resource usage (/en/docs/api/projects/list-project-resource-usage) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/resource-usage/` Returns hourly metered Public Cloud usage for the project (newest first), with optional date filters and pagination. An hour appears about 10 minutes after it ends, once its cost is final. Only the project owner (`superadmin`) can access this endpoint. `total_cost_pln` is the sum of OK hours in the filtered range. ## Parameters - `end` (query) `string`: Inclusive end date (`YYYY-MM-DD`). Defaults to `start` when only `start` is set. - `limit` (query) `integer`: Page size (default `100`, max `500`). - `offset` (query) `integer`: Number of hours to skip (default `0`). - `project_uuid` (path, required) `string`: Project UUID. - `start` (query) `string`: Inclusive start date (`YYYY-MM-DD`). Defaults to `end` when only `end` is set. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "Paginated hourly metered usage for a project.", "properties": { "count": { "type": "integer", "description": "Total hours matching the filter (before pagination)." }, "limit": { "type": "integer", "description": "Page size." }, "offset": { "type": "integer", "description": "Number of hours skipped." }, "results": { "type": "array", "items": { "type": "object", "description": "One hour of metered Public Cloud usage for a project.", "properties": { "hour_start": { "type": "string", "format": "date-time", "description": "Start of the metered hour (UTC)." }, "vcore_regular": { "type": "integer", "description": "Running Regular vCPUs during this hour." }, "vcore_light": { "type": "integer", "description": "Running Light vCPUs during this hour." }, "vcore_off": { "type": "integer", "description": "Stopped vCPUs billed at the off rate during this hour." }, "ram_on_gib": { "type": "integer", "description": "Running RAM in GiB during this hour." }, "ram_off_gib": { "type": "integer", "description": "Stopped RAM in GiB during this hour." }, "storage_fast_bytes": { "type": "integer", "description": "Fast block storage (NVMe) size in bytes." }, "private_network_tags_count": { "type": "integer", "description": "Number of internal private networks (VLAN tags)." }, "private_network_external_vlan_count": { "type": "integer", "description": "Number of external VLAN private networks." }, "cloud_gateway_standard_count": { "type": "integer", "description": "Number of standard Cloud Gateways." }, "public_ip_count": { "type": "integer", "description": "Number of public IPv4 addresses." }, "backup_disk_bytes": { "type": "integer", "description": "Backup disk usage in bytes (PBS GC / billed size)." }, "total_cost_pln": { "type": "string", "description": "Net cost for this hour in PLN (6 decimal places)." } }, "required": [ "backup_disk_bytes", "cloud_gateway_standard_count", "hour_start", "private_network_external_vlan_count", "private_network_tags_count", "public_ip_count", "ram_off_gib", "ram_on_gib", "storage_fast_bytes", "total_cost_pln", "vcore_light", "vcore_off", "vcore_regular" ] }, "description": "Hourly usage rows, newest first." }, "total_cost_pln": { "type": "string", "description": "Sum of OK hourly costs for the filtered range (PLN, 6 decimal places)." } }, "required": [ "count", "limit", "offset", "results", "total_cost_pln" ] } } ``` ### 403 You are not the project owner (`superadmin`), or access is denied. ### 404 Project not found. # List project tasks (/en/docs/api/projects/list-project-tasks) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/task/` Returns recent cluster tasks started by members of this project (filtered to the project's Proxmox users). `user` is the member email, or `current` when the task belongs to the authenticated API user. A `status` that matches an internal-detail pattern is returned as `error`. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "A recent Proxmox cluster task initiated by a project member.", "properties": { "upid": { "type": "string", "description": "Proxmox unique task ID (UPID)." }, "type": { "type": "string", "description": "Task type, e.g. `qmstart`, `qmcreate`, `vzdump`." }, "status": { "type": "string", "default": "running", "description": "Task status, e.g. `OK`, `running`, or an error string." }, "user": { "type": [ "string", "null" ], "description": "Member who started the task: their email, or `current` when it is the authenticated API user." }, "starttime": { "type": [ "integer", "null" ], "description": "Unix timestamp when the task started." }, "endtime": { "type": [ "integer", "null" ], "description": "Unix timestamp when the task finished; null while still running." }, "id": { "type": [ "string", "null" ], "description": "Proxmox object id related to the task (often the VMID)." } }, "required": [ "type", "upid" ] } } ``` ### 403 You are not a member of this project. ### 500 No cluster servers available, or Proxmox error. # List projects (/en/docs/api/projects/list-projects) `GET https://api.hostd.cloud/v1/cloud/project/` Returns Public Cloud projects you can access (as an active member), including your role, cluster, and allocated VM resources (count, vCPU, RAM, and fast storage). Resource limits and hourly pricing are available on the single-project endpoint. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "Public Cloud project the authenticated user can access (list payload).", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "Project UUID." }, "name": { "type": "string", "description": "Project name.", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Optional project description." }, "cluster": { "type": "string", "readOnly": true, "description": "Cluster (zone) name, e.g. `waw-1`." }, "cluster_location": { "type": [ "string", "null" ], "readOnly": true, "description": "Physical location of the cluster, e.g. Warsaw." }, "role": { "type": [ "string", "null" ], "readOnly": true, "description": "Your role in this project: `superadmin`, `admin`, or `auditor`." }, "vm_count": { "type": "integer", "readOnly": true, "description": "Number of virtual machines in this project." }, "cores": { "type": "integer", "readOnly": true, "description": "Allocated vCPUs across virtual machines in this project. Every CPU class counts 1:1." }, "ram_mib": { "type": "integer", "readOnly": true, "description": "Allocated RAM across virtual machines in this project, in MiB." }, "storage_fast_gb": { "type": "integer", "readOnly": true, "description": "Allocated fast storage (NVMe) across virtual machines in this project, in GiB." } }, "required": [ "cluster", "cluster_location", "cores", "name", "ram_mib", "role", "storage_fast_gb", "uuid", "vm_count" ] } } ``` # Update a project (/en/docs/api/projects/update-project) `PATCH https://api.hostd.cloud/v1/cloud/project/{uuid}/` Updates the project name and/or description. The cluster cannot be changed. Only the project owner (`superadmin`) can update a project. Write access is also blocked when the owner's account is on hold or card verification is still required. ## Parameters - `uuid` (path, required) `string`: Project UUID. ## Request `application/json` ```json { "type": "object", "description": "Project name and description (the only fields that can be changed).", "properties": { "name": { "type": "string", "description": "Project name.", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Optional project description." } } } ``` `application/x-www-form-urlencoded` ```json { "type": "object", "description": "Project name and description (the only fields that can be changed).", "properties": { "name": { "type": "string", "description": "Project name.", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Optional project description." } } } ``` `multipart/form-data` ```json { "type": "object", "description": "Project name and description (the only fields that can be changed).", "properties": { "name": { "type": "string", "description": "Project name.", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Optional project description." } } } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Single Public Cloud project: identity and role, plus resource caps and hourly pricing.", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "Project UUID." }, "name": { "type": "string", "description": "Project name.", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Optional project description." }, "cluster": { "type": "string", "readOnly": true, "description": "Cluster (zone) name, e.g. `waw-1`." }, "cluster_location": { "type": [ "string", "null" ], "readOnly": true, "description": "Physical location of the cluster, e.g. Warsaw." }, "role": { "type": [ "string", "null" ], "readOnly": true, "description": "Your role in this project: `superadmin`, `admin`, or `auditor`." }, "limit": { "allOf": [ { "type": "object", "description": "Resource caps that apply to this project (from the billing account / project settings).", "properties": { "max_cores": { "type": "integer", "readOnly": true, "description": "Account vCPU budget. Every CPU class counts 1:1 (shared across projects)." }, "max_sdn_lan_bridges": { "type": "integer", "readOnly": true, "description": "Maximum private networks (LAN) in this project." }, "max_cores_per_vm": { "type": "integer", "readOnly": true, "description": "Maximum raw vCPUs allowed on a single VM." }, "max_backup_jobs": { "type": "integer", "readOnly": true, "description": "Maximum backup jobs in this project." } }, "required": [ "max_backup_jobs", "max_cores", "max_cores_per_vm", "max_sdn_lan_bridges" ] } ], "readOnly": true, "description": "Resource caps that apply when creating or resizing VMs in this project." }, "price_model": { "readOnly": true, "description": "Effective hourly prices in PLN for this project.", "anyOf": [ { "type": "object", "description": "Project-facing hourly prices (same public names as PriceModelPublicSerializer).", "properties": { "vcore_regular": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Regular vCPU price, PLN per vCPU-hour." }, "vcore_light": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Light vCPU price, PLN per vCPU-hour." }, "ram": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "RAM price, GiB/hour" }, "storage_fast": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "readOnly": true, "description": "Fast block storage (NVMe) price, GiB/hour." }, "public_ip": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Public IP price, IP/hour" }, "private_network_tag": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Private network (tag) price, network/hour" }, "private_network_external_vlan": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Private network (external VLAN) price, network/hour" }, "cloud_gateway_standard": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,4}(?:\\.\\d{0,6})?$", "description": "Cloud Gateway (standard tier) price, gateway/hour" } }, "required": [ "public_ip", "ram", "storage_fast" ] }, { "type": "null" } ] } }, "required": [ "cluster", "cluster_location", "limit", "name", "price_model", "role", "uuid" ] } ``` ### 400 Invalid name or description. ### 403 You are not the project owner (`superadmin`), or write access is blocked (card verification or billing hold). ### 404 Project not found or you are not a member. # Create a security group rule (/en/docs/api/security-groups/create-security-group-rule) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/groups/{uuid}/rules/` Adds a rule to the group. Omit `position` to append. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `uuid` (path, required) `string`: Security group UUID. ## Request (required) `application/json` ```json { "type": "object", "description": "Create or update a security-group rule.", "properties": { "pos": { "type": "integer", "description": "Rule position to update (required for PUT)." }, "position": { "type": "integer", "description": "Insert at this position (POST). Omit to append." }, "type": { "allOf": [ { "enum": [ "in", "out" ], "type": "string" } ], "description": "Traffic direction." }, "action": { "allOf": [ { "enum": [ "ACCEPT", "DROP" ], "type": "string" } ], "description": "What to do with matching traffic." }, "proto": { "allOf": [ { "enum": [ "tcp", "udp", "icmp" ], "type": "string" } ], "description": "Protocol." }, "source": { "type": "string", "description": "Source IPv4 or IPv6 address, CIDR (IPv4 up to /26, IPv6 up to /64), IPv4 range, or IP set as `+`." }, "dest": { "type": "string", "description": "Destination IPv4 or IPv6 address, CIDR (IPv4 up to /26, IPv6 up to /64), IPv4 range, or IP set as `+`." }, "sport": { "type": "string", "description": "Source port, range (`80:85`) or comma-separated list. TCP and UDP only." }, "dport": { "type": "string", "description": "Destination port, range (`80:85`) or comma-separated list. TCP and UDP only." }, "comment": { "type": "string", "description": "Optional comment." }, "enable": { "type": "boolean", "description": "Whether the rule is enabled. Defaults to true." } }, "required": [ "action", "proto", "type" ] } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a firewall write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot manage the network, or write access is blocked (card verification or billing hold). ### 404 Security group not found in this project. ### 500 The cluster could not complete the request. # Create a security group (/en/docs/api/security-groups/create-security-group) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/groups/` Creates an empty security group. Add rules with the rule endpoints, then attach it to VMs. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Request (required) `application/json` ```json { "type": "object", "description": "Create a security group.", "properties": { "display_name": { "type": "string", "description": "Group name. Latin letters, digits, hyphens and underscores, starting with a letter, at most 15 characters. Stored in lower case; spaces become underscores." }, "comment": { "type": "string", "description": "Free-text comment." } }, "required": [ "display_name" ] } ``` ## Responses ### 201 `application/json` ```json { "type": "object", "description": "A project security group: a named list of firewall rules that can be attached to VMs.", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "Security group UUID." }, "display_name": { "type": "string", "readOnly": true, "description": "Group name." }, "pve_group_name": { "type": "string", "readOnly": true, "description": "Identifier that VM firewall rules use as `action` when `type` is `group`." }, "comment": { "type": "string", "readOnly": true, "description": "Free-text comment." } }, "required": [ "comment", "display_name", "pve_group_name", "uuid" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot manage the network, or write access is blocked (card verification or billing hold). ### 500 The cluster could not complete the request. # Delete a security group rule (/en/docs/api/security-groups/delete-security-group-rule) `DELETE https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/groups/{uuid}/rules/` Deletes the rule at `pos`. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `uuid` (path, required) `string`: Security group UUID. ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a firewall write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot manage the network, or write access is blocked (card verification or billing hold). ### 404 Security group or rule not found in this project. ### 500 The cluster could not complete the request. # Delete a security group (/en/docs/api/security-groups/delete-security-group) `DELETE https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/groups/{uuid}/` Removes all rules from the group, detaches it from every VM in the project, then deletes it. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `uuid` (path, required) `string`: Security group UUID. ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of deleting a security group.", "properties": { "message": { "type": "string", "description": "Short status message." }, "cleared_rule_count": { "type": "integer", "description": "Rules that were removed from the group." }, "detached_vm_count": { "type": "integer", "description": "VMs the group was detached from." } }, "required": [ "cleared_rule_count", "detached_vm_count", "message" ] } ``` ### 403 You are not a member of this project, your role cannot manage the network, or write access is blocked (card verification or billing hold). ### 404 Security group not found in this project. ### 500 The cluster could not complete the request. # List security group rules (/en/docs/api/security-groups/list-security-group-rules) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/groups/{uuid}/rules/` Returns the rules of the group in evaluation order. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `uuid` (path, required) `string`: Security group UUID. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "One packet-filter rule of a security group.", "properties": { "pos": { "type": "integer", "description": "Rule position (0-based)." }, "type": { "type": "string", "description": "`in` or `out`." }, "action": { "type": "string", "description": "`ACCEPT` or `DROP`." }, "proto": { "type": "string", "description": "`tcp`, `udp`, or `icmp`." }, "source": { "type": [ "string", "null" ], "description": "Source address, CIDR, or IP set as `+`." }, "dest": { "type": [ "string", "null" ], "description": "Destination address, CIDR, or IP set as `+`." }, "sport": { "type": [ "string", "null" ], "description": "Source port or range." }, "dport": { "type": [ "string", "null" ], "description": "Destination port or range." }, "comment": { "type": [ "string", "null" ], "description": "Optional comment." }, "enable": { "type": [ "boolean", "null" ], "description": "Whether the rule is enabled." } }, "required": [ "action", "pos", "proto", "type" ] } } ``` ### 403 You are not a member of this project. ### 404 Security group not found in this project. ### 500 The cluster could not complete the request. # List security groups (/en/docs/api/security-groups/list-security-groups) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/groups/` Returns the security groups of the project. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "A project security group: a named list of firewall rules that can be attached to VMs.", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "Security group UUID." }, "display_name": { "type": "string", "readOnly": true, "description": "Group name." }, "pve_group_name": { "type": "string", "readOnly": true, "description": "Identifier that VM firewall rules use as `action` when `type` is `group`." }, "comment": { "type": "string", "readOnly": true, "description": "Free-text comment." } }, "required": [ "comment", "display_name", "pve_group_name", "uuid" ] } } ``` ### 403 You are not a member of this project. # Reorder a security group rule (/en/docs/api/security-groups/move-security-group-rule) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/groups/{uuid}/rules/move/` Moves the rule at `from_pos` to `to_pos`. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `uuid` (path, required) `string`: Security group UUID. ## Request (required) `application/json` ```json { "type": "object", "description": "Reorder a security-group rule.", "properties": { "from_pos": { "type": "integer", "description": "Current rule position." }, "to_pos": { "type": "integer", "description": "New rule position." } }, "required": [ "from_pos", "to_pos" ] } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a firewall write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot manage the network, or write access is blocked (card verification or billing hold). ### 404 Security group or rule not found in this project. ### 500 The cluster could not complete the request. # Replace all security group rules (/en/docs/api/security-groups/replace-security-group-rules) `PUT https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/groups/{uuid}/rules/replace/` Sets the full ordered list of rules of the group. Every rule is validated first; nothing changes if one is invalid. Unchanged positions are kept, and a changed rule is replaced without leaving a gap. Returns the resulting rules. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `uuid` (path, required) `string`: Security group UUID. ## Request (required) `application/json` ```json { "type": "object", "description": "The full security group rule list.", "properties": { "rules": { "type": "array", "items": { "type": "object", "description": "One rule in the full security group rule list.", "properties": { "type": { "allOf": [ { "enum": [ "in", "out" ], "type": "string" } ], "description": "Traffic direction." }, "action": { "allOf": [ { "enum": [ "ACCEPT", "DROP" ], "type": "string" } ], "description": "What to do with matching traffic." }, "proto": { "allOf": [ { "enum": [ "tcp", "udp", "icmp" ], "type": "string" } ], "description": "Protocol." }, "source": { "type": "string", "description": "Source IPv4 or IPv6 address, CIDR (IPv4 up to /26, IPv6 up to /64), IPv4 range, or IP set as `+`." }, "dest": { "type": "string", "description": "Destination IPv4 or IPv6 address, CIDR (IPv4 up to /26, IPv6 up to /64), IPv4 range, or IP set as `+`." }, "sport": { "type": "string", "description": "Source port, range (`80:85`) or comma-separated list. TCP and UDP only." }, "dport": { "type": "string", "description": "Destination port, range (`80:85`) or comma-separated list. TCP and UDP only." }, "comment": { "type": "string", "description": "Optional comment." }, "enable": { "type": "boolean", "description": "Whether the rule is enabled. Defaults to true." } }, "required": [ "action", "proto", "type" ] }, "description": "All rules of the group in evaluation order. An empty list removes every rule." } }, "required": [ "rules" ] } ``` ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "One packet-filter rule of a security group.", "properties": { "pos": { "type": "integer", "description": "Rule position (0-based)." }, "type": { "type": "string", "description": "`in` or `out`." }, "action": { "type": "string", "description": "`ACCEPT` or `DROP`." }, "proto": { "type": "string", "description": "`tcp`, `udp`, or `icmp`." }, "source": { "type": [ "string", "null" ], "description": "Source address, CIDR, or IP set as `+`." }, "dest": { "type": [ "string", "null" ], "description": "Destination address, CIDR, or IP set as `+`." }, "sport": { "type": [ "string", "null" ], "description": "Source port or range." }, "dport": { "type": [ "string", "null" ], "description": "Destination port or range." }, "comment": { "type": [ "string", "null" ], "description": "Optional comment." }, "enable": { "type": [ "boolean", "null" ], "description": "Whether the rule is enabled." } }, "required": [ "action", "pos", "proto", "type" ] } } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot manage the network, or write access is blocked (card verification or billing hold). ### 404 Security group not found in this project. ### 500 The cluster could not complete the request. # Update a security group rule (/en/docs/api/security-groups/update-security-group-rule) `PUT https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/groups/{uuid}/rules/` Updates the rule at `pos`. Send an empty string to clear `source`, `dest`, `sport`, `dport` or `comment`. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `uuid` (path, required) `string`: Security group UUID. ## Request (required) `application/json` ```json { "type": "object", "description": "Create or update a security-group rule.", "properties": { "pos": { "type": "integer", "description": "Rule position to update (required for PUT)." }, "position": { "type": "integer", "description": "Insert at this position (POST). Omit to append." }, "type": { "allOf": [ { "enum": [ "in", "out" ], "type": "string" } ], "description": "Traffic direction." }, "action": { "allOf": [ { "enum": [ "ACCEPT", "DROP" ], "type": "string" } ], "description": "What to do with matching traffic." }, "proto": { "allOf": [ { "enum": [ "tcp", "udp", "icmp" ], "type": "string" } ], "description": "Protocol." }, "source": { "type": "string", "description": "Source IPv4 or IPv6 address, CIDR (IPv4 up to /26, IPv6 up to /64), IPv4 range, or IP set as `+`." }, "dest": { "type": "string", "description": "Destination IPv4 or IPv6 address, CIDR (IPv4 up to /26, IPv6 up to /64), IPv4 range, or IP set as `+`." }, "sport": { "type": "string", "description": "Source port, range (`80:85`) or comma-separated list. TCP and UDP only." }, "dport": { "type": "string", "description": "Destination port, range (`80:85`) or comma-separated list. TCP and UDP only." }, "comment": { "type": "string", "description": "Optional comment." }, "enable": { "type": "boolean", "description": "Whether the rule is enabled. Defaults to true." } }, "required": [ "action", "proto", "type" ] } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a firewall write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot manage the network, or write access is blocked (card verification or billing hold). ### 404 Security group or rule not found in this project. ### 500 The cluster could not complete the request. # Update a security group (/en/docs/api/security-groups/update-security-group) `PATCH https://api.hostd.cloud/v1/cloud/project/{project_uuid}/firewall/groups/{uuid}/` Renames the group or changes its comment. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `uuid` (path, required) `string`: Security group UUID. ## Request `application/json` ```json { "type": "object", "description": "Rename a security group or change its comment. Send at least one field.", "properties": { "display_name": { "type": "string", "description": "New name. Latin letters, digits, hyphens and underscores, starting with a letter, at most 15 characters. Stored in lower case; spaces become underscores. Renaming changes `pve_group_name`, and VM rules that use the group follow automatically." }, "comment": { "type": "string", "description": "Free-text comment." } } } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "A project security group: a named list of firewall rules that can be attached to VMs.", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true, "description": "Security group UUID." }, "display_name": { "type": "string", "readOnly": true, "description": "Group name." }, "pve_group_name": { "type": "string", "readOnly": true, "description": "Identifier that VM firewall rules use as `action` when `type` is `group`." }, "comment": { "type": "string", "readOnly": true, "description": "Free-text comment." } }, "required": [ "comment", "display_name", "pve_group_name", "uuid" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot manage the network, or write access is blocked (card verification or billing hold). ### 404 Security group not found in this project. ### 500 The cluster could not complete the request. # Create a VM snapshot (/en/docs/api/snapshots/create-vm-snapshot) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/snapshots/` Creates a snapshot. Only one snapshot is allowed; returns 400 if one already exists. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Request `application/json` ```json { "type": "object", "description": "Create the one allowed snapshot on this VM.", "properties": { "description": { "type": "string", "description": "Optional snapshot description (max 200 characters in the portal)." } } } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of a VM power action.", "properties": { "task_id": { "type": [ "string", "null" ], "description": "Cluster task ID, or null when HA applies the state change immediately." }, "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Delete a VM snapshot (/en/docs/api/snapshots/delete-vm-snapshot) `DELETE https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/snapshots/{snapname}/` Deletes the named snapshot. The Proxmox `current` entry cannot be deleted. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `snapname` (path, required) `string`: Snapshot name (`name` from the snapshot list). - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of a VM power action.", "properties": { "task_id": { "type": [ "string", "null" ], "description": "Cluster task ID, or null when HA applies the state change immediately." }, "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # List VM snapshots (/en/docs/api/snapshots/list-vm-snapshots) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/snapshots/` Returns snapshots for this VM. The Proxmox `current` entry is omitted. A VM may have at most one snapshot. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "A VM snapshot (the Proxmox `current` entry is omitted).", "properties": { "name": { "type": "string", "description": "Snapshot name." }, "snaptime": { "type": "integer", "description": "Unix timestamp when the snapshot was taken." }, "description": { "type": [ "string", "null" ], "description": "Optional snapshot description." } }, "required": [ "name", "snaptime" ] } } ``` ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Roll back a VM snapshot (/en/docs/api/snapshots/rollback-vm-snapshot) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/snapshots/{snapname}/rollback/` Restores the VM to the named snapshot. The VM must be stopped. `start_after` is not allowed for high-availability VMs. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `snapname` (path, required) `string`: Snapshot name (`name` from the snapshot list). - `vmid` (path, required) `integer`: VM identifier (VMID). ## Request `application/json` ```json { "type": "object", "description": "Rollback options. The VM must be stopped.", "properties": { "start_after": { "type": "boolean", "default": false, "description": "If true, start the VM after rollback completes. Not allowed for high-availability VMs." } } } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of a VM power action.", "properties": { "task_id": { "type": [ "string", "null" ], "description": "Cluster task ID, or null when HA applies the state change immediately." }, "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 409 The action is not allowed in the current VM or HA state. ### 500 The cluster could not complete the request. # Add an SSH key (/en/docs/api/ssh-keys/create-ssh-key) `POST https://api.hostd.cloud/v1/user/ssh-keys/` Adds an SSH public key to your account. ## Request (required) `application/json` ```json { "type": "object", "description": "SSH public key on your account.", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "description": "Key name.", "maxLength": 120 }, "public_ssh_key": { "type": "string", "description": "OpenSSH public key, e.g. `ssh-ed25519 AAAA… user@host`." } }, "required": [ "id", "name", "public_ssh_key" ] } ``` `application/x-www-form-urlencoded` ```json { "type": "object", "description": "SSH public key on your account.", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "description": "Key name.", "maxLength": 120 }, "public_ssh_key": { "type": "string", "description": "OpenSSH public key, e.g. `ssh-ed25519 AAAA… user@host`." } }, "required": [ "id", "name", "public_ssh_key" ] } ``` `multipart/form-data` ```json { "type": "object", "description": "SSH public key on your account.", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "description": "Key name.", "maxLength": 120 }, "public_ssh_key": { "type": "string", "description": "OpenSSH public key, e.g. `ssh-ed25519 AAAA… user@host`." } }, "required": [ "id", "name", "public_ssh_key" ] } ``` ## Responses ### 201 `application/json` ```json { "type": "object", "description": "SSH public key on your account.", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "description": "Key name.", "maxLength": 120 }, "public_ssh_key": { "type": "string", "description": "OpenSSH public key, e.g. `ssh-ed25519 AAAA… user@host`." } }, "required": [ "id", "name", "public_ssh_key" ] } ``` ### 400 Invalid name or SSH public key. # Delete an SSH key (/en/docs/api/ssh-keys/delete-ssh-key) `DELETE https://api.hostd.cloud/v1/user/ssh-keys/{id}/` Removes an SSH public key from your account. Existing VMs are not changed. ## Parameters - `id` (path, required) `integer`: A unique integer value identifying this user ssh key. ## Responses ### 204 SSH key deleted. ### 404 SSH key not found. # List SSH keys (/en/docs/api/ssh-keys/list-ssh-keys) `GET https://api.hostd.cloud/v1/user/ssh-keys/` Returns SSH public keys on your account. Use `id` in `ssh_key_ids` when creating a VM. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "SSH public key on your account.", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "description": "Key name.", "maxLength": 120 }, "public_ssh_key": { "type": "string", "description": "OpenSSH public key, e.g. `ssh-ed25519 AAAA… user@host`." } }, "required": [ "id", "name", "public_ssh_key" ] } } ``` # Create a VM (/en/docs/api/virtual-machines/create-vm) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/` Creates a virtual machine in the project, then starts it. The request waits until creation finishes. Requires a project role that can write VMs. Card verification, a prepaid hold, or a suspended account blocks creation. CPU, RAM, and disk must follow the account grid and quotas. At least one network is required (public WAN and/or a private network). `os_image` is an image `name` from List OS images. SSH keys must belong to the API key owner (Settings → SSH Keys), at most five. The response is the assigned VMID. You can lower CPU, RAM, or CPU class 24 hours after create. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Request (required) `application/json` ```json { "type": "object", "description": "Fields required to create a virtual machine.", "properties": { "hostname": { "type": "string", "description": "DNS-style hostname (letters, digits, hyphens, and dots; no underscores; at most 64 characters).", "maxLength": 255 }, "username": { "type": [ "string", "null" ], "description": "Cloud-init username. Omit to use the default for the OS image.", "maxLength": 128 }, "password": { "type": "string", "description": "Cloud-init password.", "maxLength": 255 }, "ssh_key_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "IDs of SSH keys on your account (Settings → SSH Keys). At most five, no duplicates." }, "cores": { "type": "integer", "minimum": 2, "description": "vCPU count (even numbers from 2). Limited by the account per-VM and account CPU quotas." }, "ram_gb": { "type": "integer", "minimum": 1, "description": "RAM in GiB, between 1 and 4 GiB per vCPU: 2 GiB steps up to 48 GiB, odd sizes from 49 to 113 GiB, then 117, 121 … GiB. Must fit the project RAM quota." }, "os_disk_gb": { "type": "integer", "minimum": 10, "description": "OS disk size in GiB. Must fit the vCPU count (20 GiB steps) and the project disk quota." }, "os_image": { "type": "string", "description": "Image `name` from List OS images (for example `debian-12.qcow2`).", "maxLength": 255 }, "cpu_mode": { "allOf": [ { "enum": [ "light", "regular" ], "type": "string" } ], "default": "regular", "description": "CPU class: `light` or `regular` (default)." }, "wan_mode": { "allOf": [ { "enum": [ "off", "ipv4", "ipv6", "dual" ], "type": "string" } ], "default": "off", "description": "Public WAN: `off`, `ipv4`, `ipv6`, or `dual`. When `off`, attach at least one private network." }, "wan_ip": { "type": [ "string", "null" ], "description": "Reserved project IPv4 to attach. Omit to pick the next free address.", "maxLength": 45 }, "wan_ipv6": { "type": [ "string", "null" ], "description": "Reserved project IPv6 to attach. Omit to pick the next free address.", "maxLength": 45 }, "lan_vnets": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "description": "Shorthand for `lan_interfaces` with `mode` `auto`. Ignored when `lan_interfaces` is set." }, "lan_interfaces": { "type": "array", "items": { "type": "object", "properties": { "vnet": { "type": "string", "description": "Private network (VNet) name.", "maxLength": 255 }, "mode": { "allOf": [ { "enum": [ "auto", "select" ], "type": "string" } ], "description": "`auto` picks a free IP; `select` uses `ip`." }, "ip": { "type": [ "string", "null" ], "description": "IPv4 address when `mode` is `select`.", "maxLength": 45 }, "interface_name": { "type": [ "string", "null" ], "description": "Ignored. The API assigns `netN` from the private network.", "maxLength": 40 }, "is_gateway": { "type": "boolean", "default": false, "description": "When WAN is off and several LANs are attached, exactly one must be the gateway." } }, "required": [ "mode", "vnet" ] } } }, "required": [ "cores", "hostname", "os_disk_gb", "os_image", "password", "ram_gb" ] } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Created virtual machine.", "properties": { "vmid": { "type": "integer", "description": "Assigned VM identifier (VMID)." } }, "required": [ "vmid" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 500 The cluster could not complete the request. # Delete a VM (/en/docs/api/virtual-machines/delete-vm) `DELETE https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/` Destroys a virtual machine and its disks. The VM must be stopped. Requires a project role that can write VMs; an API key needs Full access to the project. Card verification, a prepaid hold, or a suspended account blocks deletion. High availability is removed automatically. Private-network addresses are released. All backups of the VM are deleted with it. By default, public IPs are released to the pool. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `release_public_ip` (query) `boolean`: If true (default), release attached public IPs back to the pool. If false, keep them reserved on the project. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 204 VM deleted. ### 400 The VM is not stopped. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Disable rescue mode (/en/docs/api/virtual-machines/disable-vm-rescue) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/rescue/disable/` Restores the previous boot order, removes the temporary rescue disk, and starts the VM from the system disk. The VM must be stopped. The system disk is left as it is. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of enabling or disabling rescue mode.", "properties": { "message": { "type": "string", "description": "Short status message." }, "task_id": { "type": "string", "description": "Cluster task ID of the rescue disk import. Present when rescue mode is enabled." }, "start_task_id": { "type": "string", "description": "Cluster task ID of the VM start." } }, "required": [ "message" ] } ``` ### 400 The VM is not stopped, or rescue mode is not enabled. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Enable rescue mode (/en/docs/api/virtual-machines/enable-vm-rescue) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/rescue/` Boots a stopped Linux VM from a temporary disk imported from the same OS image. The system disk stays attached. SSH keeps the existing keys. An optional password is for the console of the temporary system; the system disk keeps its own password. The request waits until the import finishes, then starts the VM. High availability must be off. Resize, reinstall, and snapshots stay unavailable until rescue mode is disabled. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Request `application/json` ```json { "type": "object", "description": "Optional console password for the temporary rescue system.", "properties": { "password": { "type": "string", "description": "Console password for the rescue system. Omit to keep the current password. SSH keeps the existing keys. The system disk keeps its own password.", "maxLength": 255 } } } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of enabling or disabling rescue mode.", "properties": { "message": { "type": "string", "description": "Short status message." }, "task_id": { "type": "string", "description": "Cluster task ID of the rescue disk import. Present when rescue mode is enabled." }, "start_task_id": { "type": "string", "description": "Cluster task ID of the VM start." } }, "required": [ "message" ] } ``` ### 400 The VM is not stopped, is not Linux, still has high availability on, already has rescue mode on, or its OS image is no longer available. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Get VM config (/en/docs/api/virtual-machines/get-vm-config) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/config/current/` Returns the current VM configuration: vCPU, RAM, OS disk size, public WAN addresses, private network interfaces, notes, and the cloud-init user. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Current VM configuration: size, networks, notes, and the cloud-init user.", "properties": { "name": { "type": "string", "description": "VM hostname." }, "description": { "type": "string", "description": "VM notes." }, "cores": { "type": "integer", "description": "vCPU count." }, "ram_gb": { "type": "integer", "description": "RAM in GiB." }, "os_disk_gb": { "type": [ "integer", "null" ], "description": "OS disk size in GiB." }, "wan": { "description": "Public WAN addresses; null when WAN is off.", "anyOf": [ { "type": "object", "properties": { "ipv4": { "type": [ "string", "null" ], "description": "Public IPv4 address, or null." }, "ipv6": { "type": [ "string", "null" ], "description": "Public IPv6 address, or null." } }, "required": [ "ipv4", "ipv6" ] }, { "type": "null" } ] }, "lan_interfaces": { "type": "array", "items": { "type": "object", "properties": { "interface_name": { "type": "string", "description": "Guest NIC name, e.g. `net1`." }, "vnet": { "type": "string", "description": "Private network (VNet) name." }, "ip": { "type": [ "string", "null" ], "description": "Private IPv4 address, or null." }, "is_gateway": { "type": "boolean", "description": "True when the default gateway is on this interface." } }, "required": [ "interface_name", "ip", "is_gateway", "vnet" ] }, "description": "Private network interfaces." }, "ciuser": { "type": "string", "description": "Cloud-init user to sign in as." } }, "required": [ "ciuser", "cores", "description", "lan_interfaces", "name", "os_disk_gb", "ram_gb", "wan" ] } ``` ### 403 You are not a member of this project. ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Get VM metrics (/en/docs/api/virtual-machines/get-vm-metrics) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/rrd/` Returns CPU, RAM, network, and disk load history for the period. Each sample is the peak of its interval; lists are empty while the VM has no data. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `timeframe` (query) `string, day | hour | month | week | year`: Period. Defaults to `hour`. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "VM load history. Each sample is the peak of its interval.", "properties": { "cpu_history": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix time (seconds)." }, "value": { "type": "number", "format": "double", "description": "CPU usage in % of the allocated vCPUs." } }, "required": [ "timestamp", "value" ] } }, "mem_history": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix time (seconds)." }, "used": { "type": "integer", "description": "Guest RAM in use, bytes." }, "total": { "type": "integer", "description": "Allocated RAM, bytes." }, "percentage": { "type": "number", "format": "double", "description": "RAM in use, % of allocated." } }, "required": [ "percentage", "timestamp", "total", "used" ] } }, "network_history": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix time (seconds)." }, "in": { "type": "integer", "description": "Inbound traffic, bytes/s." }, "out": { "type": "integer", "description": "Outbound traffic, bytes/s." } }, "required": [ "in", "out", "timestamp" ] } }, "disk_history": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix time (seconds)." }, "read": { "type": "integer", "description": "Disk reads, bytes/s." }, "write": { "type": "integer", "description": "Disk writes, bytes/s." } }, "required": [ "read", "timestamp", "write" ] } } }, "required": [ "cpu_history", "disk_history", "mem_history", "network_history" ] } ``` ### 400 Invalid timeframe. ### 403 You are not a member of this project. ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Get a VM (/en/docs/api/virtual-machines/get-vm) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/` Returns live status for one VM, including whether it is under high availability, whether outbound SMTP (port 25) is allowed, and whether rescue mode is on. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Single VM: live status, HA, and outbound SMTP allowlist.", "properties": { "ha": { "readOnly": true, "description": "High-availability status, when present.", "anyOf": [ { "type": "object", "properties": { "managed": { "type": "boolean", "description": "True when the VM is under high availability." } } }, { "type": "null" } ] }, "status": { "type": "string", "readOnly": true, "description": "Power status, e.g. `running`, `stopped`, `paused`." }, "vmid": { "type": "integer", "readOnly": true, "description": "VM identifier (VMID)." }, "name": { "type": "string", "readOnly": true, "description": "VM hostname." }, "cpu_mode": { "allOf": [ { "enum": [ "light", "regular" ], "type": "string" } ], "readOnly": true, "description": "CPU class: `light` or `regular` (default)." }, "outbound_smtp_allowed": { "type": "boolean", "readOnly": true, "description": "True when outbound SMTP on port 25 is allowed for every public IP of this VM (set by hostd on request; independent of the VM firewall). Ports 465 and 587 are always open." }, "rescue": { "type": "boolean", "readOnly": true, "description": "True when the VM boots a temporary rescue disk." } }, "required": [ "cpu_mode", "ha", "name", "outbound_smtp_allowed", "rescue", "status", "vmid" ] } ``` ### 403 You are not a member of this project. ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # List OS images (/en/docs/api/virtual-machines/list-os-images) `GET https://api.hostd.cloud/v1/cloud/project/{uuid}/cluster/available-images/` Returns OS images you can use for new VMs in this project (`os_image` in create VM) and for reinstall. ## Parameters - `uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "OS image available for new VMs and reinstall in this project.", "properties": { "name": { "type": "string", "description": "Image filename, e.g. `debian-12.qcow2`. Pass it as `os_image` when creating a VM." } }, "required": [ "name" ] } } ``` ### 404 Project not found or you are not a member. ### 503 No cluster servers available. # List VMs (/en/docs/api/virtual-machines/list-vms) `GET https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/` Returns virtual machines in the project (status and resource totals). Requires project membership. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. ## Responses ### 200 `application/json` ```json { "type": "array", "items": { "type": "object", "description": "Virtual machine in a project list (status and resource totals).", "properties": { "vmid": { "type": "integer", "readOnly": true, "description": "VM identifier (VMID)." }, "name": { "type": "string", "readOnly": true, "description": "VM hostname." }, "status": { "type": "string", "readOnly": true, "description": "Power status, e.g. `running`, `stopped`, `paused`." }, "cores": { "type": "integer", "readOnly": true, "description": "vCPU count." }, "ram_gb": { "type": "integer", "readOnly": true, "description": "RAM in GiB." }, "os_disk_gb": { "type": "integer", "readOnly": true, "description": "OS disk size in GiB." }, "cpu_usage": { "type": "number", "format": "double", "readOnly": true, "description": "Current CPU usage as a fraction of 1 (not a percentage)." }, "ram_used_mib": { "type": "integer", "readOnly": true, "description": "Current RAM usage in MiB." }, "cpu_mode": { "type": "string", "readOnly": true, "description": "CPU class: `light` or `regular` (default)." } }, "required": [ "cores", "cpu_mode", "cpu_usage", "name", "os_disk_gb", "ram_gb", "ram_used_mib", "status", "vmid" ] } } ``` ### 403 You are not a member of this project. ### 500 The cluster could not complete the request. # Reboot VM (/en/docs/api/virtual-machines/reboot-vm) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/power/reboot/` Requests an ACPI reboot. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of a VM power action.", "properties": { "task_id": { "type": [ "string", "null" ], "description": "Cluster task ID, or null when HA applies the state change immediately." }, "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Reinstall a VM (/en/docs/api/virtual-machines/reinstall-vm) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/reinstall/` Replaces the OS disk with a fresh copy of the chosen image and resets the hostname, cloud-init user, password and SSH keys. All data on the OS disk is lost; the VM must be stopped first. The disk keeps its previous size, and IP addresses stay the same. The request waits until the reinstall finishes. The new image must have the same firmware type (BIOS or UEFI) as the current one. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Request (required) `application/json` ```json { "type": "object", "description": "Fields to reinstall the operating system of a virtual machine.", "properties": { "hostname": { "type": "string", "description": "DNS-style hostname (letters, digits, hyphens, and dots; no underscores; at most 64 characters).", "maxLength": 255 }, "username": { "type": [ "string", "null" ], "description": "Cloud-init username. Omit to use the default for the OS image.", "maxLength": 128 }, "password": { "type": "string", "description": "Cloud-init password.", "maxLength": 255 }, "ssh_key_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "IDs of SSH keys on your account (Settings → SSH Keys). At most five, no duplicates." }, "os_image": { "type": "string", "description": "Image `name` from List OS images (for example `debian-12.qcow2`). Must have the same firmware type (BIOS or UEFI) as the current image.", "maxLength": 255 }, "start_vm_after": { "type": "boolean", "default": false, "description": "Start the VM once the reinstall finishes." } }, "required": [ "hostname", "os_image", "password" ] } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of a VM reinstall.", "properties": { "message": { "type": "string", "description": "Short status message." }, "task_id": { "type": "string", "description": "Cluster task ID of the OS disk import." }, "start_task_id": { "type": "string", "description": "Cluster task ID of the VM start. Present only when `start_vm_after` was true." } }, "required": [ "message", "task_id" ] } ``` ### 400 The request is invalid, the VM is not stopped, or the image is not compatible with this VM. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Reset VM (/en/docs/api/virtual-machines/reset-vm) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/power/reset/` Hard-resets the VM (equivalent to a power-cycle of the guest). ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of a VM power action.", "properties": { "task_id": { "type": [ "string", "null" ], "description": "Cluster task ID, or null when HA applies the state change immediately." }, "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Resume VM (/en/docs/api/virtual-machines/resume-vm) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/power/resume/` Resumes a suspended VM. High-availability VMs are resumed through HA (`task_id` may be null). ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of a VM power action.", "properties": { "task_id": { "type": [ "string", "null" ], "description": "Cluster task ID, or null when HA applies the state change immediately." }, "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Shut down VM (/en/docs/api/virtual-machines/shutdown-vm) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/power/shutdown/` Requests an ACPI shutdown. High-availability VMs are stopped through HA (`task_id` may be null). ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of a VM power action.", "properties": { "task_id": { "type": [ "string", "null" ], "description": "Cluster task ID, or null when HA applies the state change immediately." }, "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Start VM (/en/docs/api/virtual-machines/start-vm) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/power/start/` Starts the VM. High-availability VMs are started through HA (`task_id` may be null). ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of a VM power action.", "properties": { "task_id": { "type": [ "string", "null" ], "description": "Cluster task ID, or null when HA applies the state change immediately." }, "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Stop VM (/en/docs/api/virtual-machines/stop-vm) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/power/stop/` Hard-stops the VM. High-availability VMs are stopped through HA (`task_id` may be null). ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of a VM power action.", "properties": { "task_id": { "type": [ "string", "null" ], "description": "Cluster task ID, or null when HA applies the state change immediately." }, "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Suspend VM (/en/docs/api/virtual-machines/suspend-vm) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/power/suspend/` Pauses the VM. Not supported for high-availability VMs (stop the VM instead). ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Result of a VM power action.", "properties": { "task_id": { "type": [ "string", "null" ], "description": "Cluster task ID, or null when HA applies the state change immediately." }, "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 409 The VM is under high availability; suspend is not supported. ### 500 The cluster could not complete the request. # Update VM notes (/en/docs/api/virtual-machines/update-vm-notes) `PUT https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/notes/` Sets VM notes. The change is applied before the response returns. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Request `application/json` ```json { "type": "object", "description": "VM notes (not the hostname).", "properties": { "description": { "type": [ "string", "null" ], "description": "VM notes (plain text, max 4096 characters).", "maxLength": 4096 } } } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a VM write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Resize a VM (/en/docs/api/virtual-machines/upgrade-vm) `POST https://api.hostd.cloud/v1/cloud/project/{project_uuid}/vm/{vmid}/upgrade/` Changes CPU, RAM, OS disk, CPU class, and public/private networking on an existing VM. After the VM is created or CPU, RAM, or CPU class is increased, you can lower those resources 24 hours later. CPU or RAM downgrade is allowed only while the VM is stopped. OS disk size cannot shrink. You cannot switch between attached WAN modes (`ipv4` / `ipv6` / `dual`); disable WAN first. ## Parameters - `project_uuid` (path, required) `string`: Project UUID. - `vmid` (path, required) `integer`: VM identifier (VMID). ## Request (required) `application/json` ```json { "type": "object", "description": "Resize CPU, RAM, disk, CPU class, and networking on an existing VM.", "properties": { "cores": { "type": "integer", "minimum": 2, "description": "vCPU count (hotplug `vcpus`). CPU downgrade requires the VM to be stopped." }, "ram_gb": { "type": "integer", "minimum": 1, "description": "RAM in GiB, between 1 and 4 GiB per vCPU: 2 GiB steps up to 48 GiB, odd sizes from 49 to 113 GiB, then 117, 121 … GiB. RAM downgrade requires the VM to be stopped." }, "os_disk_gb": { "type": "integer", "minimum": 10, "description": "OS disk size in GiB. May only stay the same or grow." }, "cpu_mode": { "allOf": [ { "enum": [ "light", "regular" ], "type": "string" } ], "default": "regular", "description": "CPU class: `light` or `regular` (default)." }, "wan_mode": { "allOf": [ { "enum": [ "off", "ipv4", "ipv6", "dual" ], "type": "string" } ], "description": "Public WAN: `off`, `ipv4`, `ipv6`, or `dual`. You cannot switch between attached modes; disable WAN first." }, "wan_ip": { "type": [ "string", "null" ], "description": "Reserved project IPv4 to attach. Omit to pick the next free address.", "maxLength": 45 }, "wan_ipv6": { "type": [ "string", "null" ], "description": "Reserved project IPv6 to attach. Omit to pick the next free address.", "maxLength": 45 }, "release_public_ip": { "type": "boolean", "default": true, "description": "When disabling WAN, release the address (true) or keep it reserved on the project (false)." }, "lan_interfaces": { "type": "array", "items": { "type": "object", "properties": { "vnet": { "type": "string", "description": "Private network (VNet) name.", "maxLength": 255 }, "mode": { "allOf": [ { "enum": [ "auto", "select" ], "type": "string" } ], "description": "`auto` picks a free IP; `select` uses `ip`." }, "ip": { "type": [ "string", "null" ], "description": "IPv4 address when `mode` is `select`.", "maxLength": 45 }, "interface_name": { "type": [ "string", "null" ], "description": "Ignored. The API assigns `netN` from the private network.", "maxLength": 40 }, "is_gateway": { "type": "boolean", "default": false, "description": "When WAN is off and several LANs are attached, exactly one must be the gateway." } }, "required": [ "mode", "vnet" ] } } }, "required": [ "cores", "os_disk_gb", "ram_gb", "wan_mode" ] } ``` ## Responses ### 200 `application/json` ```json { "type": "object", "description": "Short confirmation after a VM write.", "properties": { "message": { "type": "string", "description": "Short status message." } }, "required": [ "message" ] } ``` ### 400 The request is invalid. ### 403 You are not a member of this project, your role cannot write, or write access is blocked (card verification or billing hold). ### 404 VM not found in this project. ### 500 The cluster could not complete the request. # Datastore (/en/docs/cloud/backup/datastore) In the **Datastore** section, you can inspect existing backups, check how much space they occupy, and restore individual files. ![Backup Datastore – statistics and volume list](/docs/backup-datastore.png) ## Steps [#steps] 1. Open the `Backup → Datastore` section. 2. Find the relevant virtual machine in the list. 3. Expand it to see specific backup copies (volumes). You can check their logical size, actual on-disk size, and creation date. 4. Use **File restore** on a volume to browse and download individual files (without a full VM restore). ## Watch out [#watch-out] Backups cannot be deleted manually. Old backups are removed by the retention of the backup job, and all backups of a VM are deleted together with it. Full VM restore is on `VM → Backups`; this page is for viewing and file restore. # File restore (/en/docs/cloud/backup/file-restore) If you accidentally deleted a few files and do not want to roll back the state of the entire system, you can download individual files or folders directly from a backup. ![File restore – file tree](/docs/backup-file-restore.png) ## Steps [#steps] 1. Open the `Backup → Datastore` section. 2. Find the backup copy you need and click **File restore**. 3. A file tree of your system will open – you can expand folders and search for the required data. 4. Once you find the file or folder, click the corresponding button to download it (folders will be downloaded as a zip archive). ## Watch out [#watch-out] This tool is designed mainly for downloading configuration files or smaller directories (roughly up to **200 MB**). If you need to recover a massive database or a full machine archive, it is better to use full VM restoration or contact [support](https://hostd.cloud/contact). # Backup (/en/docs/cloud/backup) Here you will find instructions for backing up your virtual machines: from configuring regular schedules to restoring individual files. Configuring schedules (weekdays, time window) and retention policies. Viewing existing backup copies and statistics. Downloading individual files or folders without having to fully restore the entire virtual machine. Full recovery of a virtual machine from a saved copy. ## Watch out [#watch-out] The platform infrastructure ensures safe and reliable backup storage, but configuring schedules and regularly testing data recovery remains your responsibility. We recommend periodically verifying that your data can be successfully restored. # Backup jobs (/en/docs/cloud/backup/jobs) Create and maintain scheduled VM backup jobs. ![Create backup job – modal](/docs/backup-job-create.png) ## Before you begin [#before-you-begin] - Admin or Superadmin access to the project. - VMs you want to protect are listed in the project. ## Steps [#steps] 1. Open `Backup → Jobs`. 2. Click **Create backup job** (or edit an existing job). 3. Fill in the **Create backup job** dialog (see below). 4. Select VMs under **Virtual machines** and click **Create**. 5. Check the warning list for VMs without a backup job. ## Fields in **Create backup job** [#fields-in-create-backup-job] **General** - **Enabled** – turns the job on or off without deleting the schedule. - **Job name** – short label in the portal (e.g. `Production VMs`). - **Backup time window** – when a backup may start (currently **00:00–06:00**). **Schedule** - Weekdays – which days the job may run (at least one day required). **Retention** - **Keep daily**, **Keep weekly**, **Keep monthly**, **Keep yearly** – how many copies to keep at each tier (see below). Empty or **0** disables that tier. If all tiers are empty, the default applies: the 3 latest, 7 daily and 4 weekly copies. **Virtual machines** - Project VM table – select machines covered by this job. A VM already in another job is greyed out (**in another job**). ## Retention – how it works [#retention--how-it-works] Retention controls how many backup copies stay on the datastore. Older copies are removed automatically; backups cannot be deleted manually. If you remove a VM from a job, its existing backups stay (and are billed) until the VM is deleted. - **Keep daily** – how many recent day-level copies to keep (e.g. **7** ≈ one week of daily restore points). - **Keep weekly** – additionally keep one copy per week (e.g. **4** ≈ about a month of weekly history). - **Keep monthly** / **Keep yearly** – longer history; set only when you need older copies. **How to set it:** for a typical VM, keep the defaults **7** daily and **4** weekly. For test environments, **3** daily and **0** weekly is often enough. For production with longer history, raise daily or add monthly (e.g. **3**). Form limits: daily up to **90**, weekly **26**, monthly **12**, yearly **2**. The more copies you keep in retention, the more storage backups use and the higher retention cost can be. ## Backup storage cost [#backup-storage-cost] Backups on PBS are **incremental** and **deduplicated**. In `Backup → Datastore` you see two sizes: - **Logical** – total data size in the backup index. - **On-disk** – actual disk usage after deduplication and compression. **Billing is hourly based on on-disk** GiB on the project datastore, not logical size. You can also check usage in `Project → Usage` (backup column: logical / on-disk). ### Illustrative example [#illustrative-example] A test VM with a **100 GiB** disk. About **5%** of data changes each day (~**5 GiB**). Daily backups, **7** daily retention (default): | Stage | Rough estimate | |-------|----------------| | First backup (full) | ~**100 GiB** on the datastore | | Each following day | ~**+5 GiB** of changed data, not another full 100 GiB | | After ~7 days | on the order of **~130 GiB** on-disk (100 + 6×5), not 7×100 GiB | | With **keep daily** = **30** | on the order of **~245 GiB** (100 + 29×5) – much higher storage cost | This is a simplified example: real on-disk usage depends on how many blocks repeat between copies. Always check **on-disk** in the datastore before raising retention. ## Watch out [#watch-out] The default project backup job limit is **1**. A backup job does not replace restore testing. # Billing (/en/docs/cloud/billing) The public cloud infrastructure is billed **hourly in Polish Zlotys (PLN)**. You pay for the resources allocated to your project: vCPU, operational memory, disk space, public IPv4 addresses, Cloud Gateway, and backup storage. You can manage your balance in the [`Billing`](https://hostd.cloud/app/settings/billing) panel and view or pay invoices in [`Invoices`](https://hostd.cloud/app/settings/invoices). How Prepaid and Postpaid models work and how they differ. When we issue invoices and what exactly they include. What resources you continue to pay for, even if you stop your server. # Invoices (/en/docs/cloud/billing/invoices) All your invoices can be viewed or downloaded in PDF format in the [`Invoices`](https://hostd.cloud/app/settings/invoices) panel. You can also pay them online there. The invoicing schedule depends on your payment model. ## Prepaid (prepayment) [#prepaid-prepayment] In this model, you top up your balance in advance, and the cost of services is deducted from it hourly. A VAT invoice is generated **at the moment of each balance top-up** (it is listed on the invoice as *Doładowanie salda rozliczeniowego*). Ongoing daily resource consumption does not generate new invoices. ## Postpaid (payment in arrears) [#postpaid-payment-in-arrears] In this model, you pay for actual consumption over the past period. A single consolidated VAT invoice is issued **at the beginning of each month**. - Each of your projects is displayed on the invoice as a separate line item: `Public Cloud {uuid} | {project name}` with a consolidated summary of resource consumption (vCPU hours, RAM, disk, etc.). - If a project's charge for the month is less than **1 PLN net**, it is not charged. - Funds carried over from your prepaid balance are shown as a **Niewykorzystane saldo prepaid** line item, and a compensation credit as a **Rabat** line item with the specified reason. If they cover the whole month, no invoice is issued. ### How to pay an invoice [#how-to-pay-an-invoice] You can pay invoices via bank transfer (payment details are specified in the PDF file itself) or online directly in the portal using a card, Apple Pay, or Google Pay. With a saved card, you can pay an invoice in one click. # Billing models (/en/docs/cloud/billing/models) The platform accrues charges **hourly** for all resources allocated to your project (even if they are not 100% loaded). Your account can operate under one of two payment models, and this model applies to all of your projects simultaneously. | | **Prepaid** (default) | **Postpaid** | |---|---|---| | Payment | Upfront – from account balance | In arrears – monthly invoice | | Accounting | Hourly balance deduction | Hourly resource usage recording | | Invoice | Instantly upon each balance top-up | At the beginning of the month for the previous month | | Automation | Auto-reload (automatic balance top-up) | One-click payment with a saved card | ## Prepaid (prepayment) [#prepaid-prepayment] This model is enabled automatically upon registration. You top up your balance in the Billing panel, and the cost of used resources is deducted from this amount every hour. - **Top-up** – the minimum amount is **50 PLN net** (maximum is 2000 PLN). You can pay by card, Apple Pay, or Google Pay. VAT is added at the moment of payment. - **Auto-reload** – a very convenient feature that allows you to automatically top up your balance from a saved payment card when it falls below a specified threshold. - If you have promotional or bonus funds on your balance, the system will always deduct resources from these funds first, and only then from your real money. ## Postpaid (payment in arrears) [#postpaid-payment-in-arrears] This model allows you to use services without prepayment and receive an invoice after the consumption period. To switch to this model, you need to submit a request to support via the **Request contract billing** button in the Billing panel. - At the beginning of each month, you receive a single invoice for all resources consumed during the previous month. - If an **individual discount** is agreed for your account, it is automatically taken into account in hourly charges. - You pay issued invoices by bank transfer or in one click with a saved card under **Invoices**. - In this model, your current accrued total is visible in real-time, while the direct balance top-up feature is disabled since you simply pay the issued invoices. ### Credit on next invoices [#credit-on-next-invoices] When you switch to postpaid, the unused funds on your prepaid balance carry over to your next invoices. In case of outages or as a gesture of goodwill, hostd may also grant you a one-time compensation credit. The welcome bonus does not carry over. - Credit is deducted from the month's charges in full, oldest first. On the invoice, the carried-over balance is shown as **Niewykorzystane saldo prepaid** and compensation as **Rabat**. - If the credit covers the whole month, no invoice is issued for that month, and we email you the charges and the credit left. - Any unused part carries over to the following months. The remaining amount is shown in the Billing panel. # Stopped VM costs (/en/docs/cloud/billing/stopped-vm-costs) Stopping (Stop) a virtual machine halts the billing of compute resources (**vCPU** and **RAM**). However, all other reserved resources continue to be billed hourly because the platform continues to reserve them for you. A virtual machine that ran during any part of an hour is billed for that whole hour as running. | Resource | Billed for a stopped VM? | |---|---| | vCPU and RAM | No | | System disk (storage) | Yes | | Floating IP (public IPv4) | Yes | | PBS backup storage | Yes | Therefore, a stopped virtual machine **does not equal zero cost**. If you want to completely stop the billing of, for example, a disk or a public IP, you must permanently delete the virtual machine (along with its disk) or release the IP address from your project. You can always check the hourly breakdown of costs on the `Project → Usage` page (available only to the account owner). # Platform capabilities (/en/docs/cloud/capabilities) The hostd Public Cloud is a reliable, scalable, and secure infrastructure (IaaS) built on top of leading enterprise-grade technologies. ## Technology Stack & Hardware [#technology-stack--hardware] We use only proven and reliable hardware from global industry leaders to ensure maximum performance and stability for your workloads. } title="Virtualization"> **Proxmox VE** – stable enterprise repository branch based on KVM/QEMU } title="Physical servers"> Exclusively **Dell PowerEdge** with **AMD EPYC** processors } title="Network gear"> Switches and routers from **Dell PowerSwitch** and **Juniper** } title="Backup system"> **Proxmox Backup Server (PBS)** – isolated deduplicated datastore per project } title="VM storage"> Distributed all-flash NVMe (SDS) with **RoCEv2** and asynchronous `io_uring` ### Storage Performance [#storage-performance] Thanks to all-flash NVMe storage and modern transmission protocols, typical latency for **4k randwrite** operations in **t1q1** mode (1 thread, `iodepth=1`) with **fsync** is only about **0.11 ms** (measured directly at the hypervisor level). *Note: This is an infrastructure metric, not an SLA for your application inside the VM, as the guest OS file system and emulation add their own overheads.* Each VM virtual disk is capped at **15,000 IOPS** read and write and **500 MB/s** read and write throughput. Details: [Storage](/en/docs/cloud/storage). ### Available Zones [#available-zones] - **WAW-AMD1** – Warsaw, Poland. The infrastructure is located in certified **Atman WAW-2** and **Equinix WA2** data centers (Tier III+ compliance). Your data and backups physically remain in Poland. ## Compute Resources [#compute-resources] - **Modern Linux OS:** Instant deployment of clean and stable images of Ubuntu, Debian, Rocky Linux, AlmaLinux, and Fedora. - **Flexible CPU classes:** - **Regular:** Default class for typical web applications and services. - **Light:** Lower scheduler priority – testing, development, and light background tasks. - **Instant Scaling (Resize):** Increase vCPU, RAM, and system disk size on-the-fly without stopping the system. - **Guaranteed High Availability (HA):** Free automatic protection against hardware failures. If a physical host fails, your VM is automatically rebooted on another working host in less than a minute. - **Snapshots:** Take an instant snapshot of the disk state for quick and safe rollbacks during system updates or testing. ## Networking & Security [#networking--security] - **Public WAN (IPv4 / IPv6):** Attach a public address in **IPv4**, **IPv6**, or **IPv4 + IPv6** mode (or leave WAN off). Addresses are assigned directly to the instance interface without overlay NAT. Hourly public IP billing applies to **IPv4 only**. - **Private Networks (VLAN):** Create fully isolated Layer 2 local network segments for secure communication between instances, featuring built-in IPAM (IP Address Management). - **Reverse DNS (PTR):** Manage PTR records for your public IPv4 and IPv6 addresses directly through the portal. - **Firewall:** Set up traffic filtering rules on public WAN interfaces. - **Security Groups:** Reusable firewall rule templates that can be quickly applied to multiple virtual machines. - **Network Map:** Interactive visual representation of your entire infrastructure, showing connections between instances, private networks, and gateways. - **External VLAN:** Integrate the cloud with your physical hardware (bare metal or on-premises) via a dedicated Layer 2 channel. ## Cloud Gateway [#cloud-gateway] A specialized, fully managed infrastructure router for your private networks. - **Full Automation:** Configure NAT, port forwarding, VPN, and proxying without the need to manually administer the router's operating system. - **WireGuard VPN:** Fast and secure access for administrators and developers to local cloud resources over an encrypted tunnel. - **Reverse Proxy:** A high-performance reverse proxy based on Caddy with automatic Let's Encrypt SSL certificate generation upon the first domain request. ## Backups & Recovery [#backups--recovery] An integrated, fully automated backup system powered by enterprise-grade Proxmox Backup Server (PBS) technologies. - **Regular Schedules (Backup jobs):** Configure flexible automated backup schedules for groups of virtual machines. - **Incrementality & Deduplication:** Backups copy only modified disk blocks and undergo deduplication at the storage level, resulting in massive savings in disk space (on-disk size) and reducing storage costs. - **File-level Restore (File restore):** Browse the backup file tree and download individual files or folders directly from the backup without a full system rollback. - **Backup on demand:** Start a backup of a VM manually, for example before an update. - **Backups follow the VM:** Old backups are removed by the retention of the backup job, and all backups of a VM are deleted together with it. ## Management & Billing [#management--billing] - **Team Access:** Add members by email and assign roles (Superadmin, Admin, Auditor) for secure joint infrastructure management. - **Hourly Billing:** Charges are accrued solely for actually allocated resources with hourly precision. - **Two Payment Models:** Pay in advance (Prepaid with auto-reload) or after consumption (Postpaid with invoices at the beginning of the month). # Cloud Gateway (/en/docs/cloud/cloud-gateway) Cloud Gateway is a managed router that hostd automatically deploys for your private network. It allows you to configure NAT, port forwarding, WireGuard VPN, and a reverse proxy. ## What is it? [#what-is-it] It is a completely isolated router virtual machine. Its main difference from your standard VMs is that **you do not have SSH or console access to it**. All settings are configured exclusively through the hostd portal interface, and the infrastructure automatically applies them under the hood. To ensure reliability, Cloud Gateway runs with **High Availability (HA)** enabled right from the moment of creation. If the physical server hosting your router fails, the system will automatically restart it on another working node (this usually takes less than a minute). You do not need to configure HA for it manually. ## When you need it [#when-you-need-it] Cloud Gateway is useful when VMs on a private network **do not have their own public IPs**, and you need: - outbound internet access (NAT) via the gateway WAN address; - inbound access to specific services on VMs (port forwarding); - secure admin access to the private network (WireGuard); - HTTP/HTTPS publishing with a Let's Encrypt certificate (reverse proxy). If an isolated VLAN without internet routing is enough, you can disable or remove Cloud Gateway at any time. ## How to enable Cloud Gateway [#how-to-enable-cloud-gateway] You can activate it when creating a new private network (`Network → Private networks → New` → **Enable Cloud Gateway**) or add it later to an existing VLAN (using the **Enable Cloud Gateway** button in the network's menu). For Internal VLAN networks, the gateway is enabled by default when you create the network. The router will automatically occupy the **`.1`** IP address in your subnet and act as the default gateway for all connected VMs. Therefore, make sure this address is free. You can assign the gateway's public IPv4 automatically (first free address from the pool) or pick one already reserved in the project. The public IP is billed separately from the Cloud Gateway service itself. ![Creating a private network with Cloud Gateway](/docs/cloud-gateway-private-network-new.png) ## Services [#services] Once the gateway is running, you configure in the portal: Forwarding ports from the router's public IP address to the internal IP addresses of your VMs. Secure VPN access to the private network for your administrators or developers. Configuring an HTTP/HTTPS proxy with automatic Let's Encrypt SSL certificate generation. ## Watch out [#watch-out] You can completely delete Cloud Gateway at any time to stop its billing. The private network (VLAN) itself will not be deleted, and your VMs will continue to communicate with each other over the local network. # Port forwarding (/en/docs/cloud/cloud-gateway/port-forwarding) Port forwarding (DNAT) allows you to receive network traffic on the public IP address of your Cloud Gateway and automatically forward it to a specific virtual machine inside the private network. ![Port forwarding – DNAT rule](/docs/cloud-gateway-port-forwarding.png) ## Steps [#steps] 1. Open your private network settings and go to the **Port forwards** tab. 2. Click **Add** and specify the parameters: protocol, public port on the router, as well as the internal IP address and port (backend) of the target VM. 3. Click **Save** to save the rule. 4. Verify the connection from the outside. ## Watch out [#watch-out] If you plan to use the [Reverse proxy](/en/docs/cloud/cloud-gateway/reverse-proxy) service, remember that TCP ports **80** and **443** will be reserved for it and cannot be used for standard port forwarding. In this case, use other public ports or configure proxy routing for the traffic. # Reverse proxy (/en/docs/cloud/cloud-gateway/reverse-proxy) You can use Cloud Gateway as a reverse proxy (powered by Caddy), which will accept HTTP and HTTPS traffic and forward it to your backend servers. It automatically obtains and renews free SSL certificates from Let's Encrypt for your domains. ![Reverse proxy – vhost and backend](/docs/cloud-gateway-reverse-proxy.png) ## Steps [#steps] 1. In your DNS provider's control panel, create an **A record** pointing your domain to the public IP address of your Cloud Gateway. 2. In the hostd portal, open the **Reverse proxy** tab in your private network's settings and **enable** the service. 3. Add your domain name (hostname) and specify the private IP address and port of your target VM (backend). 4. Click **Save** to save the configuration. 5. Try opening your domain in a browser via HTTPS. If the A record is configured correctly, the system will automatically generate an SSL certificate during the first visit to the site. ## Watch out [#watch-out] Managing direct DNS records (A records) for your domain is handled entirely on the side of your DNS provider. Please note: enabling the Reverse proxy service completely reserves TCP ports **80** and **443**, as well as UDP port **443** on the Cloud Gateway, preventing them from being used for standard port forwarding. # WireGuard (/en/docs/cloud/cloud-gateway/wireguard) WireGuard allows you to create a secure VPN tunnel between your computer and your private network in the cloud. This is ideal for administrative access to databases or internal services without exposing them to the public internet. ![WireGuard – page overview](/docs/cloud-gateway-wireguard.png) ## Steps [#steps] 1. In your private network settings, navigate to the **WireGuard** tab. 2. If the server is not configured yet, click **Set up WireGuard server** (or **Enable** if it was previously disabled). 3. Click **Add peer** and enter a clear name for your device (for example, "Admin's Laptop"). 4. In the list of peers, open the **Peer config** menu. You can scan the QR code using the WireGuard mobile app or click **Download** to save the configuration file (`.conf`) for your desktop client. 5. Import the file into your WireGuard client, connect, and verify access (for example, by pinging the private IP address of any of your VMs). ![Peer config – QR code and download](/docs/cloud-gateway-wireguard-peer-config.png) ## Watch out [#watch-out] The downloaded configuration is set up so that **only traffic destined for your private network** is routed through the VPN (split tunneling). All of your normal internet traffic (web browsing, YouTube, etc.) will go through your usual connection as always, without putting load on the Cloud Gateway. # High Availability (HA) (/en/docs/cloud/datacenter/high-availability) High Availability (HA) mode automatically protects your virtual machines against hardware failures. If the physical server hosting your machine fails, the platform will independently restart it on another working server. ## Steps [#steps] 1. Navigate to the `Datacenter → High Availability` section. 2. Toggle the **HA** switch for the desired virtual machine. 3. If necessary, create an **affinity rule** to define whether certain VMs should run on the same physical server or must run on different ones. 4. You can always check the current HA status on the Summary tab in the settings of a specific VM. ## Watch out [#watch-out] - Restarting a virtual machine on another server during a failure typically takes **up to one minute**. Please note that this is a hardware reboot (similar to powering on after a power outage), so it does not protect against internal failures of the operating system itself. - The High Availability feature is provided entirely **free of charge** – you only pay the standard hourly cost of your machine's vCPU and RAM. - Each affinity rule can combine between **2 and 3 VMs**. A single virtual machine can belong to only one placement rule. # Datacenter (/en/docs/cloud/datacenter) The **Datacenter** section groups tools that work directly with the Proxmox cluster running your project. Viewing operation history, execution statuses, and errors. Activating high availability for virtual machines and configuring mutual placement rules (affinity rules). ## Watch out [#watch-out] Configuring High Availability requires **Admin** or **Superadmin** access permissions. # Tasks (/en/docs/cloud/datacenter/tasks) The task log displays the history of all infrastructure operations in your project (such as creating virtual machines, resizing them, starting and stopping them, etc.). This helps identify which team member initiated a specific action and check its current status. ![Tasks – project task history](/docs/datacenter-tasks.png) To view the log, open the `Datacenter → Tasks` section. Any project member, regardless of their role, can view the detailed table: - **Start Time / End Time** – the exact start and completion times of the task. - **Operation Description** – what specific action was performed. - **Status** – the current execution status (`OK`, `running`, or an error description if something went wrong). - **User** – the email of the team member who started the task. ## Watch out [#watch-out] - This log only records operations related to cloud management at the hostd portal level. It does not display system events or logs inside the operating system of the virtual machine itself. - Automated scheduled backup jobs and High Availability (HA) automatic restart operations are part of the platform's internal system logic and are not displayed in this user actions table. # Getting started (/en/docs/cloud/getting-started) This guide will help you create your first project, securely configure access rules, launch your first virtual machine, protect it with a firewall, enable High Availability (HA), and configure automated backups. ## Roadmap [#roadmap] 1. [Project creation](#step-1-project) 2. [VM launch](#step-2-vm) 3. [Security Group configuration](#step-3-security-group) 4. [Firewall configuration on the VM](#step-4-firewall) 5. [High Availability (HA) enablement](#step-5-ha) 6. [Backup Job configuration](#step-6-backup-job) ## Before you begin [#before-you-begin] - Review the [Resources and limits](/en/docs/cloud/public-cloud-overview) page to understand how the platform works and what limits apply. - Prepare an SSH key on your computer (you will need the public part of the key to paste into the form). - Install an SSH client. You can also use the web console (`VM → Console`) if needed. - For prepaid accounts, make sure you have sufficient balance. ## Steps [#steps] ### 1. Create a project [#step-1-project] 1. Open the management panel: `Console → Public Cloud`. 2. Click **Create project**, choose a convenient zone, enter the **Project name**, and confirm the creation. ![Create project – Public Cloud](/docs/getting-started-create-project.png) ### 2. Create a virtual machine (VM) [#step-2-vm] 1. On the overview page of your new project, click **Create VM**. 2. Select the operating system image, specify the `hostname`, `username`, and password. 3. Add your **public SSH key** into the corresponding field. 4. Configure the required resources (vCPU, RAM, disk size, and `CPU mode`). 5. Enable the **public WAN** (Public WAN) option so the machine gets internet access. 6. Click **Create**. The VM creation and initial setup via `cloud-init` takes up to one minute. ![Create VM – form with image, SSH key, and WAN](/docs/vm-create-form.png) ### 3. Create a Security Group [#step-3-security-group] To easily manage the same rules (such as SSH access) across multiple servers, it is recommended to use Security Groups. 1. Navigate to the `Network → Security groups` section. 2. Create a new security group. Use a short Latin name (up to **15** characters). 3. Add an **IN** rule to allow connections: select protocol **TCP**, port **22** (SSH). In the **Source** field, specify your IP addresses in the `x.x.x.x/32` format. ![Security groups in Network](/docs/datacenter-firewall-group.png) ### 4. Configure Firewall on the VM [#step-4-firewall] Now you need to protect your virtual machine from unwanted traffic. To do this, open `VM → Firewall` (rules apply only to the public WAN interface). 1. Toggle the **Global Status** switch to **On**. 2. Change **Policy In** to **DROP** – this will block all incoming traffic except for what you explicitly allow. 3. Click **Apply** to apply the policy. 4. Add permission for SSH: click **Insert Security Group** and select the group from step 3, or click **Add Rule** and create a standard rule only for this machine. 5. Now you can securely connect to the machine via SSH. ![VM Firewall – Global Status, Policy In, and rules](/docs/getting-started-vm-firewall.png) ### 5. Enable High Availability (HA) [#step-5-ha] HA mode automatically restarts your virtual machine on another physical server if the current node fails. This feature is provided completely **free of charge** – you only pay the standard hourly cost of your VM's vCPU and RAM. 1. Navigate to the `Datacenter → High Availability` section. 2. Toggle the **HA** switch to **On** for your virtual machine. 3. If necessary, create an **affinity rule** to determine whether specific VMs should run on the same physical server or must run on different ones. 4. You can always check the current HA status on the `Summary` tab in the VM's settings. ![High Availability in Datacenter](/docs/datacenter-ha-enable.png) ### 6. Create a Backup Job [#step-6-backup-job] Automatic schedules (backup jobs) are the primary tool for regularly saving the state of your VMs. By default, you can create **1** backup job per project, but you can add multiple virtual machines to it. 1. Open `Backup → Jobs`. 2. Click **Create backup job**. 3. Specify a **Job name** (e.g., `Production VMs`) and make sure the **Enabled** toggle is active. 4. Select the days of the week for the backup (at least one day is required). Backups are initiated within the allowed time window: **00:00–06:00**. 5. Configure **Retention**: for a typical VM, **Keep daily = 7** is sufficient. 6. Select your VM in the **Virtual machines** table and click **Save**. ![Create backup job – dialog](/docs/backup-job-create.png) ## Watch out [#watch-out] - Until you activate the Firewall (step 4), your VM with a public IP will be completely open to the internet on all ports. Configure the firewall immediately before hosting any important data or services on the machine. - If you stop the VM, billing for CPU and RAM stops. However, you will continue to pay for the allocated disk, attached Floating IP, backups, and Cloud Gateway. - HA protects against hardware failures (restart usually takes up to a minute) but not from OS-level crashes. Use backups (step 6) to protect your data. - Backups are billed based only on the real (on-disk) space used after compression and deduplication – see [Datastore](/en/docs/cloud/backup/datastore). # Introduction (/en/docs/cloud) This section contains all the necessary information to work with the hostd Public Cloud – from creating your first virtual machine to configuring networking and backups. ## Where to start [#where-to-start] Detailed overview of our technology stack, architecture, and hardware. Step-by-step guide to launching a secure VM. Resource organization at the account and project levels, CPU modes, and default limits. Team management, cost monitoring, and limits. Creation, connection, resizing, reinstallation, snapshots, backups, and deletion. Public IPs, PTR records, private networks, external VLANs, security groups, and IP sets. NAT, port forwarding, WireGuard, and reverse proxy settings. Backup schedules, datastore management, and file restoration. Tasks and High Availability (HA). Prepaid and postpaid models, invoicing, and resource costs. ## Please note [#please-note] - Public Cloud is an IaaS (Infrastructure as a Service) platform. We guarantee the operation of physical hardware, virtualization, and network, while operating system and software management is handled on your side. # External VLAN (/en/docs/cloud/networking/external-vlan) **External VLAN** brings a dedicated VLAN from your own infrastructure into your project as a private network. Instances attached to it share one Layer 2 segment with your equipment, and the traffic never crosses the public internet. You can connect: - An office or server room; - A colocation rack in another data center; - Physical dedicated servers (bare metal), your own routers or switches. ## How it works [#how-it-works] 1. Your carrier delivers the VLAN from your site to the handoff point with our network. 2. We carry the VLAN from the handoff point to the cluster of your zone. 3. The VLAN appears in your project as a private network. 4. You pick that network in an instance's network settings, the same way as any [private network](/en/docs/cloud/networking/private-network). ## Carriers [#carriers] - **EPIX / e-Południe** – if you are an EPIX member, order the VLAN to hostd on your side; we take it from the handoff point. - **Zprava** – a VLAN through the Zprava network. Not connected to either of them? Contact us and we will plan the route together. ## Parameters [#parameters] | Parameter | Value | |-----------|-------| | Bandwidth | 1 Gbps by default, 2 or 4 Gbps on request | | MTU | 1500 by default, 9000 on request | | Setup on our side | Within one business day after the carrier delivers the VLAN to the handoff point | ## What the network includes [#what-the-network-includes] An External VLAN is a plain Layer 2 segment between your site and your instances: - **Cloud Gateway** is not available on this network. Routing, NAT, and internet access for the segment stay on your side. - **VM firewall rules** do not apply to traffic on this network. Filter it on your router or inside the guest operating system. - Addressing (static IPs or your own DHCP server) is managed by you. - The link runs through one carrier. Redundant links through two carriers into the same VLAN are not offered. ## Pricing [#pricing] Our part, from your instances to the handoff point, is billed as **Private network (external VLAN)** in the [price list](https://hostd.cloud/en/pricing). The carrier charges for its part of the link separately. ## How to order [#how-to-order] Contact [sales](https://hostd.cloud/en/contact/sales) or open a support ticket in the portal. Include: - The project the VLAN should appear in; - Your carrier (EPIX / e-Południe, Zprava, or other); - The required bandwidth and MTU. # Floating IP (/en/docs/cloud/networking/floating-ip) Keep a public IPv4 reserved in the project after VM or gateway delete, and attach it to another VM or gateway later. ## How it works [#how-it-works] In hostd Public Cloud, a Floating IP is a **real public IPv4** assigned directly to the WAN interface of your VM or Cloud Gateway – not a separate virtual address mapped through 1:1 NAT, as in a typical OpenStack floating IP. - The address lives on the instance itself; traffic to that IP reaches the VM or gateway without an extra overlay or proxy hop. - Inside the guest OS you see the same public address on the network interface (for example `net0` on a VM). - **Floating** means the IPv4 stays in your project when you delete the VM or gateway, so you can attach it to another resource later – not that the address is virtual. ## Before you begin [#before-you-begin] - A public IPv4 assigned to a VM or Cloud Gateway, or already reserved in the project. ## Steps [#steps] 1. Check the address in `Network → Public IPs`. 2. When deleting a VM or gateway, turn off **Release public IP address** to keep the IP reserved in the project. 3. When creating another VM or gateway, select the reserved IP instead of **Auto**. 4. To change the public IP on the same VM: in [Resize VM](/en/docs/cloud/virtual-machines/resize), turn WAN (net0) off, save, then turn WAN on again and choose **Auto** or another reserved address. ## Watch out [#watch-out] - While WAN is on, you cannot swap to another address directly – turn the public interface off first. - Changing the WAN IP does not require a VM reboot. # Networking (/en/docs/cloud/networking) This section contains instructions for configuring public IP addresses, creating private networks (VLANs), and managing your project's network topology. A visual topology of your project, showing active connections and VM statuses. Real public IPv4 addresses for your virtual machines and gateways, with the ability to reserve and reuse them. Configuring reverse DNS (PTR) records for public IP addresses. Creating isolated local networks (VLANs) and configuring internal address allocation (IPAM). Connecting a dedicated Layer 2 channel to your physical or external infrastructure (outside the cloud). Creating and configuring templates for firewall rules. Reusable lists of IPs and CIDRs for firewall rules. Configuring NAT, WireGuard VPN, port forwarding, and a reverse proxy on a virtual router. ## Watch out [#watch-out] If you want to reassign a public IP address to another virtual machine, first disable the public interface (WAN) in the `VM → Resize` section, save the settings, and then connect the interface again by selecting your desired reserved address. This works without requiring an operating system reboot. # IP sets (/en/docs/cloud/networking/ip-sets) IP sets are named lists of IPv4/IPv6 addresses and CIDRs. Create a list once, then reference it in firewall rules as **source** or **destination** instead of repeating the same addresses in every rule. ## Steps [#steps] 1. Open `Network → IP sets`. 2. Click **Add IP set** and enter a short Latin name (up to **15** characters). Rules use that name plus `_` and two characters (for example `office_ab`). The name cannot be changed later. 3. On the card, click **Add address** to add hosts or CIDRs (IPv4 up to **/24**, IPv6 up to **/64**). 4. Open `VM → Firewall` (or a security group’s rules) and create or edit a rule. 5. In **Source Address** or **Destination Address**, choose the IP set from **Use IP set…**, or type `+office_ab` manually. 6. Later changes to the IP set members apply everywhere that set is referenced. ## Watch out [#watch-out] - An IP set only affects traffic when a firewall rule uses it and the VM firewall is enabled (**Global Status** = **On** on `VM → Firewall`). - Direct CIDR in a rule is limited to **/26** for IPv4 and **/64** for IPv6; members inside an IP set may be IPv4 up to **/24** or IPv6 up to **/64**. - Deleting an IP set clears that reference from rules that used it. # Network map (/en/docs/cloud/networking/network-map) The **Network map** tab provides an intuitive logical schema of your entire project infrastructure, displaying the connections between the public internet, Cloud Gateway, private networks, and virtual machines. ![Network map in the portal](/docs/networking-network-map.png) ## What is displayed on the schema [#what-is-displayed-on-the-schema] 1. **WAN Node** (on the left) – shows the status of your public IPv4 address pool: the total number of addresses in the project, how many of them are currently in use, and how many remain free. 2. **Virtual Machines** (cards) – display the machine name, its public and private IP addresses, current power status, vCPU/RAM configuration, and load graph. Clicking on a VM name allows you to quickly navigate to its detailed settings. 3. **Private Networks** (circles with the name **vnet** and CIDR subnet) – visualize your internal VLANs. All machines connected to a local network are linked by lines to the corresponding subnet circle. 4. **Cloud Gateway** – displayed at the intersection of the public internet and your private network. Clicking on the gateway name opens the settings for WireGuard, reverse proxy, or port forwarding. 5. **Power Management and Console** – on the card of each running VM, there is a console icon (**Open Console in New Window**), and via the three-dots menu `⋯` you can quickly restart or stop the machine. ## Watch out [#watch-out] - This page is designed solely for visual monitoring and quick navigation. To change network or interface parameters, you must go to the appropriate sections (for example, `VM → Resize` or the settings of a specific private network). - Animated lines leading to virtual machines indicate that the server is currently running (status **running**). Cloud Gateway lines are always animated. This is a visual indicator of activity status and not a real-time network traffic graph. - Virtual machines that are not connected to any network are grouped and displayed separately on the right side of the screen. # Private network (/en/docs/cloud/networking/private-network) A private network (local VLAN) allows you to combine your virtual machines into an isolated Layer 2 network segment. Traffic within such a network is completely protected from external access and is not metered or billed. ![Private network – list and VLAN layout](/docs/networking-private-network.png) ## Steps [#steps] 1. Open the `Network → Private networks` section. 2. Click **New** and create an internal VLAN, specifying your desired IPv4 subnet range (CIDR). 3. If virtual machines in this local network require secure internet access (NAT) or other network services, enable the **Enable Cloud Gateway** option. 4. Connect your virtual machines to the created network (this can be done either during the creation of a new VM or on a running machine via the `VM → Resize` section). 5. You can view the list of allocated addresses and manage them under the **IPAM** tab in your private network's settings. # PTR / reverse DNS (/en/docs/cloud/networking/ptr) A reverse DNS record (PTR record) is used to verify that your public IP address matches a domain name. Most commonly, a correct PTR record is necessary for the stable operation of mail servers (to prevent your emails from ending up in spam) or for access authorization and monitoring systems. ![Editing PTR in Network → IP Addresses](/docs/networking-public-ips-ptr.png) ## Steps [#steps] 1. Navigate to the `Network → Public IPs` section. 2. Select the desired public IP address and click on the **PTR** edit field. 3. Enter your domain name (FQDN) that you want to associate with this address. 4. Click **Save** to save the changes. ## Watch out [#watch-out] Managing direct DNS records for your domain (such as A, MX, CNAME, TXT) is handled on the side of your DNS provider (for example, Cloudflare or your domain registrar). Configuring PTR in our portal works exclusively for the reverse lookup of public IPv4 addresses allocated by our platform. # Security groups (/en/docs/cloud/networking/security-groups) Security Groups are templates for traffic filtering rules. They allow you to configure access rules (for example, opening ports for a web server or limiting access to a database) once and quickly apply them to multiple virtual machines. ## Steps [#steps] 1. Open the `Network → Security groups` section. 2. Click **Create group** and enter a short Latin name for the group (up to **15** characters). 3. Add the required rules for incoming (**IN**) or outgoing (**OUT**) traffic inside the created group. 4. Go to the settings of the desired virtual machine, open the `VM → Firewall` tab, and click the **Insert Security Group** button to attach the created rule template. 5. In the future, any changes you make to the security group in the Network section will automatically apply to all attached virtual machines. ## Watch out [#watch-out] A security group will only start filtering a virtual machine's traffic after you attach it to that VM and make sure that the firewall is enabled (the **Global Status** switch is set to the **On** position in the `VM → Firewall` settings). # Activity (/en/docs/cloud/projects/activity) The **Activity** log shows changes made in the project by all members, including actions through their API keys and the MCP server. Every project member can view it, regardless of role. ## Steps [#steps] 1. Open `Project → Activity`. 2. To narrow the list, type in the search field. It matches the member's email, the event, and the API key name. 3. To show a specific period, pick a date range with the date button. **Clear** returns to all dates. 4. Use the arrows below the table to move between pages (15 events per page). ## What the log shows [#what-the-log-shows] | Column | Contents | | --- | --- | | **Time** | When the change was made, in Europe/Warsaw time. | | **Event** | What was changed, for example an instance created, a firewall rule added, or a backup restored. Failed operations are marked **Failed**. | | **Actor** | Who made the change: the member's email (**You** for your own actions), plus the API key name for actions through an API key or MCP. Automatic actions show **System**. | The log covers instances (create, resize, reinstall, power actions, snapshots, restore from backup), networking (private networks, Cloud Gateway, public IPs and PTR), firewall (security groups, IP sets, VM rules), High Availability, backup jobs and backups, and project members. ## Watch out [#watch-out] - The project log does not show IP addresses or devices. Your own sign-ins and account changes, with IP address and device, are listed in `Settings → Activity`. - Date ranges are whole days in Europe/Warsaw time. # Projects (/en/docs/cloud/projects) A project in our system is the primary tool for grouping and isolating your cloud resources. ![Project overview – VM list and resource limits](/docs/project-overview.png) ## What a project consolidates [#what-a-project-consolidates] - Virtual machines and operations on them (starting, stopping, restarting, resizing); - Network infrastructure (private VLAN networks, dedicated public IP addresses, Cloud Gateway); - Backup system (personal backup schedules and a dedicated PBS datastore); - Access permissions, security groups, High Availability, and task log; - Financial statistics of project expenses (available only to the account owner). ## Watch out [#watch-out] You can delete a project only after all virtual machines and private networks have been completely removed from it. Project deletion is irreversible: it automatically releases all your public IP addresses, completely clears the backup storage (PBS datastore), and permanently deletes all backups. # Usage (/en/docs/cloud/projects/resource-usage) The **Usage** tab allows the project owner (Superadmin) to track hourly expenses in Polish Zlotys (PLN) for each type of active resource in detail. ![Usage – hourly costs](/docs/datacenter-resource-usage.png) ## Steps [#steps] 1. Open `Project → Usage` (only the project owner can access this section). 2. Review the hourly breakdown of costs across key categories: processors (compute), operational memory (RAM), disks (storage), **public IPv4**, backups, and Cloud Gateway. 3. Compare this data with active services in your project to understand the structure of your expenses. 4. For payments and viewing accounting documents, navigate to the `Billing` section. ## Watch out [#watch-out] - The **Public IPv4** column counts and prices **IPv4 addresses only**. Public IPv6 is not billed as a separate IP line. - The data on this page is intended for internal monitoring and budget planning. An hour appears about 10 minutes after it ends, once its cost is final. It is not a financial or accounting document (official invoices are generated exclusively in the `Billing` section). # Team access (/en/docs/cloud/projects/team-access) You can work on a project together with your colleagues or partners. Managing access and member roles is restricted to the project owner – the user with the **Superadmin** role. ![Add user and role](/docs/projects-team-access.png) ## Steps to grant access [#steps-to-grant-access] 1. Navigate to the `Project → Members` section. 2. Click the **Add permission** button. 3. Enter the email address of the user who has a registered hostd account and select their role (**Admin** or **Auditor**). 4. If necessary, you can always revoke access or change a user's role on the same list. ## Available system roles [#available-system-roles] | Role | Access Permissions | | --- | --- | | **Superadmin** | Project owner. Has full rights: managing members, viewing billing and financial expenses, creating, modifying, and deleting any VMs and networks. | | **Admin** | Technical administrator. Has full access to infrastructure management (creating, resizing, deleting VMs, network configuration) but cannot see financial information or the team access management section. | | **Auditor** | Observer. Has read-only access to view VM and network parameters without the right to make any changes. | ## Watch out [#watch-out] To successfully add a team member, they must already have a registered account in the hostd system. Immediately after entering their email address, the project will instantly appear in their personal control panel. # Resources and limits (/en/docs/cloud/public-cloud-overview) This page contains detailed information about account and project organization, CPU classes, and default system limits. ## Resource Organization [#resource-organization] Cloud infrastructure management is divided into two logical levels: **account** and **projects**. | Management Level | Contents | |---|---| | **Account** | General profile settings, financial balance, and total vCPU limit (shared across all projects). | | **Project** | Virtual machines, private networks (VLANs), reserved public IPs, Cloud Gateways, backup storage (PBS datastore), team access permissions, and hourly cost details. | Public Cloud services are billed **hourly in Polish Zlotys (PLN)**. We offer two payment models: - **Prepaid** – funds are deducted hourly from your balance. Automatic balance replenishment from a saved card is available (auto-reload). - **Postpaid** – pay for actually consumed resources. You receive a single invoice at the beginning of each month for the previous period (requires approval). For more details on payment models, see the [Billing models](/en/docs/cloud/billing/models) section. ## CPU classes [#cpu-classes] When creating a virtual machine or resizing it, you choose the **CPU class** and the number of **vCPUs**. The vCPU count is the number of virtual processors visible to the guest operating system. The CPU class sets the **relative scheduling priority** when VMs compete for CPU time on the host. When capacity is available, every class can use its allocated vCPUs; the class does not impose a fixed percentage cap on their usage. | CPU class | API slug | Role | |---|---|---| | **Regular** | `regular` | Default class for typical workloads | | **Light** | `light` | Lower scheduler priority – workers, staging, CI | Hourly vCPU rates differ by class (Regular, Light). The account vCPU limit counts every class **1:1**. ## Limits (Default) [#limits-default] To protect new accounts from uncontrolled expenses, default starting limits are in place. If your business needs more resources, please send a request to our support team. ### Account Limits [#account-limits] | Resource | Default Limit | |---|---| | Projects within one zone | **5** | | Total vCPU budget on account | **16** (raw vCPUs, all classes) | | Maximum vCPUs for a single VM | **16** | There is no separate limit on how many virtual machines you can create – only the vCPU budget and the derived RAM and disk quotas apply. The vCPU budget is shared across all projects of the account. Every CPU class counts as **1** against the budget. *Example of using a 16 vCPU budget:* 16 vCPUs in any mix of Regular and Light. A single VM is limited to 8 vCPUs. ### Requesting higher limits [#requesting-higher-limits] Open **Request higher limits** on the Public Cloud project list, **Account limits** in the user menu, or the link in the VM create and resize forms when a limit is reached. Set the new total vCPU budget and, if you need larger VMs, turn on **Raise vCPU per VM** and set the per-VM limit (both in steps of **2**); the RAM and disk quotas follow the vCPU budget. Use **Details** for anything else, such as more projects or private networks. The request opens a support ticket, and the new limits apply once support approves it. VMs in a shared project count against the project owner's account, so the owner sends the request. ### Project Limits [#project-limits] | Resource | Default Limit | |---|---| | Private networks (VLAN) | **1** | | Automated backup jobs | **1** | | Total RAM for all VMs | Account vCPU budget × **4** GiB (default **64** GiB) | | Total system disks (NVMe) for all VMs | Account vCPU budget × **100** GiB (default **1600** GiB) | ### Virtual Machine (VM) Limits [#virtual-machine-vm-limits] | Resource | Limits and Steps | |---|---| | vCPU Count | From **2** to limit (increases in steps of **2**) | | Operational Memory (RAM) | From **vCPU × 1** to **vCPU × 4** GiB, in **2 GiB** steps | | System Disk | From **vCPU × 10** to **vCPU × 100** GiB (in **20 GiB** steps) | | User Snapshots | **1** at a time per VM | | Private Network Interfaces (LAN) | Up to **8** interfaces (each requires a created private network) | | SSH Keys at Creation | Up to **5** keys | *Note: You can lower vCPU, RAM, or CPU class 24 hours after you create a VM or increase those resources. Lowering vCPU and RAM also needs a stopped VM. For more details, see the [Resize VM](/en/docs/cloud/virtual-machines/resize) section.* ### Network Limits and Rules [#network-limits-and-rules] | Feature | Limit or Rule | |---|---| | Public IPv4 | Reverse DNS (PTR record) can be easily changed directly in the portal. | | IPv6 | Public WAN in **IPv6** or **IPv4 + IPv6**. Hourly public IP billing is IPv4-only. | | Private Networks | Default **1** per project (only IPv4 addressing is supported). | | External VLAN | Connection interface is available in the UI, but support assistance is required for configuration. | | WAN Bandwidth | 250 Mbps for VMs with 2 vCPUs, +50 Mbps for each additional 2 vCPUs. | | LAN Bandwidth | 2 / 3 / 4 / 5 Gbps for the same vCPU levels (exact metrics are specified in the VM creation form). | | VM Firewall | Filters public WAN interface only. Subnets (CIDR) up to **/26** (IPv4) or **/64** (IPv6) are allowed in rules. | # Storage (/en/docs/cloud/storage) Read-only view of a project storage pool in the console, plus the performance limits applied to each VM virtual disk. ## Overview [#overview] See which VM virtual disks are on a given storage pool – disk capacity is billed in the project. VM system disks use distributed all-flash NVMe storage. See [Platform capabilities](/en/docs/cloud/capabilities) for architecture notes (RoCEv2, `io_uring`, latency reference). ## Disk performance limits [#disk-performance-limits] Every virtual disk is capped at the hypervisor with fixed IOPS and throughput limits. The values are the same for all VMs and are not configurable in the portal. | Limit | Value | |-------|-------| | Read IOPS | **15,000** | | Write IOPS | **15,000** | | Read throughput | **500 MB/s** | | Write throughput | **500 MB/s** | ## Watch out [#watch-out] Additional VM disks are not available in the portal. Increase the system disk on [Resize a VM](/en/docs/cloud/virtual-machines/resize). ## Related [#related] - [Virtual machines](/en/docs/cloud/virtual-machines) - [Capabilities](/en/docs/cloud/capabilities) – storage architecture and planned additional VM disks. # Add SSH keys to a running VM (/en/docs/cloud/virtual-machines/add-ssh-keys) Add keys from Settings → SSH keys to a running Linux VM. They are added to `~/.ssh/authorized_keys` of the VM user, the one set at create or reinstall, and work right away. ## Before you begin [#before-you-begin] - The VM is running. - `qemu-guest-agent` runs on the VM. It is installed on hostd images. If you removed it, install it again or add the key over SSH yourself. ## Steps [#steps] 1. Open the VM and go to `SSH keys`. 2. Select the keys to add, or add a new one with `+`, and click Add. 3. Confirm it is you: enter the code from your authenticator app, or the code we send to your email if two-factor authentication is off. The confirmation lasts 15 minutes, so you can add keys to other VMs in that time without a new code. The page shows the user that received the keys. ## Watch out [#watch-out] - Keys are only appended, nothing is removed. To remove a key, edit `~/.ssh/authorized_keys` on the VM. - A reinstall sets only the keys selected in the reinstall form. - In [rescue mode](/en/docs/cloud/virtual-machines/rescue) the keys go to the temporary system and disappear when you disable it. Use this to sign in and fix `~/.ssh/authorized_keys` on the system disk. # VM backups and restore (/en/docs/cloud/virtual-machines/backups-restore) Run a backup of a VM now or restore a full VM from a selected PBS backup. ## Run a backup now [#run-a-backup-now] Open `VM → Backups`, click **Backup now** and confirm. Up to 2 backups can be started per VM in 24 hours, and not while another backup of this VM is running. The backup runs as your user and appears in `Datacenter → Tasks`. Old backups are removed only by the retention of a backup job that includes this VM; without a job, backups are kept and billed until the VM is deleted. ## Before you begin [#before-you-begin] - VM must be **stopped** before restore. - A backup copy exists on `VM → Backups`. ## Steps [#steps] 1. Stop the VM. 2. Open `VM → Backups`. 3. Select a backup and click **Restore**. 4. Choose the start-after-restore option if available and needed. 5. After completion, verify the VM and applications. ## Watch out [#watch-out] - Restore requires a stopped VM. - HA VMs: turn off autostart for restore – restore will not start with autostart enabled. Start the VM manually after completion. - To download individual files from a backup, use **Backup → Datastore**. - Backups cannot be deleted manually: they are removed by the retention of the backup job or together with the VM. # SSH and console (/en/docs/cloud/virtual-machines/connect-console) To manage your virtual machine, you can connect to it over the network via SSH (primary method) or use the noVNC web console built into the portal (emergency method if the network is unavailable). ![noVNC console](/docs/vm-console-novnc.png) ## Before you begin [#before-you-begin] - The virtual machine must be in the **running** state. - Make sure you remember the username you specified during the VM creation or reinstallation. - If connecting via SSH over the internet (WAN): the machine must have a public IP address, and you must have the corresponding private SSH key configured on your computer. ## Connection methods [#connection-methods] ### 1. Connecting via SSH (Recommended) [#1-connecting-via-ssh-recommended] Open a terminal on your computer and execute the connection command (if your private key is saved in the default path `~/.ssh/id_rsa` or `~/.ssh/id_ed25519`, the `-i` parameter is not required): ```bash ssh username@public_ip ``` If you are using a key with a custom name or path: ```bash ssh -i ~/.ssh/id_rsa username@public_ip ``` ### 2. Connecting via noVNC web console [#2-connecting-via-novnc-web-console] If the network is disabled on the machine, ports are blocked, or you are experiencing issues with SSH key configuration: 1. Go to your VM settings and open the `VM → Console` tab (or click the **Open Console in New Window** button). 2. Log into the system by entering your username and the password you specified during VM creation or system reinstallation. ## Watch out [#watch-out] On all our standard Linux images, SSH password authentication is disabled by default. If you try to connect via SSH using a password, you will receive an access error (Permission denied). To enable password login, please refer to our [dedicated guide](/en/docs/cloud/virtual-machines/ssh-password-login). # Create a VM (/en/docs/cloud/virtual-machines/create) Creating a Linux VM: image, CPU class, resources, SSH keys, and networking. ![Create a VM – form with image, SSH key, and WAN](/docs/vm-create-form.png) ## Before you begin [#before-you-begin] - Access to the project with Admin or Superadmin role. ## Steps [#steps] 1. Open the project and click **Create VM**. 2. Choose an image, hostname, and username, and set a password. We do not store passwords – you cannot view it in the portal later. 3. Set **CPU class** (Regular or Light), vCPU, RAM, and OS disk size. 4. Add SSH keys. 5. Choose networking: public WAN mode (**Off**, **IPv4**, **IPv6**, or **IPv4 + IPv6**), a private network LAN interface, or both. 6. Click **Create** and wait about a minute (initial system setup runs in the background). ## Watch out [#watch-out] - On all Linux images, SSH password login is disabled – only SSH keys work. To enable password SSH, see [SSH password login](/en/docs/cloud/virtual-machines/ssh-password-login). - Minimum vCPU is **2**, step is **2**. RAM ranges from **1×** to **4×** the vCPU count in GiB, in **2 GiB** steps – with 4 vCPU that is 4 to 16 GiB. The OS disk is a range from **10×** to **100×** the vCPU count in GiB, in **20 GiB** steps – with 4 vCPU that is 40 to 400 GiB. - The system disk is limited to **15,000 IOPS** and **500 MB/s** (read and write). See [Storage](/en/docs/cloud/storage). - Public WAN modes: **Off** (no public address), **IPv4**, **IPv6**, or **IPv4 + IPv6**. On an attached VM you can only switch **Off ↔ the same mode**; to change between IPv4 / IPv6 / dual-stack, turn WAN off first. - Hourly **public IP** billing applies to **IPv4 only**. Public IPv6 is included without a separate IP charge. - HA is not enabled at create time; enable it later in `Datacenter → High Availability`. # Delete a VM (/en/docs/cloud/virtual-machines/destroy) Delete a VM. All backups of the VM are deleted with it. You choose what happens to the public IP. ![Destroy VM – public IP option](/docs/vm-destroy.png) ## Before you begin [#before-you-begin] - VM must be **stopped**. - Decision on whether to release or keep the public IP. ## Steps [#steps] 1. Stop the VM. 2. Open `VM → Destroy`. 3. Choose whether to **release** the public IP or **keep it reserved** in the project. 4. Confirm delete. 5. Enter the code from your authenticator app, or the code we send to your email if two-factor authentication is off. The confirmation lasts 15 minutes. ## Watch out [#watch-out] All backups of the VM are permanently deleted with it and cannot be restored afterwards. A kept floating IP continues to bill, but you can attach it to another VM or gateway later. # Firewall and security groups (/en/docs/cloud/virtual-machines/firewall-security-groups) On VM WAN you add your own firewall rules or insert security groups created under `Network → Security groups`. ![Create firewall rule – modal](/docs/vm-firewall-rule-modal.png) ## Before you begin [#before-you-begin] - VM with a WAN (`net0`) interface. - Admin or Superadmin access to the project. ## Steps – rule on the VM [#steps--rule-on-the-vm] 1. Open `VM → Firewall`. 2. Set **Global Status** to **On**, **Policy In** to **DROP**, and click **Apply** if the firewall is off. 3. Click **Add rule**. 4. Fill in the **Create firewall rule** dialog (see below) and click **Add**. 5. Check rule order in the table – within each direction, rules apply top to bottom. ### Fields in **Create firewall rule** [#fields-in-create-firewall-rule] - **Type** – **IN** (traffic to the VM) or **OUT** (traffic from the VM). - **Action** – **ACCEPT** (allow) or **DROP** (deny). - **Protocol** – **TCP**, **UDP**, or **ICMP**. - **Source Address** – sender address or CIDR; active for **IN**, greyed out for **OUT**. - **Destination Address** – recipient address or CIDR; active for **OUT**, greyed out for **IN**. - **Source Port** – source port (e.g. `80`, `80:85`, `80,443`); usually empty for **IN**, fill in for **OUT**. - **Destination Port** – destination port; fill in for **IN** (e.g. `22` for SSH), usually empty for **OUT**. - **Comment** – optional note. - **Enabled** – disabled rules stay in the list but are not applied. ## Security groups [#security-groups] ![Insert Security Group on VM Firewall](/docs/vm-firewall-insert-group.png) To reuse the same rules on many VMs, create a security group under [Security groups](/en/docs/cloud/networking/security-groups), then on the VM firewall click **Insert Security Group** and choose the group. ## Watch out [#watch-out] - Portal VM firewall applies to WAN (`net0`) only. LAN interfaces are not filtered by this firewall. - CIDR in rules is limited to **/26** for IPv4 and **/64** for IPv6. - Outbound SMTP (ports 25 / 465 / 587) is blocked at the network edge by default, independent of these rules – see [Outbound email (SMTP)](/en/docs/cloud/virtual-machines/outbound-email). # Virtual machines (/en/docs/cloud/virtual-machines) Links to VM lifecycle guides: create, connect, resize, reinstall, rescue, password reset, backups, and delete. Image, username, CPU mode, resources, SSH keys, WAN/LAN. When to use SSH and when to use noVNC. Enable SSH password login on Linux. CPU/RAM/disk/NIC and downgrade limits. Reinstall the OS from an image. Boot a temporary copy of the OS. The system disk stays attached. Set a new password on the system disk from rescue mode. One fast rollback point. Restore a selected backup. Backups and floating IP during delete. WAN rules and security groups. ## Watch out [#watch-out] A powered-off VM no longer bills CPU and RAM, but disk, floating IPs, backups, and other active project resources still bill. # Outbound email (SMTP) (/en/docs/cloud/virtual-machines/outbound-email) Outbound connections to port **25** from instances and Cloud Gateways are **blocked by default** at the hostd network edge. This applies even when Proxmox VM firewall rules allow the traffic. Ports **587** and **465** are open. Sending through a mail provider (Google Workspace, Microsoft 365, Amazon SES, SendGrid, Mailgun and similar) works without a request. We do this to protect the reputation of our IP ranges. ## When you need an unlock [#when-you-need-an-unlock] Only when the instance delivers mail to recipients' mail servers itself, for example your own Postfix or Exim server sending to the internet. ## Status in the portal [#status-in-the-portal] - **VM → Firewall** shows whether outbound email is blocked for that instance. - A private network with a Cloud Gateway shows the same notice on its page. ## Request an unlock [#request-an-unlock] 1. Open **VM → Firewall**, or the private network page for a Cloud Gateway. 2. Use **Request unlock**. 3. Choose the purpose and enter the sending domain(s). 4. Submit – a support ticket is created. You can follow it under **Support**. We review the request (typical checks: legitimate use, domains, account history). After approval, port 25 is opened for the public IP(s) of the instance or gateway. ## Watch out [#watch-out] - The unlock belongs to the public IP. A newly attached or newly reserved address starts blocked, and an address released back to the pool loses its unlock. - Guest or Proxmox firewall rules alone cannot open port 25 while the edge block is in place. - Configure SPF, DKIM, and DMARC for domains you send from. # Reinstall a VM (/en/docs/cloud/virtual-machines/reinstall) Wipe the system disk and reinstall the OS from a portal image. CPU, RAM, OS disk size, network interfaces, and their MAC addresses stay unchanged. ![VM Reinstall – OS image, credentials, and SSH keys](/docs/vm-reinstall.png) ## Before you begin [#before-you-begin] - VM must be **stopped**. - If the system disk has data you need to keep, make sure backups exist in `VM → Backups`. ## Steps [#steps] 1. Stop the VM. 2. Open `VM → Reinstall`. 3. Choose an OS image, hostname, and username, and set a password. We do not store passwords – you cannot view it in the portal later. 4. Add SSH keys. 5. Run reinstall and optionally start the VM after completion. 6. Enter the code from your authenticator app, or the code we send to your email if two-factor authentication is off. The confirmation lasts 15 minutes. ## Watch out [#watch-out] - Reinstall deletes all data on the system disk. - Reinstall removes the VM snapshot if one exists. # Rescue mode (/en/docs/cloud/virtual-machines/rescue) Rescue mode starts a stopped Linux VM from a temporary disk copied from the same OS image. You get a shell where the system disk is still attached, so you can repair it without reinstalling. ## Before you begin [#before-you-begin] - The VM runs Linux. - The VM is stopped. - High availability is off. - You can sign in with the SSH keys already on the VM, or with the console password. - `VM → Rescue` shows the user to sign in as. That is the cloud-init user on this VM. ## What rescue mode changes [#what-rescue-mode-changes] The VM boots a fresh copy of its OS image. That copy is a separate disk, about 10 GB, on the same storage as the system disk. The system disk stays attached. Files on it are not rewritten. Network settings, the firewall, and the SSH keys stay as they are. The password in the enable form is for the console of this temporary system. It does not replace the password on the system disk. `passwd` run in the rescue shell changes only the temporary system, and that password is gone when you leave rescue mode. To set the password the VM will use after you leave rescue mode, mount the system disk and change it there: [Reset the VM password](/en/docs/cloud/virtual-machines/reset-password). ## Enable [#enable] 1. Stop the VM. 2. Open `VM → Rescue`. 3. Optionally set a console password for the temporary system. Leave it off to keep the current console password. 4. Enable rescue mode and enter the code from your authenticator app, or the code we send to your email if two-factor authentication is off. The VM starts from the temporary disk. Sign in as the user shown on the page, with an SSH key or through `VM → Console`. ## Disable [#disable] 1. Stop the VM. 2. Open `VM → Rescue`. 3. Disable rescue mode. The temporary disk is removed and the VM starts from the system disk. ## Watch out [#watch-out] - While rescue mode is on, resize, reinstall, and snapshots are unavailable, and high availability cannot be turned on. Destroy still deletes the VM. - The temporary disk is billed until you disable rescue mode. - Anything you change on the temporary system, including its password and installed packages, disappears with that disk. # Reset the VM password (/en/docs/cloud/virtual-machines/reset-password) Set a new password on the system disk of a Linux VM. The VM must already be in [rescue mode](/en/docs/cloud/virtual-machines/rescue). The password from the rescue enable form, and any `passwd` you run in the rescue shell, apply only to the temporary system. That disk is removed when you disable rescue mode, so those passwords do not come back with the VM. The password you set below is written on the system disk and is the one the VM uses after it boots normally. ## Before you begin [#before-you-begin] - Rescue mode is on and you are signed in with an SSH key or through `VM → Console`. - The user is the one shown on `VM → Rescue`. ## Steps [#steps] 1. List the disks: ```bash lsblk -o NAME,SIZE,SERIAL,FSTYPE,MOUNTPOINT ``` The disk whose `SERIAL` is `rescue` is the temporary system, mounted at `/`. The other disk is the system disk. On hostd images the root filesystem is the first partition of the system disk, usually `vda1`. 2. Mount that partition and change the password. Replace `vda1` with the partition from your `lsblk`, and `debian` with the VM user. ```bash sudo mkdir -p /mnt/system sudo mount /dev/vda1 /mnt/system sudo mount --bind /dev /mnt/system/dev sudo mount --bind /proc /mnt/system/proc sudo mount --bind /sys /mnt/system/sys sudo chroot /mnt/system passwd debian sudo umount -R /mnt/system ``` `passwd` asks for the new password twice. The command has to run through `chroot`. `passwd` without it changes only the temporary system, and that password is gone when you leave rescue mode. 3. Power off the VM: `sudo poweroff`. 4. Open `VM → Rescue` and disable rescue mode. The VM boots from the system disk with the new password. ## Watch out [#watch-out] SSH password login is off on hostd images. The new password works on the console. To allow it over SSH as well, turn that on separately: [Enable SSH password login](/en/docs/cloud/virtual-machines/ssh-password-login). # Resize a VM (/en/docs/cloud/virtual-machines/resize) Change CPU class, vCPU, RAM, disk size, and network interfaces. ![VM Resize – CPU class, vCPU, RAM, and networking](/docs/vm-resize-overview.png) ## Before you begin [#before-you-begin] - Admin or Superadmin access to the project. - While the VM is **running**, you can increase vCPU, RAM, and OS disk, change **CPU class**, and edit WAN/LAN interfaces. - To lower CPU or RAM: VM must be **stopped**. ## Steps [#steps] 1. Open `VM → Resize`. 2. Change **CPU class**, vCPU, and RAM within the allowed ranges. 3. Grow the OS disk if you need more space. 4. Change WAN or private NICs and review the access impact. To change the public IP: turn WAN off, save, turn WAN on again, and choose **Auto** or a reserved address (no VM reboot). 5. Click **Save**. ## Watch out [#watch-out] - You can lower vCPU, RAM, or **CPU class** **24 hours** after you create the VM or increase those resources. Lowering vCPU/RAM also needs a stopped VM. - OS disk can only grow; it cannot shrink. - Disk size sets a floor for vCPU: one core carries at most **100 GiB**, so a 400 GiB disk keeps the VM at 4 vCPU or more. - **CPU class** can be changed while the VM is running. # Snapshots (/en/docs/cloud/virtual-machines/snapshots) Create one user snapshot per VM and roll back if needed. ## Before you begin [#before-you-begin] - Admin or Superadmin access to the VM. - No existing snapshot on the VM – you can have only **one**. ## Steps [#steps] 1. Open `VM → Snapshots`. 2. Click **Create snapshot** before changing the system. 3. After testing, delete the snapshot or use **Rollback** if the change failed. ## Watch out [#watch-out] A snapshot is not a backup. You can have only one snapshot per VM. # Enable SSH password login (/en/docs/cloud/virtual-machines/ssh-password-login) On Linux images, hostd disables SSH password login by default. This guide explains how to turn it on manually in the guest OS. ## Before you begin [#before-you-begin] - VM in **running** state. - Access to the VM by SSH key or [noVNC console](/en/docs/cloud/virtual-machines/connect-console). - VM user password from [create](/en/docs/cloud/virtual-machines/create) or [reinstall](/en/docs/cloud/virtual-machines/reinstall). ## Steps [#steps] 1. Sign in to the VM by SSH key or `VM → Console`. 2. Create `/etc/ssh/sshd_config.d/99-password-auth.conf` with the line `PasswordAuthentication yes`. 3. Restart SSH: `systemctl restart ssh` (Debian, Ubuntu) or `systemctl restart sshd` (AlmaLinux, Rocky Linux, Fedora). 4. Connect by SSH with the VM user password. ## Watch out [#watch-out] - Password login is less secure than SSH keys – enable it only if you really need it. - After [reinstall](/en/docs/cloud/virtual-machines/reinstall), initial system setup disables SSH password login again – repeat these steps if you still need password SSH. - If SSH does not respond, check the [VM firewall](/en/docs/cloud/virtual-machines/firewall-security-groups) and the guest OS firewall. # MCP server (/en/docs/mcp) The hostd MCP server lets an AI agent work with your Public Cloud on your behalf: list projects and OS images, add SSH keys, create and manage VMs, configure the firewall, backups, and high availability, and set PTR records. It uses the same [API](/en/docs/api) and the same API key. Endpoint: `https://mcp.hostd.cloud/mcp` (Streamable HTTP). ## Connect [#connect] Create an API key in the portal under [Settings → API Keys](https://hostd.cloud/app/settings/api-keys). A separate key for the agent is a good default: you can delete it at any time without affecting your other integrations. **Cursor** – add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project): ```json { "mcpServers": { "hostd": { "url": "https://mcp.hostd.cloud/mcp", "headers": { "Authorization": "Bearer " } } } } ``` **Claude Code:** ```bash claude mcp add --transport http hostd https://mcp.hostd.cloud/mcp \ --header "Authorization: Bearer " ``` ## Access [#access] The agent works with your API key, so it has the same access as the key: for each project **Read**, **Write** (everything except deleting), or **Full** (also deletes VMs, the project, and public IPs), plus the SSH key access you chose, never above your role in a project ([details](/en/docs/api#authentication)). Projects outside the key's access are hidden from the agent; with Read it can only read. Deleting a VM (together with all its backups) needs Full. Before risky actions – deleting a VM, reinstalling, rescue mode, restoring a backup, rolling back a snapshot, resizing, or changing the firewall – the agent shows you what will happen and waits for your approval. ## Example [#example] > In the project web, create a VM named git. Install Docker and run Gitea. On the firewall, allow HTTP and HTTPS from anywhere, and SSH only from the security group management. The agent finds the project, your SSH key, and that security group. It proposes an image and a size that fits Gitea, with the hourly price, and creates the VM only after you agree. It waits until the VM is running, connects over SSH from your computer, and installs Docker and Gitea. hostd never receives the private key. A password you did not choose is stored in the VM notes in the portal and is not printed in the chat. It then allows HTTP and HTTPS, attaches management so SSH follows that group's rules, and asks again before turning the firewall on and dropping every other inbound connection. ## Tools [#tools] Forty-five tools. | Tool | What it does | |------|--------------| | `hostd_list_clusters` | Zones and hourly prices | | `hostd_list_projects` | Projects this key can access | | `hostd_get_project` | One project: its limits and hourly prices | | `hostd_create_project` | Create a project, after you agree; the key must be allowed to create projects | | `hostd_get_account_usage` | Account CPU, RAM, and disk used against the limits | | `hostd_list_os_images` | OS images available for new VMs in a project | | `hostd_list_ssh_keys` | SSH public keys on the account | | `hostd_create_ssh_key` | Add an SSH public key | | `hostd_list_vms` | VMs in a project: status, size, and current load | | `hostd_get_vm` | One VM: status, addresses, notes, and the cloud-init user | | `hostd_get_vm_metrics` | CPU, RAM, network, and disk over an hour, a day, a week, or a month | | `hostd_list_project_tasks` | Recent tasks in a project | | `hostd_create_vm` | Create a VM, after you agree | | `hostd_wait_vm_ready` | Wait until a VM is running and return its addresses | | `hostd_power_vm` | Start, shut down, stop, reboot, or reset | | `hostd_resize_vm` | Change vCPU, RAM, disk, or CPU class, after you agree | | `hostd_reinstall_vm` | Reinstall the OS of a stopped VM, after you agree | | `hostd_enable_rescue` | Boot a stopped Linux VM from a temporary copy of its OS, after you agree. High availability must be off | | `hostd_disable_rescue` | Remove that temporary disk and boot the system disk, after you agree | | `hostd_delete_vm` | Delete a stopped VM and its backups; needs Full, and your agreement | | `hostd_list_vm_snapshots` | The snapshot of a VM | | `hostd_manage_vm_snapshot` | Create, delete, or roll back that snapshot | | `hostd_list_vm_backups` | Backups of a VM | | `hostd_create_vm_backup` | Back up a VM now | | `hostd_restore_vm_backup` | Restore a backup onto a stopped VM, after you agree | | `hostd_list_backup_jobs` | Scheduled backup jobs, and VMs in none | | `hostd_manage_backup_job` | Create, change, or delete a backup job, or add and remove VMs | | `hostd_get_project_ha` | Which VMs have high availability, and the placement rules | | `hostd_set_vm_ha` | Turn high availability on or off for a VM | | `hostd_manage_ha_rule` | Create, change, or delete a placement rule | | `hostd_get_vm_firewall` | A VM's firewall options, rules, and attached groups | | `hostd_set_vm_firewall_options` | Turn the VM firewall on or off and set its policies | | `hostd_manage_vm_firewall_rules` | Add, change, delete, or reorder a VM's firewall rules | | `hostd_list_ip_sets` | IP sets, their members, and where they are used | | `hostd_manage_ip_set` | Create an IP set, change its comment, or delete it | | `hostd_manage_ip_set_members` | Add or remove addresses in an IP set | | `hostd_list_security_groups` | Security groups, their rules, and which VMs use them | | `hostd_manage_security_group` | Create, rename, or delete a security group | | `hostd_manage_security_group_rules` | Add, change, delete, or reorder rules in a security group | | `hostd_list_private_networks` | Private networks, or the free addresses of one of them | | `hostd_create_private_network` | Create a private network, after you agree | | `hostd_manage_vm_network` | Add or remove a private-network interface of a VM, or turn its public network on or off; removing and public-network changes only after you agree | | `hostd_list_public_ips` | Public addresses reserved in the project | | `hostd_update_ptr` | Set the PTR record of a public address | | `hostd_get_current_agent_ip` | The public address this MCP connection comes from | ## Limits [#limits] The MCP server follows the [API limits](/en/docs/api#limits). It also paces the agent: repeated calls wait briefly instead of failing, and the agent gets the retry time when a limit is reached. # Terraform provider (/en/docs/terraform) The hostd Terraform provider manages your Public Cloud as code: projects, SSH keys, virtual machines, and their firewalls. It uses the same [API](/en/docs/api) and the same API key. Provider: [`hostdcloud/hostd`](https://registry.terraform.io/providers/hostdcloud/hostd/latest/docs) in the Terraform Registry, where every resource and argument is documented. ## Connect [#connect] Create an API key in the portal under [Settings → API Keys](https://hostd.cloud/app/settings/api-keys) and export it: ```bash export HOSTD_API_KEY= ``` ```hcl terraform { required_providers { hostd = { source = "hostdcloud/hostd" } } } provider "hostd" {} ``` Terraform checks the key when it starts. An invalid key, or an `api_url` that is not an absolute `http` or `https` address without a path, fails the plan before any resource changes. ## Access [#access] The provider works with your API key, so it has the same access as the key ([details](/en/docs/api#authentication)): - `hostd_ssh_key` needs **Write** access to SSH keys. - `hostd_project` needs a key that is allowed to **create projects**; the key gets **Full** access to the projects it creates. To use an existing project, set its UUID as `project_id`. - `hostd_vm` needs **Write** access to the project; destroying a VM needs **Full**. - `hostd_ip_set` and `hostd_ip_set_member` need **Write** access to the project. Deleting a set also removes firewall rules that reference it. - `hostd_security_group` needs **Write** access to the project. Deleting a group detaches it from every VM. - `hostd_vm_firewall` needs **Write** access to the project. The firewall filters the VM's public interface. A rule with `type = "group"` and `action` set to the group's `pve_group_name` attaches a security group. - `hostd_public_ips` needs **Read**. `hostd_public_ip_ptr` needs **Write** and sets the PTR of an address the project already has. Removing it restores the default hostname and does not release the address. - `hostd_private_networks` and `hostd_ip_addresses` need **Read**. `free_ips` on a private network are the addresses `lan_interfaces` can use with `mode = select`. - Reading state and `hostd_os_images` need **Read**. Use a separate key for each Terraform workspace. Export it as `HOSTD_API_KEY` (a CI secret) and do not put it in the configuration. Prefer a key that expires in 30 or 90 days: create the next key, point the secret at it, then delete the old one. | Command | Minimum access | |---|---| | `terraform plan` | Read on the project and on SSH keys | | `terraform apply` | Write on the project, Write on SSH keys, and allowed to create projects | | `terraform destroy` | Full on the project | ## Example [#example] ```hcl resource "hostd_project" "main" { name = "production" cluster_name = "waw-1" } resource "hostd_ssh_key" "admin" { name = "admin" public_ssh_key = file("~/.ssh/id_ed25519.pub") } data "hostd_os_images" "available" { project_id = hostd_project.main.id } resource "hostd_vm" "web" { project_id = hostd_project.main.id hostname = "web-01" os_image = "debian-12-amd64.qcow2" ssh_key_ids = [hostd_ssh_key.admin.id] cores = 2 ram_gb = 4 os_disk_gb = 20 } resource "hostd_security_group" "web" { project_id = hostd_project.main.id name = "web" rules = [ { type = "in", action = "ACCEPT", proto = "tcp", dport = "80,443" }, { type = "in", action = "ACCEPT", proto = "tcp", dport = "22" }, ] } resource "hostd_vm_firewall" "web" { project_id = hostd_vm.web.project_id vmid = hostd_vm.web.vmid enable = true policy_in = "DROP" policy_out = "ACCEPT" rules = [ { type = "group", action = hostd_security_group.web.pve_group_name }, ] } output "web_ipv4" { value = hostd_vm.web.ipv4 } ``` Image names depend on the cluster: `hostd_os_images` returns the ones available in a project. You sign in to the VM with the SSH keys you attach; the provider sets a random password and does not expose it. ## Resources [#resources] | Name | What it manages | |------|-----------------| | `hostd_project` | A project in a cluster (zone) | | `hostd_ssh_key` | An SSH public key on your account | | `hostd_vm` | A VM: CPU, RAM, disk, CPU class, public and private networks | | `hostd_ip_set` | A named address list for firewall rules | | `hostd_ip_set_member` | One address or network in an IP set | | `hostd_security_group` | A named, ordered list of firewall rules | | `hostd_vm_firewall` | A VM firewall: on or off, default policies, rules and attached security groups | | `hostd_os_images` (data source) | OS images available in a project | | `hostd_public_ips` (data source) | Public addresses reserved on a project | | `hostd_public_ip_ptr` | PTR hostname of a public address | | `hostd_private_networks` (data source) | Private networks in a project, with free addresses | | `hostd_ip_addresses` (data source) | Public addresses on the account | ## Limits [#limits] - The provider follows the [API limits](/en/docs/api#limits): when a limit is reached it waits for the `Retry-After` time and retries. GET requests are also retried on HTTP 5xx and network errors, for up to two minutes. API errors are shown as the message text (`detail`, `error`, or `field: message`). - A VM's CPU or RAM can be lowered only with `power_state` set to `stopped`, and only 24 hours after it was created or last increased. `timeouts` overrides how long create, update, and delete may take. - Switching a VM's public network between `ipv4`, `ipv6`, and `dual` goes through `off`. - Private networks are attached with `lan_interfaces` (`auto` takes a free address, `select` uses a chosen one). Create them in the portal first. With public networking off and more than one network, mark exactly one `is_gateway`. - `rules` on `hostd_security_group` and `hostd_vm_firewall` is the complete ordered list, written in one request. Rules added to that group or VM in the portal are removed on the next apply. Destroying `hostd_vm_firewall` removes the rules and turns the VM firewall off. - Destroying a VM deletes its disks and every backup of that VM. Public addresses return to the pool unless `retain_public_ips` is true (a reserved IPv4 stays billed). `wan_ip` and `wan_ipv6` attach a reserved address. Changing `project_id`, `hostname`, `os_image`, `username`, `wan_ip`, or `wan_ipv6` replaces the VM. For a production VM set `lifecycle { prevent_destroy = true }`. - SSH keys are installed only when a VM is created. Changing `ssh_key_ids` or replacing a `hostd_ssh_key` does not touch the VM; update `authorized_keys` on the VM yourself. - An IP set cannot be renamed: a new `name` replaces the set. - If creating a VM or a project is interrupted, the provider keeps a VM with the same hostname, or a project with the same name in the same cluster, that appeared during that call, instead of creating another. A VM or project that existed before is never taken over.