> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idyl.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure runtime policy

> Control which workload isolation classes a subnet accepts.

Use subnet runtime policy when a subnet should accept only specific workload
isolation classes, such as standard containers or microVM-backed workloads.
For the builder, operator, and provider model, see
[Workload isolation](/concepts/workload-isolation).

Runtime policy is enforced at the subnet boundary. It controls workload
admission and node eligibility for scheduling. It does not grant provider
admission by itself, and it is separate from deploy approval.

## How runtime policy works

IDYL keeps three concepts separate:

| Concept                   | Example                                                                       | Controlled by          |
| ------------------------- | ----------------------------------------------------------------------------- | ---------------------- |
| Subnet runtime policy     | `allowedIsolationClasses: ["microvm"]`, `allowedVMMBackends: ["firecracker"]` | Subnet operator        |
| Workload isolation intent | `--isolation-class microvm`                                                   | Workload author        |
| Node runtime preset       | `--runtime-profile containerd-kata-qemu`                                      | Provider node operator |

The supported isolation classes are:

| Isolation class | Meaning                                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `container`     | Standard container isolation. Docker Engine and containerd/runc nodes can satisfy this class.                                         |
| `microvm`       | MicroVM-backed workload runtime. The supported provider path is containerd with Kata Containers and an explicit Kata backend profile. |

For `microvm` policy, a subnet can also restrict compatible Kata VMM backends:

| VMM backend   | Matching node profiles        |
| ------------- | ----------------------------- |
| `qemu`        | `containerd-kata-qemu`        |
| `firecracker` | `containerd-kata-firecracker` |

`microvm` is not a cryptographic attestation claim. It means IDYL schedules the
workload for a node that reports a compatible microVM runtime path. It does not
prove confidential-computing execution.

## Choose a policy

| Policy                       | Use it when                                                                                              |
| ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| No runtime policy            | The subnet should not apply a subnet-level isolation rule.                                               |
| `microvm` with a default     | Most workloads in the subnet should run as `microvm`, and workload authors may omit `--isolation-class`. |
| Strict `microvm`             | Every workload author must explicitly request `--isolation-class microvm`.                               |
| `microvm` with a VMM backend | The subnet should accept only explicit Kata backend capacity, such as QEMU or Firecracker.               |
| `container` and `microvm`    | The subnet accepts both classes, and each workload should state the intended isolation class.            |

## Create a subnet with runtime policy

Create a subnet with no runtime policy:

```bash theme={null}
idyl subnet create --region us-east
```

Create a `microvm` subnet with defaulting. Workloads that omit
`--isolation-class` inherit `microvm`:

```bash theme={null}
idyl subnet create \
  --region us-east \
  --allowed-isolation-class microvm \
  --default-isolation-class microvm
```

Create a strict `microvm` subnet. Workloads must explicitly request
`--isolation-class microvm`:

```bash theme={null}
idyl subnet create \
  --region us-east \
  --allowed-isolation-class microvm
```

Create a `microvm` subnet that accepts only Kata + Firecracker nodes:

```bash theme={null}
idyl subnet create \
  --region us-east \
  --allowed-isolation-class microvm \
  --allowed-vmm-backend firecracker
```

Create a `microvm` subnet that accepts either Kata + QEMU or Kata +
Firecracker nodes:

```bash theme={null}
idyl subnet create \
  --region us-east \
  --allowed-isolation-class microvm \
  --allowed-vmm-backend qemu \
  --allowed-vmm-backend firecracker
```

Create a subnet that allows both `container` and `microvm` workloads:

```bash theme={null}
idyl subnet create \
  --region us-east \
  --allowed-isolation-class container \
  --allowed-isolation-class microvm
```

You can also pass allowed classes as a comma-separated list:

```bash theme={null}
idyl subnet create \
  --region us-east \
  --allowed-isolation-class container,microvm
```

## Update an existing subnet

Set or replace runtime policy:

```bash theme={null}
idyl subnet edit <subnet> \
  --allowed-isolation-class microvm \
  --default-isolation-class microvm
```

Restrict a `microvm` subnet to a specific Kata backend:

```bash theme={null}
idyl subnet edit <subnet> \
  --allowed-isolation-class microvm \
  --allowed-vmm-backend firecracker
```

Clear runtime policy:

```bash theme={null}
idyl subnet edit <subnet> --clear-runtime-policy
```

When you set a policy, `--allowed-isolation-class` is required.
`--default-isolation-class` is optional, but when present it must be one of the
allowed isolation classes. `--allowed-vmm-backend` is optional and only applies
when `microvm` is an allowed isolation class.

## Verify the policy

Inspect the subnet:

```bash theme={null}
idyl subnet get <subnet> -o yaml
```

Output similar to:

```yaml theme={null}
slug: "100000000001"
region: us-east
status: active
runtimePolicy:
  allowedIsolationClasses:
    - microvm
  defaultIsolationClass: microvm
  allowedVMMBackends:
    - firecracker
```

