> ## 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.
# Connect a node
> Join this machine as an IDYL provider node and start the local node service.
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:
```bash theme={null}
brew install --cask idyl-labs/tap/idyl
```
Install IDYL with the install script:
```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/idyl-labs/cli/main/install.sh | sh
```
Verify the install:
```bash theme={null}
idyl version
```
## 2. Log in
```bash theme={null}
idyl login
```
Confirm the account that will own the node:
```bash theme={null}
idyl whoami
```
## 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.
```bash theme={null}
idyl node init --realm global.idyl.network --limit-cpu 1 --limit-memory 256Mi
```
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:
```bash theme={null}
idyl node init --realm global.idyl.network --limit-cpu 1 --limit-memory 256Mi --limit-disk 10Gi --limit-gpu nvidia:1
```
Update the local node config later:
```bash theme={null}
idyl node config set --realm global.idyl.network
idyl node config set --limit-cpu 2 --limit-memory 1Gi
idyl node config show
```
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](/provide/configure-a-node).
## 4. Join through a fleet
Use a fleet when this node should be managed with a group of provider nodes.
```bash theme={null}
idyl node join --fleet --display-name gpu-1 --start
```
Output similar to:
```text theme={null}
Node identity ready.
Display name: gpu-1
Node ID: 63GtQFnlN3-lsHQBW6HlJZblsHPy8n5oYO1lG0qZQd4
Account: 550000000001 / Alice
Signed in: alice@example.com
Fleet: 391742608215 / prod
Subnet: 100000000001
Admission: admitted
Service: started
```
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.
```bash theme={null}
idyl node join --subnet --display-name gpu-1 --start
```
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:
```text theme={null}
Node ID: idyl1abc...
Account: 550000000001 / Alice
Subnet: seti
Admission: pending
Service: stopped
Run after approval:
idyl node start
```
After the subnet operator grants admission, start the service:
```bash theme={null}
idyl node start
```
## 6. Rename the node
Set or replace the display name for this machine's existing local node
identity:
```bash theme={null}
idyl node edit --set-display-name gpu-2
```
To edit another node owned by the account, pass its canonical node ID:
```bash theme={null}
idyl node edit --set-display-name gpu-2
```
Clear the display name:
```bash theme={null}
idyl node edit --clear-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
```bash theme={null}
idyl node status
```
View logs:
```bash theme={null}
idyl node logs
```
Stop the local node service:
```bash theme={null}
idyl node stop
```
For more service lifecycle commands, see [Run the node service](/provide/run-locally).
## 8. Confirm the node is visible
Inspect connected nodes in the subnet:
```bash theme={null}
idyl node get --subnet
```
To include disconnected nodes:
```bash theme={null}
idyl node get --subnet --all
```
To watch nodes as they change:
```bash theme={null}
idyl node get --subnet --watch
```
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:
```bash theme={null}
idyl node uninstall-service
```
To delete the local node identity and state, use reset with explicit
confirmation:
```bash theme={null}
idyl node reset --dangerous
```
Only reset a node when you intentionally want this machine to stop using its
current node identity.