> ## 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 a node

> Choose local node settings, runtime profiles, and runtime security posture before joining a node.

Configure a node on the machine that will provide capacity to IDYL. The local
node config controls the node realm, contribution limits, runtime profile, and
service readiness checks for that machine.

Start here when you want to choose how the node should run workloads before
joining a fleet or subnet. For the full join flow, see
[Connect a node](/provide/connect-a-node).

For the workload author, subnet operator, and provider node model, see
[Workload isolation](/concepts/workload-isolation).

## Operating system support

Use the operating system that matches how the node will be used.

<Tabs>
  <Tab title="Linux">
    Use Linux for production provider nodes and for microVM-backed workload
    isolation.

    Install IDYL:

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/idyl-labs/cli/main/install.sh | sh
    ```

    Linux nodes can use Docker Engine, containerd with runc, or containerd with
    Kata Containers when the host has the required runtime dependencies.
  </Tab>

  <Tab title="macOS">
    Use macOS for local provider testing and development workflows.

    Install IDYL with Homebrew Cask:

    ```bash theme={null}
    brew install --cask idyl-labs/tap/idyl
    ```

    macOS nodes do not provide native Linux/KVM microVM capacity. Use a Linux
    host when a subnet requires microVM-backed workloads.
  </Tab>

  <Tab title="Windows">
    Use Windows as an operator workstation for the IDYL CLI. Native Windows
    provider nodes are not supported by the local node service documented here.

    To provide capacity from a Windows environment, run a supported Linux host
    or VM and configure the IDYL node inside that Linux environment:

    ```powershell theme={null}
    ssh <user>@<linux-host>
    ```

    Then follow the Linux instructions on that host.

    Do not use WSL2 as a production microVM provider host. Use a real Linux host
    with KVM when the subnet requires microVM-backed workloads.
  </Tab>
</Tabs>

Verify the CLI:

```bash theme={null}
idyl version
```

## Choose a runtime profile

Prefer `--runtime-profile` for normal node configuration. A profile writes the
provider and runtime settings that the node will report when it starts. Some
profiles require a recent IDYL CLI and host-specific runtime dependencies.

| Runtime profile               | Host support                                                 | Workload isolation | Use it when                                                                  |
| ----------------------------- | ------------------------------------------------------------ | ------------------ | ---------------------------------------------------------------------------- |
| `docker`                      | Linux, macOS                                                 | `container`        | You want the default container runtime path and Docker Engine is available.  |
| `containerd-runc`             | Linux                                                        | `container`        | You want standard container isolation through containerd and runc.           |
| `containerd-kata-qemu`        | Linux with KVM, containerd, Kata Containers, and QEMU        | `microvm`          | You need a Kata + QEMU backend and the host has been prepared for it.        |
| `containerd-kata-firecracker` | Linux with KVM, containerd, Kata Containers, and Firecracker | `microvm`          | You need a Kata + Firecracker backend and the host has been prepared for it. |

The profiles available on a machine are shown by your installed CLI:

```bash theme={null}
idyl node init --help
idyl node config set --help
```

Docker and containerd/runc nodes do not satisfy `microvm` runtime policy.
MicroVM-backed workloads require a compatible containerd/Kata node with an
explicit backend profile. IDYL does not change a requested microVM workload to
container isolation when compatible capacity is missing.

## Initialize local node config

Log in before configuring or joining a node:

```bash theme={null}
idyl login
idyl whoami
```

Initialize the local node config with a runtime profile:

```bash theme={null}
idyl node init --runtime-profile docker
```

For a containerd/runc node:

```bash theme={null}
idyl node init --runtime-profile containerd-runc
```

For a microVM-capable Linux node:

```bash theme={null}
idyl node init --runtime-profile containerd-kata-qemu
```

Set the node realm explicitly when the machine should use a specific realm:

```bash theme={null}
idyl node init \
  --realm global.idyl.network \
  --runtime-profile containerd-kata-qemu
```

## Limit contributed capacity

Contribution limits are local safety caps. IDYL uses the lower of the machine's
detected capacity and the limits you configure.

Set CPU and memory limits:

```bash theme={null}
idyl node init \
  --runtime-profile docker \
  --limit-cpu 2 \
  --limit-memory 4Gi
```

Set disk and GPU limits when the node should contribute those resources:

```bash theme={null}
idyl node config set \
  --limit-disk 100Gi \
  --limit-gpu nvidia:1