List subnets:

```bash theme={null}
idyl subnet list
```

When a subnet has a runtime policy, table output includes a runtime policy
summary. Structured output includes the `runtimePolicy` object.

## Workload admission behavior

When a workload is created in a subnet with runtime policy, IDYL resolves the
effective isolation class in this order:

1. If the workload sets `--isolation-class`, IDYL uses that explicit value.
2. Otherwise, if the subnet sets `defaultIsolationClass`, IDYL uses the subnet
   default.
3. Otherwise, if the subnet has runtime policy but no default, IDYL rejects the
   workload because an isolation class is required.

The effective isolation class must be listed in
`allowedIsolationClasses`.

This workload is accepted by a `microvm` subnet:

```bash theme={null}
idyl deploy nginx:1.27-alpine \
  --name web \
  --subnet <subnet> \
  --platform linux/amd64 \
  --isolation-class microvm
```

This workload is accepted only when the subnet has
`defaultIsolationClass: microvm`:

```bash theme={null}
idyl deploy nginx:1.27-alpine \
  --name web \
  --subnet <subnet> \
  --platform linux/amd64
```

This workload is rejected by a `microvm`-only subnet:

```bash theme={null}
idyl deploy nginx:1.27-alpine \
  --name web \
  --subnet <subnet> \
  --platform linux/amd64 \
  --isolation-class container
```

The error message includes:

```text theme={null}
isolation.class "container" is not allowed by subnet runtimePolicy
```

When a subnet has runtime policy but no default, a workload that omits
`--isolation-class` is rejected with a message that includes:

```text theme={null}
isolation.class is required by subnet runtimePolicy
```

## Coordinate compatible capacity

Runtime policy does not install runtimes or approve provider capacity. Provider
nodes must still be admitted to the subnet, and each node must report runtime
metadata that can satisfy the policy.

`--runtime-profile` selects a named preset. The preset writes the provider,
runtime type, and default local runtime settings. Use `--runtime-provider` only
when you are not using a preset and need to provide raw runtime settings.

| Runtime profile               | Isolation class it can satisfy |
| ----------------------------- | ------------------------------ |
| `docker`                      | `container`                    |
| `containerd-runc`             | `container`                    |
| `containerd-kata-qemu`        | `microvm`                      |
| `containerd-kata-firecracker` | `microvm`                      |

Use `containerd-kata-*` as shorthand for the family of explicit Kata backend
profiles. It is not a runtime profile value accepted by the CLI.

Join a Kata-capable node to a subnet:

```bash theme={null}
idyl node join --subnet <subnet> --runtime-profile containerd-kata-qemu --start
```

A node can be admitted to a subnet but still fail to contribute compatible
capacity for a workload. For example, Docker and containerd/runc nodes do not
satisfy `microvm` policy.

Inspect connected nodes:

```bash theme={null}
idyl node get --subnet <subnet>
```

On the provider node, inspect local runtime readiness:

```bash theme={null}
idyl node status
```

## Scheduling behavior

After a workload passes admission, the scheduler uses the effective isolation
class and node runtime metadata.

For `microvm`, the node must report a compatible microVM runtime path. Docker
and containerd/runc are not compatible with `microvm`, and IDYL does not
downgrade `microvm` workloads to `container`. Backend selection is controlled
by node configuration and subnet runtime policy, not by a workload-level
runtime-profile flag.

If no compatible node is available, the workload remains unplaced until
compatible capacity is available. Runtime compatibility errors include the
requested isolation class, for example:

```text theme={null}
no available nodes in subnet <subnet> support requested isolation class microvm
```

Resource shortage errors do not include an isolation class compatibility
reason:

```text theme={null}
no nodes available in subnet <subnet> with sufficient capacity and generic requirements
```

## Troubleshooting

| Symptom                                                                         | What to check                                                                                                                              |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Workload is rejected with `isolation.class is required by subnet runtimePolicy` | The subnet has runtime policy but no default. Add `--isolation-class` to the workload or set `--default-isolation-class` on the subnet.    |
| Workload is rejected with `isolation.class "container" is not allowed`          | The workload requested an isolation class that is not in `allowedIsolationClasses`.                                                        |
| Node is admitted but workloads do not schedule there                            | Confirm the node profile matches the workload isolation class and that the node is reporting healthy runtime metadata.                     |
| `microvm` workloads do not place                                                | Confirm the subnet has admitted at least one healthy `containerd-kata-qemu` or `containerd-kata-firecracker` node with available capacity. |
| `container` workloads do not place                                              | Confirm the subnet has admitted healthy Docker or containerd/runc capacity.                                                                |

## Related guides

* [Workload isolation](/concepts/workload-isolation)
* [Manage a subnet](/operate/manage-a-subnet)
* [Control admission](/operate/control-admission)
* [Inspect nodes](/operate/inspect-nodes)
* [Connect a node](/provide/connect-a-node)
* [Command reference](/cli/reference/generated)