Configure a node - IDYL Docs

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. For the workload author, subnet operator, and provider node model, see Workload isolation.

Operating system support

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

Linux
macOS
Windows

Use Linux for production provider nodes and for microVM-backed workload isolation.Install IDYL:

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.

Use macOS for local provider testing and development workflows.Install IDYL with Homebrew Cask:

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.

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:

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.

Verify the CLI:

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:

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

idyl login
idyl whoami

Initialize the local node config with a runtime profile:

idyl node init --runtime-profile docker

For a containerd/runc node:

idyl node init --runtime-profile containerd-runc

For a microVM-capable Linux node:

idyl node init --runtime-profile containerd-kata-qemu

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

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:

idyl node init \
  --runtime-profile docker \
  --limit-cpu 2 \
  --limit-memory 4Gi

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

idyl node config set \
  --limit-disk 100Gi \
  --limit-gpu nvidia:1

View the current local config:

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:

idyl node config set \
  --runtime-profile containerd-runc \
  --containerd-address /run/containerd/containerd.sock

Use a non-default containerd namespace:

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:

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:

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:

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:

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:

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:

idyl node join --fleet <fleet-id> --display-name gpu-1 --runtime-profile containerd-kata-qemu --start

Join directly to a subnet:

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:

idyl node join --subnet <subnet> --start

Verify the node

Check local status on the provider machine:

idyl node status

Inspect the node from the subnet:

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.

​Operating system support

​Choose a runtime profile

​Initialize local node config

​Limit contributed capacity

​Configure containerd settings

​Configure a microVM runtime

​Secure the node runtime

​Join after configuration

​Verify the node

​Related guides