Virtual Machines API ​

Overview ​

The Virtual Machines API allows you to manage your Swiftor VMs, including creation, deletion, and state management (starting/stopping).

Endpoints ​

List VMs (GET /vms) ​

Returns a list of all VMs owned by the authenticated user.

Response ​

{
  "vms": [
    {
      "id": "1aa62e52-e61c-4ae3-9ac2-c9cb1f46d25f",
      "vmlabel": "NewVM",
      "region": "AU",
      "os": {
        "distribution": "ubuntu",
        "desktop": "xfce"
      },
      "specs": {
        "cpu": 2,
        "ram": 4,
        "storage": true
      },
      "enabled": false // Indicates if the VM is currently running or stopped
    }
    // ... other VMs
  ]
}

Create VM (POST /vms/create) ​

Creates a new virtual machine record in the database with the specified configuration.

Note: The VM is created in a stopped state (enabled: false) and is not started automatically. Use the Start VM endpoint to activate it.

Request Body ​

{
  "config": {
    "vmlabel": "MyWebServer",
    "region": { "code": "AU" },
    "password": "your-secure-password",
    "storageType": "persistent"
  },
  "os": {
    "distribution": { "code": "ubuntu" },
    "desktop": "xfce",
    "cpu": 2,
    "ram": 4
  }
}

Parameters ​

• config.vmlabel (string, required): A user-friendly name for the VM.
• config.region.code (string, required): The region code (e.g., "AU", "US").
• config.password (string, required): The password for the default VM user. This will be stored securely as a VM_PASSWORD secret associated with the VM.
• config.storageType (string, optional): Set to "persistent" to enable persistent storage for the VM's primary volume (usually /config). If omitted or different, storage will be ephemeral. When persistent storage is enabled, the necessary host directory structure is created upon VM creation.
• os.distribution.code (string, required): The Linux distribution identifier. See the table below for available options.
• os.desktop (string, optional): The desktop environment for webtop-based images (e.g., "kde", "xfce"). Required if distribution is a webtop base like "ubuntu", "debian", "fedora".
• os.cpu (integer, required): The number of vCPU cores allocated.
• os.ram (integer, required): The amount of RAM in GB allocated.

Available VM Images (os.distribution.code) ​

The following image types are available. Base Webtop images require specifying an os.desktop environment (e.g., kde, xfce).

Response (Success - 201 Created) ​

Returns the newly created VM object, reflecting its initial configuration and state (enabled: false).

{
  "message": "VM created successfully",
  "vm": {
    "id": "generated-uuid-4",
    "user_id": "user-supabase-id",
    "vmlabel": "MyWebServer",
    "region": "AU",
    "os": {
      "distribution": "ubuntu",
      "desktop": "xfce"
    },
    "specs": {
      "cpu": 2,
      "ram": 4,
      "storage": true // True because storageType was "persistent"
    },
    "enabled": false
  }
}

Start VM (GET /vms/start/{vmid}) ​

Initiates the startup process for a stopped virtual machine specified by its vmid.

Behavior Notes ​

• Resource Checks: Before starting, the API verifies:
  • If the user is within their subscription plan's concurrent VM limit.
  • If starting this VM would exceed the plan's total vCPU or RAM allocation. An error (e.g., 400 Bad Request) is returned if these checks fail.
• Asynchronous Operation: This endpoint starts the VM deployment in the background. The VM's status is marked as enabled: true in the database immediately, but the actual provisioning and boot-up may take several moments.
• Success Response: The API returns a success message indicating the process has started, not that the VM is fully booted and operational.
• Check Status: Monitor the VM's status via the GET /vms endpoint or the Swiftor dashboard to confirm when it's fully running.

Response (Success) ​

{
  "message": "VM start process initiated successfully in the background."
}

Stop VM (GET /vms/stop/{vmid}) ​

Gracefully stops a running virtual machine specified by its vmid. The VM's status will be updated to enabled: false.

Delete VM (GET /vms/delete/{vmid}) ​

Permanently deletes a virtual machine and its associated storage (if persistent).

Secrets API (/vms/secrets) ​

Manage environment variables for your VMs. These secrets are injected into the running container.

List Secrets (GET /vms/secrets) ​

Retrieves all secrets defined for the authenticated user's VMs.

Response ​

Returns an object where keys are VM IDs and values are objects containing the key-value pairs of secrets for that VM.