```

View the current local config:

```bash theme={null}
idyl node config show
```

If the node service is already running, restart it for updated contribution
limits or runtime settings to take effect.

## Configure containerd settings

The containerd profiles use the default containerd socket and namespace unless
you override them.

Use a non-default containerd socket:

```bash theme={null}
idyl node config set \
  --runtime-profile containerd-runc \
  --containerd-address /run/containerd/containerd.sock
```

Use a non-default containerd namespace:

```bash theme={null}
idyl node config set \
  --runtime-profile containerd-kata-qemu \
  --containerd-namespace idyld
```

Use raw runtime settings only when a named profile does not match the host:

```bash theme={null}
idyl node config set \
  --runtime-provider containerd \
  --containerd-runtime-type io.containerd.runc.v2
```

For most nodes, a named runtime profile is easier to inspect and operate than
raw runtime settings.

## Configure a microVM runtime

Use a microVM runtime profile on Linux hosts that have containerd, Kata
Containers, and KVM available. The host must be prepared before the node starts;
IDYL does not install containerd, Kata, or Firecracker for you.

For the Kata + QEMU backend:

```bash theme={null}
idyl node config set --runtime-profile containerd-kata-qemu
```

For the Kata + Firecracker backend, use the backend-specific profile and an
explicit Kata configuration path:

```bash theme={null}
idyl node config set \
  --runtime-profile containerd-kata-firecracker \
  --containerd-kata-config-path /opt/kata/share/defaults/kata-containers/configuration-fc.toml \
  --containerd-kata-vmm-backend firecracker
```

Use the Firecracker profile only when the host has Firecracker installed and the
Kata configuration selects Firecracker. If a required runtime dependency is
missing, the node reports a failed readiness check instead of using a different
runtime profile.

## Secure the node runtime

In this guide, securing the node runtime means choosing the appropriate
isolation profile, limiting contributed resources, validating host readiness,
and protecting the local node identity. It is not a remote attestation or
confidential-computing claim.

Use this checklist before admitting the node to a subnet that handles workloads
requiring stronger runtime isolation:

| Check                                   | What to do                                                                                                                                                |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Choose the runtime profile deliberately | Use `containerd-kata-qemu` or `containerd-kata-firecracker` for microVM-backed workloads. Use `docker` or `containerd-runc` only for container isolation. |
| Keep the node private key on the node   | The local node identity belongs to this machine. Do not copy it to other machines unless you intentionally want them to use the same identity.            |
| Limit capacity                          | Set `--limit-cpu`, `--limit-memory`, `--limit-disk`, and `--limit-gpu` to the capacity you intend to contribute.                                          |
| Validate readiness                      | Run `idyl node status` and resolve failed checks before starting or rejoining the node.                                                                   |
| Match subnet policy                     | Confirm the subnet runtime policy accepts the isolation class the node can provide.                                                                       |
| Use Linux for microVM capacity          | Run microVM provider nodes on real Linux hosts with KVM. Do not rely on macOS, Windows, or WSL2 for microVM-backed capacity.                              |

For production Linux nodes, render and validate the production service plan
before installing or starting the service:

```bash theme={null}
idyl node service plan --production --runtime-profile containerd-kata-qemu
idyl node service validate --production --runtime-profile containerd-kata-qemu
```

Use the profile that matches the node:

```bash theme={null}
idyl node service validate --production --runtime-profile docker
idyl node service validate --production --runtime-profile containerd-runc
idyl node service validate --production --runtime-profile containerd-kata-qemu
idyl node service validate --production --runtime-profile containerd-kata-firecracker
```

## Join after configuration

Join through a fleet:

```bash theme={null}
idyl node join --fleet <fleet-id> --display-name gpu-1 --runtime-profile containerd-kata-qemu --start
```

Join directly to a subnet:

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

`--display-name` sets optional account-owned presentation metadata. It does not
change the local node identity or runtime configuration.

If you already initialized the node with the desired runtime profile, you can
omit `--runtime-profile` during join:

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

## Verify the node

Check local status on the provider machine:

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

Inspect the node from the subnet:

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

If a workload does not place on the node, confirm the node is admitted, the
runtime profile is healthy, the subnet runtime policy matches the workload, and
the node has enough available capacity.

## Related guides

* [Workload isolation](/concepts/workload-isolation)
* [Connect a node](/provide/connect-a-node)
* [Run the node service](/provide/run-locally)
* [Configure runtime policy](/operate/configure-runtime-policy)
* [Inspect nodes](/operate/inspect-nodes)
* [Command reference](/cli/reference/generated)