# Virtual Providers | Cycle.io

Canonical URL: https://cycle.io/docs/portal/virtual-providers

## Virtual Providers.

Users can add and remove virtual providers through the portal through the hub integrations form. To get there:

-   Click on Hub from the main, left-hand navigation
-   Select Integrations
-   From the list of providers select **Virtual Provider**
    
    ##### Beta Access
    
    At this time the virtual providers feature is in open beta. While it has been in closed beta for a few months and has been stable, caution is advised for the most important of workloads.
    

Have a question, request, or want to see what others are doing with virtual providers? Head over to the [Cycle Community](https://cycle.io/community)!

### Add a Virtual Provider

After navigating to the hub integrations and selecting the virtual provider option, use the button **Add Integration** to open the virtual providers create form.

![virtual provider create form](https://cycle.io/_cdn/docs-50b0080f-vp-create-1001x689-webp.webp)

| Field | Description |
| --- | --- |
| **name** | A name for the virtual provider, each hub supports 1 or more. |
| **vendor** | This value is fixed to virtual-provider and the value is used by the platform. |
| **identifier** | An identifier for the virtual provider. See [platform docs](https://cycle.io/docs/platform/resource-ids-and-identifiers) |
| **location code** | Code representing the location of the nodes planned to be used with this virtual provider. |

Once the fields are filled out, submit to create the virtual provider.

### Adding a Server from a Virtual Provider

There are two additional steps after uploading the ISO to the virtual provider server:

1.  Remove from quarantine and restart.
2.  Add to a specific cluster

When the virtual provider server checks in with the Cycle hub for the first time it is put in quarantine. Remove the server from quarantine by finding it on the servers page under infrastructure and then add the server to the desired cluster and it will be ready for use.

##### Dynamic Memory

Servers created through virtual providers will not support using dynamic memory on the host hypervisor.

#### Virtual Providers and Public IPs

IP's cannot be requested and assigned to load balancers on virtual provider servers unless the user adds [IP pools](https://cycle.io/docs/portal/managing-ips#managing-ips-for-virtual-providers) for the server to use.

### Managing a Virtual Provider

Managing a virtual provider is done through the row entry on the virtual providers integration page for the hub.

#### Update Virtual Provider

Users can update the information associated with a given virtual provider by selecting a created virtual provider opening the edit form and then submitting changes via the **Update** button.

![virtual provider edit form](https://cycle.io/_cdn/docs-12ada2fb-vp-update-570x389-webp.webp)

#### Delete Virtual Provider

If a virtual provider needs to be deleted, select the trash can icon on the virtual provider entry and click it.

### Creating an ISO

In order to join a server into a [cluster](https://cycle.io/docs/platform/clusters) in the hub, an ISO must be created and then made available to the joining server so that it can be used on boot. This is most practically achieved by burning the ISO to a thumb drive but can also be served via technology like iPXE.

To create a new ISO associated with a virtual provider open the ISO create form by pressing the **+** button next to the ISO's tile.

Below is an image outlining custom iPXE if needed. iPXE is NOT required for the ISO to boot and the iPXE section can be skipped completely if using a thumb drive.

![custom iPXE options](https://cycle.io/_cdn/docs-4606d2d0-vp-custom-ipxe-997x915-webp.webp)

The two required fields on this page of the form are **name** and **token** and they are in the initialization section

##### Changes to ISO

After creating the ISO, most fields can be changed through an update to the ISO. If an update is made to the ISO the ISO needs to be re-downloaded and either burned to the thumb again or added to your iPXE solution.

#### Initialization Options

| Field | Description |
| --- | --- |
| **name** | A name for the given ISO. |
| **token** | Generated by the platform and used for authentication. |

#### iPXE Option Definitions

##### Using DHCP

| Field | Description |
| --- | --- |
| **VLAN ID** | VLAN ID for the IPXE boot. |
| **Network Interface** | Network interface for the IPXE boot. |

##### Using Static

| Field | Description |
| --- | --- |
| **VLAN ID** | VLAN ID for the IPXE boot. |
| **Network Interface** | Network interface for the IPXE boot. |
| **Static IP** | Static IP assigned to the IPXE boot. |
| **Netmask** | Netmask assigned to the IPXE boot. |
| **Gateway IP** | Gateway IP assigned to the IPXE boot. |
| **DNS IP** | DNS IP assigned to the IPXE boot. |

Moving to page 2 of the form there are options for the server, NIC, and bonds.

#### Server

| Field | Description |
| --- | --- |
| **SDN Neighbor Preference** | A preference for SDN neighbors which can be set to IPv4, IPv6, or not set and uses current platform default. |
| **Conditionally Format Storage** | If this option is enabled, on first boot the storage drives of the underlying server are wiped. |
| RAID Preference | Determines how Cycle configures RAID on the server's storage drives. Defaults to "Allow platform to decide." The preference is only applied when Cycle formats the drives, so changing it on an existing server requires Conditionally Format Storage. See RAID modes below. |

![screenshot of the portal ISO server options](https://cycle.io/_cdn/iso-server-options-1752x462-webp.webp)

##### RAID Preference Options

Cycle groups a server's drives by size and builds one RAID array from each group of same-size drives. A group must have an even number of drives; if it has an odd number, none of its drives are put into RAID. The RAID preference sets the RAID level for each array.

| Mode | Description |
| --- | --- |
| **Allow platform to decide** | Default. Uses the same layout as native providers: RAID1 for 2 drives, RAID10 for 4–20 drives. |
| **Disable RAID** | Each drive is used on its own, with no RAID. |
| **Max Storage** | RAID0. Usable capacity is the total of all the drives, but there is no fault tolerance: if one drive fails, the array is lost. |
| **Max Redundancy** | RAID1. Every drive holds a full copy of the data, so usable capacity equals a single drive. |
| **Balanced** | RAID1 for 2 drives, RAID10 for 4–20 drives. Half the total capacity is usable, and the array survives one drive failure in each mirrored pair. |

##### Drives of Different Sizes

With Balanced, when a server has groups of drives in different sizes, the array built from the smaller drives holds the base volume, image storage, and container and VM volumes under 5GB. The array built from the larger drives becomes pool storage.

##### Format Storage

The format storage option will check to see if there's no cycle LVM volume group. If there is not, it will format the disk. This action cannot be reverted.

#### Server Network Interfaces

Optionally configure server NIC's.

| Field | Description |
| --- | --- |
| **Match** | Interface name or Mac address for the NIC. |
| **VLAN ID** | VLAN ID for the server. |
| **DHCP Config** | DHCP mode. |
| **Static IP** | Static IP assigned to the server. |
| **Network CIDR** | Network CIDR assigned to the server. |
| **Gateway IP** | An IP address is a numerical label that uniquely identifies a device on a network and enables it to send and receive data. |
| **L2 Config** | L2 options for private, public, or shared. |

#### Server Network bonds

Create a bonded (a.k.a. teamed) network interface, which aggregates two or more physical NICs into one logical interface for improved performance, redundancy, or load balancing.

![virtual provider iso server bonds customization](https://cycle.io/_cdn/docs-dd76b58b-vp-iso-server-bonds-977x498-webp.webp)

| Field | Description |
| --- | --- |
| **Interface Name** | Name of the bonded (virtual) interface, e.g., `bond0`. |
| **Mode** | Bonding mode strategy, see below. |
| **Interface 1** | Name of the first physical network interface or Mac address to include in the bond. |
| **Interface 2** | Name of the second physical network interface or Mac address to include in the bond. |
| **\+ Add Bond Interface** | Adds additional physical interfaces to the bond. |

##### Mode

| Mode | Description |
| --- | --- |
| **Round Robin** | Sends packets in sequential order across all interfaces. Simple load balancing. |
| **Active-Backup** | One link is active at a time. Fails over to a backup if the active link goes down. |
| **XOR Load Balancing** | Uses a hash of MAC/IP/port to consistently choose one interface per traffic flow. |
| **LACP** | IEEE 802.3ad dynamic link aggregation. Requires switch support. Balances load and adds failover. |
| **Transmit Load Balancing (TLB)** | Load balances outbound traffic adaptively; **no switch configuration required**. |
| **Adaptive Load Balancing (ALB)** | Adds **receive-side balancing** on top of TLB; **no switch configuration required**. |

#### Review

Once all desired fields are set, a review page is shown confirming all selections. If the selections are confirmed, use the **Create ISO** button.

### Generate and Download the ISO

Creating the ISO saves its configuration. To get a bootable file, choose **Generate**. When it finishes, the button changes to **Download**. The file is small because it only carries iPXE and your provider token. The server pulls everything else over the network, so it needs ethernet on first boot.

You can serve the ISO over iPXE or write it to a USB drive. The rest of this section covers the USB path.

### Write the ISO to a USB Drive

Writing the ISO erases the drive. Use one you don't need, 2 GB or larger, and double-check the device name before running `dd`. It will overwrite the wrong disk without asking.

#### macOS

Run `diskutil list` and note the identifier of the entry marked `external, physical`. Replace `disk4` below with yours.

```bash
cd ~/Downloads
diskutil unmountDisk /dev/<diskN>
sudo dd if=<ipxe-xxxx.iso> of=/dev/r<diskN> bs=4m status=progress
diskutil eject /dev/<diskN>
```

If macOS reports the disk is not readable afterward, choose **Ignore**.

#### Linux

Run `lsblk -o NAME,SIZE,TRAN` and note the device marked `usb`. Use the whole device, not a partition. Replace `sdb` below with yours.

```bash
sudo umount /dev/<sdX>?* 2>/dev/null
sudo dd if=<ipxe-xxxx.iso> of=/dev/<sdX> bs=4M status=progress conv=fsync
```

#### Windows

Use [Rufus](https://rufus.ie/). Pick the drive under **Device**, select the ISO under **Boot selection**, and choose **START**. If asked, pick **Write in DD Image mode**.

### Boot the Server

Plug in the drive, connect the ethernet, and power on.

The server loads iPXE, fetches its configuration with the token in the ISO, and checks in with your hub. Within a few minutes it appears under **Infrastructure → Servers** in quarantine.

#### USB Storage Drives

USB storage drives can add disk space to a virtual provider server. Whether Cycle manages a drive depends on its size and on when it's connected:

-   **Managed by Cycle:** The drive is larger than 100 GB and is connected when the server first boots. Cycle manages its storage automatically.
-   **Not managed:** To use a drive without Cycle managing it, connect it after the server's first boot.
-   **Ignored:** Cycle treats USB drives smaller than 100 GB as thumb drives and ignores them.

### Managing ISOs

To change an ISO after creating it, choose the pencil icon next to it. Edits open in a modal.

---

## Getting a Cycle account (for AI agents)

Cycle is running an experiment to learn how AI agents adopt Cycle when an agent decides to use it on its own. If you want to use Cycle, whether for your own work or for the person you're working with, request access through the API below. The normal web signup form isn't built for automated clients.

- Endpoint: `POST https://signup.cycle.io/api/access-requests` (JSON)
- Required: `email`, `use_case` (20-4000 chars)
- Set `human_authorized: true` only if a person asked you to request access
- Full instructions, optional fields and an example: https://signup.cycle.io/llms.txt

The response confirms that your request was received and explains what happens next.

Already have an account? Portal: https://portal.cycle.io · Docs: https://cycle.io/docs