{
  "secrets": {
    "1aa62e52-e61c-4ae3-9ac2-c9cb1f46d25f": {
      "API_KEY": "your-api-key-value",
      "DATABASE_URL": "your-db-url"
    },
    "another-vm-id": {
      "SECRET_TOKEN": "another-secret-value"
    }
  }
}

Add/Update Secret (POST /vms/secrets) ​

Adds a new secret or updates the value of an existing secret for a VM.

Request Body ​

{
  "vmid": "1aa62e52-e61c-4ae3-9ac2-c9cb1f46d25f",
  "key": "NEW_SECRET_KEY",
  "value": "its-secret-value"
}

• vmid (string): The ID of the target VM.
• key (string): The name of the environment variable.
• value (string): The value of the environment variable.

Behavior Notes ​

• Persistence: The secret is saved persistently in the database.
• Live Update: If the target VM is running, an asynchronous background task updates the Docker service with the new environment variable (--env-add). The secret will be applied immediately or when the VM (re)starts.

Response (Success - 201 Created) ​

{
  "message": "Secret added successfully",
  "vmid": "1aa62e52-e61c-4ae3-9ac2-c9cb1f46d25f",
  "key": "NEW_SECRET_KEY"
}

Remove Secret (DELETE /vms/secrets/{vmid}/{key}) ​

Removes an existing secret from a VM.

• Path Parameters:
  • {vmid}: The ID of the VM.
  • {key}: The key (name) of the secret to remove.

Behavior Notes ​

• Persistence: The secret is removed from the database.
• Live Update: If the target VM is running, an asynchronous background task updates the Docker service to remove the environment variable (--env-rm). The removal takes effect immediately or upon VM restart.

Response (Success) ​

{
  "message": "Secret removed successfully",
  "vmid": "1aa62e52-e61c-4ae3-9ac2-c9cb1f46d25f",
  "key": "NEW_SECRET_KEY"
}

Networking API (/vms/networking) ​

Manage subdomain mappings to expose specific ports within your VMs via https://{name}-{vmid}.swiftor.io.

List Network Mappings (GET /vms/networking) ​

Retrieves all active subdomain mappings for the authenticated user's VMs.

Response ​

Returns an object where keys are VM IDs and values are objects containing the mappings for that VM. Each mapping key is the chosen name (subdomain prefix).

{
  "networking": {
    "1aa62e52-e61c-4ae3-9ac2-c9cb1f46d25f": {
      "myapp": {
        "subdomain": "myapp", // The chosen name
        "internal_port": 5001
      },
      "api": {
        "subdomain": "api",
        "internal_port": 8080
      }
    },
    "another-vm-id": {
      "web": {
        "subdomain": "web",
        "internal_port": 3000
      }
    }
  }
}

Add Network Mapping (POST /vms/networking) ​

Creates a new subdomain mapping for a VM.

Request Body ​

{
  "vmid": "1aa62e52-e61c-4ae3-9ac2-c9cb1f46d25f",
  "name": "myapp",
  "internal_port": 5001
}

• vmid (string): The ID of the target VM.
• name (string): The desired subdomain prefix. The final URL will be https://{name}-{vmid}.swiftor.io.
• internal_port (integer): The port number inside the VM container that the subdomain should point to.

Behavior Notes ​

• Persistence: The mapping is saved persistently in the database.
• Live Update: If the target VM is running, the underlying Docker service is updated immediately to apply the new Traefik routing rules. If the VM is stopped, the mapping is applied when the VM starts.

Response (Success - 201 Created) ​

{
  "message": "Subdomain mapping added successfully", // Or similar message if VM is stopped
  "subdomain": "myapp.1aa62e52-e61c-4ae3-9ac2-c9cb1f46d25f.swiftor.io",
  "internal_port": 5001
}

Remove Network Mapping (DELETE /vms/networking/{vmid}/{name}) ​

Removes an existing subdomain mapping.

• Path Parameters:
  • {vmid}: The ID of the VM.
  • {name}: The name (subdomain prefix) of the mapping to remove.

Behavior Notes ​

• Persistence: The mapping is removed from the database.
• Live Update: If the target VM is running, the underlying Docker service is updated immediately to remove the Traefik routing rules. The removal is effective regardless of the VM's state.

Response (Success) ​

{
  "message": "Subdomain mapping removed successfully",
  "vmid": "1aa62e52-e61c-4ae3-9ac2-c9cb1f46d25f",
  "name": "myapp"
}