Skip to main content
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.
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.
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 profileHost supportWorkload isolationUse it when
dockerLinux, macOScontainerYou want the default container runtime path and Docker Engine is available.
containerd-runcLinuxcontainerYou want standard container isolation through containerd and runc.
containerd-kata-qemuLinux with KVM, containerd, Kata Containers, and QEMUmicrovmYou need a Kata + QEMU backend and the host has been prepared for it.
containerd-kata-firecrackerLinux with KVM, containerd, Kata Containers, and FirecrackermicrovmYou 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

Log in before configuring or joining a node: 
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:
CheckWhat to do
Choose the runtime profile deliberatelyUse 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 nodeThe 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 capacitySet --limit-cpu, --limit-memory, --limit-disk, and --limit-gpu to the capacity you intend to contribute.
Validate readinessRun idyl node status and resolve failed checks before starting or rejoining the node.
Match subnet policyConfirm the subnet runtime policy accepts the isolation class the node can provide.
Use Linux for microVM capacityRun 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> --runtime-profile containerd-kata-qemu --start
Join directly to a subnet: 
idyl node join --subnet <subnet> --runtime-profile containerd-kata-qemu --start
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.