Skip to main content
Use idyl node join on the machine that will provide capacity. The command creates or loads the machine’s local node identity, proves ownership from that machine, requests the chosen provider admission path, and can start the local node service when the node is admitted. The node private key stays on the machine. Package installation alone does not create a node identity or start the node service. You can give the node an optional display name while joining. The display name helps people recognize the node, but the immutable node ID remains its canonical identity.

​
1. Install IDYL

Node service management is supported on macOS and Linux.
Install IDYL with Homebrew Cask:
Verify the install:

​
2. Log in

Confirm the account that will own the node:

​
3. Configure the local node

This step is optional. idyl node join can create the local node identity and config automatically. Use idyl node init when you want to set the node realm or local resource limits before joining. If you omit --realm, the node uses the active CLI context realm. You can pass --realm explicitly when the CLI has multiple contexts or initialized realms.
Limits are safety caps: IDYL uses the lower of the machine’s detected capacity and the configured local limits. You can also set disk and GPU limits:
Update the local node config later:
If the node service is already running, restart it for updated limits to take effect. For runtime profile selection, operating system support, containerd settings, and microVM configuration, see Configure a node.

​
4. Join through a fleet

Use a fleet when this node should be managed with a group of provider nodes.
Output similar to:
Omit --display-name when the node should remain unnamed. Setting a display name during join requires permission to both enroll and edit provider nodes in the account.

​
5. Join one node directly to a subnet

Use direct subnet join when the subnet should admit this specific node instead of a fleet.
This path does not add the node to a fleet.

​
Pending admission

Some subnets require provider approval. If admission is pending, the node is registered but the local service is not started:
After the subnet operator grants admission, start the service:

​
6. Rename the node

Set or replace the display name for this machine’s existing local node identity:
To edit another node owned by the account, pass its canonical node ID:
Clear the display name:
Set and clear are mutually exclusive. A display name can be changed while the node is offline and does not require the node to reconnect. Display names are visible to users who can already see the node, including subnet observers. Do not put credentials, secrets, private URLs, or other sensitive information in a display name.

​
7. Check the local node

View logs:
Stop the local node service:
For more service lifecycle commands, see Run the node service.

​
8. Confirm the node is visible

Inspect connected nodes in the subnet:
To include disconnected nodes:
To watch nodes as they change:
Node tables show the display name and the full canonical node ID. When a node has no display name, the node ID is the primary value.

​
Remove local node state

To remove the local service integration while keeping the node identity:
To delete the local node identity and state, use reset with explicit confirmation:
Only reset a node when you intentionally want this machine to stop using its current node identity.