> ## 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.

# idyl node

> Manage nodes

Manage the local provider node identity and view runtime nodes.

Use init to prepare this machine and record local contribution limits before
joining. The join workflow creates or loads this machine's local node identity,
proves ownership with a private-key signature, and requests fleet or direct
subnet admission.

## Usage

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

## Aliases

* `nodes`

## Commands

| Command                       | Description                                            |
| ----------------------------- | ------------------------------------------------------ |
| `idyl node config`            | Manage this machine's local node config                |
| `idyl node credential`        | Manage this node's connection credential               |
| `idyl node edit`              | Edit an account-owned provider node                    |
| `idyl node get`               | List nodes in subnet, or get one's details             |
| `idyl node id`                | Show this machine's local node identity                |
| `idyl node init`              | Prepare this machine as a local provider node          |
| `idyl node join`              | Join this machine as a provider node                   |
| `idyl node logs`              | Show local node service logs                           |
| `idyl node reset`             | Delete local node identity and state                   |
| `idyl node run-service`       | Run idyld under the local service wrapper              |
| `idyl node service`           | Plan and validate production node service installation |
| `idyl node start`             | Install and start the local node service               |
| `idyl node status`            | Show local node status                                 |
| `idyl node stop`              | Stop the local node service                            |
| `idyl node uninstall-service` | Remove the local node service integration              |

## Inherited flags

| Flag                                 | Description                                                        |
| ------------------------------------ | ------------------------------------------------------------------ |
| `-a <string>, --account-id <string>` | Account ID to use, overriding the current context.                 |
| `-c <string>, --context <string>`    | Use the named context for this command.                            |
| `--homedir <string>`                 | Override the configuration directory. Defaults to \~/.config/idyl. |
| `-n <string>, --namespace <string>`  | Namespace to use for this command.                                 |
| `-o <string>, --output <string>`     | Output format (json\|yaml).                                        |
| `-p <string>, --profile <string>`    | Override the access profile for this command.                      |
| `--realm <string>`                   | Override the realm for this command.                               |
| `--subnet <string>`                  | Override the context subnet for this command.                      |

## Examples

```bash theme={null}
# Prepare this machine with a node realm and local contribution limits
idyl node init --realm idyl.network --limit-cpu 1 --limit-memory 256Mi --limit-disk 10Gi

# Join this machine through a fleet
idyl node join --fleet <fleet-id> --display-name gpu-1 --start

# Rename this machine's account-owned provider node
idyl node edit --set-display-name gpu-1

# Join this machine directly to a subnet
idyl node join --subnet <subnet> --start

# Show this machine's local node identity
idyl node id

# List connected nodes in the current subnet
idyl node get
```

## Subcommand reference

### `idyl node config`

Manage this machine's local node config.

The local node config stores non-secret service state, the node realm, and
contribution limits. Contribution limits are local safety caps: they define the
maximum CPU, memory, GPU, and ephemeral disk capacity this machine is willing to
make available to IDYL.

#### Usage

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

#### Commands

| Command                | Description                             |
| ---------------------- | --------------------------------------- |
| `idyl node config get` | Show this machine's local node config   |
| `idyl node config set` | Update this machine's local node config |

#### Examples

```bash theme={null}
idyl node config show
idyl node config get
idyl node config set --realm idyl.network
idyl node config set --limit-cpu 2 --limit-memory 1Gi
idyl node config set --limit-disk 50Gi --limit-gpu nvidia:1
```

### `idyl node config get`

Show this machine's local node config, contribution limits, and local config paths.

#### Usage

```bash theme={null}
idyl node config get [flags]
```

#### Aliases

* `show`

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

### `idyl node config set`

Update this machine's local node config.

Set the local node realm or one or more local safety caps for the maximum CPU,
memory, GPU, and ephemeral disk capacity this machine is willing to make
available to IDYL. Changes are written locally and apply the next time the node
service starts.

#### Usage

```bash theme={null}
idyl node config set [flags]
```

#### Flags

| Flag                                      | Description                                                                                                                                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--containerd-address <string>`           | Socket address for containerd profiles or raw containerd provider config.                                                                                                                         |
| `--containerd-kata-config-path <string>`  | Kata runtime configuration path for Kata profiles or raw Kata provider config.                                                                                                                    |
| `--containerd-kata-vmm-backend <string>`  | Expected Kata VMM backend for raw Kata provider config or advanced profile overrides: qemu or firecracker.                                                                                        |
| `--containerd-namespace <string>`         | The containerd namespace for containerd profiles or raw containerd provider config.                                                                                                               |
| `--containerd-runtime-type <string>`      | The containerd runtime type for raw provider config; cannot be combined with --runtime-profile.                                                                                                   |
| `--limit-cpu <string>`                    | Maximum CPU this node may contribute, such as 1, 2, or 500m.                                                                                                                                      |
| `--limit-disk <string>`                   | Maximum ephemeral disk this node may contribute, such as 10Gi, 100Gi, or 500Gi.                                                                                                                   |
| `--limit-gpu <string>`                    | Maximum GPU capacity this node may contribute, such as 1, nvidia:1, or h100:2.                                                                                                                    |
| `--limit-memory <string>`                 | Maximum memory this node may contribute, such as 256Mi, 1Gi, or 8Gi.                                                                                                                              |
| `--microvm-ack-none`                      | Acknowledge that the microvm none-network containment proof passed on this host.                                                                                                                  |
| `--microvm-ack-restricted-egress`         | Acknowledge that the microvm restricted-egress containment proof passed on this host.                                                                                                             |
| `--microvm-artifact-version <string>`     | Pinned guest artifact version for the microvm profile (required).                                                                                                                                 |
| `--microvm-containerd-address <string>`   | Containerd socket used by the microvm provider for image operations; defaults to /run/containerd/containerd.sock.                                                                                 |
| `--microvm-containerd-namespace <string>` | Containerd namespace used by the microvm provider for image operations; defaults to idyld.                                                                                                        |
| `-o <string>, --output <string>`          | Output format: table, json, or yaml. Default: `table`.                                                                                                                                            |
| `--runtime-profile <string>`              | Named local runtime preset that selects the provider, runtime type, and explicit backend when applicable: docker, containerd-runc, containerd-kata-qemu, containerd-kata-firecracker, or microvm. |
| `--runtime-provider <string>`             | Raw local runtime provider when not using --runtime-profile: docker or containerd. Default: `docker`.                                                                                             |
| `--workload-session-proxy-path <string>`  | Absolute path to the workload session proxy binary (idyl-workload-session-proxy); defaults to the binary installed alongside idyld. Pass an empty value to clear an override.                     |

#### Examples

```bash theme={null}
idyl node config set --realm idyl.network
idyl node config set --limit-cpu 2
idyl node config set --limit-memory 1Gi --limit-disk 50Gi
idyl node config set --limit-gpu nvidia:1
idyl node config set --runtime-profile containerd-runc
```

### `idyl node credential`

Manage this node's connection credential

#### Usage

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

#### Commands

| Command                      | Description                             |
| ---------------------------- | --------------------------------------- |
| `idyl node credential renew` | Renew this node's connection credential |

### `idyl node credential renew`

Renew this node's connection credential using its current connection certificate. This node-local operation does not require a user login.

#### Usage

```bash theme={null}
idyl node credential renew [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

### `idyl node edit`

Set or clear a provider node's account-owned display name.

The optional argument is always the canonical node ID. When it is omitted,
the command targets this machine's existing local node identity. Display names
are presentation labels only and are never resolved as identifiers.

#### Usage

```bash theme={null}
idyl node edit [node-id] [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `--clear-display-name`           | Remove the provider node display name.                 |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |
| `--set-display-name <string>`    | Set the provider node display name.                    |

#### Examples

```bash theme={null}
idyl node edit --set-display-name gpu-1
idyl node edit <node-id> --set-display-name "GPU East"
idyl node edit <node-id> --clear-display-name
```

### `idyl node get`

List nodes in the current subnet, or get details of a specific node.

With no arguments, lists connected nodes in the subnet.
With a node ID argument, gets details of that specific node.

#### Usage

```bash theme={null}
idyl node get [node-id] [flags]
```

#### Aliases

* `list`
* `ls`

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `--all`                          | Include disconnected nodes.                            |
| `--limit <int>`                  | Maximum number of nodes to list. Default: `100`.       |
| `--offset <int>`                 | Number of nodes to skip. Default: `0`.                 |
| `-o <string>, --output <string>` | Output format (json\|yaml\|wide).                      |
| `-s <string>, --subnet <string>` | Canonical subnet slug, overriding the current context. |
| `-w, --watch`                    | Watch for changes to nodes.                            |

#### Examples

```bash theme={null}
# List connected nodes
idyl node get

# List all nodes including disconnected
idyl node get --all

# Get a specific node
idyl node get my-node-id

# Watch nodes
idyl node get -w

# List with per-class detail (VMM backend, feature tags)
idyl node get -o wide

# Get in JSON format
idyl node get -o json
```

### `idyl node id`

Show this machine's local node identity without creating server-side state.

#### Usage

```bash theme={null}
idyl node id [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

### `idyl node init`

Prepare this machine as a local provider node without joining IDYL.

The command creates this machine's local node identity and local node config if
they do not already exist. The local config records the node realm and can also
record contribution limits for the maximum CPU, memory, GPU, and ephemeral disk
capacity this machine is willing to make available to IDYL.

If --realm is omitted, the command uses the active CLI context realm, or the
only initialized realm when exactly one realm is configured.

The command does not register ownership, join a fleet, join a subnet, request
admission, or start the local node service.

#### Usage

```bash theme={null}
idyl node init [flags]
```

#### Flags

| Flag                                      | Description                                                                                                                                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--containerd-address <string>`           | Socket address for containerd profiles or raw containerd provider config.                                                                                                                         |
| `--containerd-kata-config-path <string>`  | Kata runtime configuration path for Kata profiles or raw Kata provider config.                                                                                                                    |
| `--containerd-kata-vmm-backend <string>`  | Expected Kata VMM backend for raw Kata provider config or advanced profile overrides: qemu or firecracker.                                                                                        |
| `--containerd-namespace <string>`         | The containerd namespace for containerd profiles or raw containerd provider config.                                                                                                               |
| `--containerd-runtime-type <string>`      | The containerd runtime type for raw provider config; cannot be combined with --runtime-profile.                                                                                                   |
| `--limit-cpu <string>`                    | Maximum CPU this node may contribute, such as 1, 2, or 500m.                                                                                                                                      |
| `--limit-disk <string>`                   | Maximum ephemeral disk this node may contribute, such as 10Gi, 100Gi, or 500Gi.                                                                                                                   |
| `--limit-gpu <string>`                    | Maximum GPU capacity this node may contribute, such as 1, nvidia:1, or h100:2.                                                                                                                    |
| `--limit-memory <string>`                 | Maximum memory this node may contribute, such as 256Mi, 1Gi, or 8Gi.                                                                                                                              |
| `--microvm-ack-none`                      | Acknowledge that the microvm none-network containment proof passed on this host.                                                                                                                  |
| `--microvm-ack-restricted-egress`         | Acknowledge that the microvm restricted-egress containment proof passed on this host.                                                                                                             |
| `--microvm-artifact-version <string>`     | Pinned guest artifact version for the microvm profile (required).                                                                                                                                 |
| `--microvm-containerd-address <string>`   | Containerd socket used by the microvm provider for image operations; defaults to /run/containerd/containerd.sock.                                                                                 |
| `--microvm-containerd-namespace <string>` | Containerd namespace used by the microvm provider for image operations; defaults to idyld.                                                                                                        |
| `-o <string>, --output <string>`          | Output format: table, json, or yaml. Default: `table`.                                                                                                                                            |
| `--runtime-profile <string>`              | Named local runtime preset that selects the provider, runtime type, and explicit backend when applicable: docker, containerd-runc, containerd-kata-qemu, containerd-kata-firecracker, or microvm. |
| `--runtime-provider <string>`             | Raw local runtime provider when not using --runtime-profile: docker or containerd. Default: `docker`.                                                                                             |
| `--workload-session-proxy-path <string>`  | Absolute path to the workload session proxy binary (idyl-workload-session-proxy); defaults to the binary installed alongside idyld. Pass an empty value to clear an override.                     |

#### Examples

```bash theme={null}
idyl node init
idyl node init --realm idyl.network
idyl node init --limit-cpu 1 --limit-memory 256Mi
idyl node init --runtime-profile containerd-kata-qemu
idyl node init --realm idyl.network --limit-cpu 2 --limit-memory 1Gi --limit-disk 50Gi --limit-gpu nvidia:1
```

### `idyl node join`

Join this machine as a provider node.

The command creates or loads the local node identity, asks the account API for
an enrollment challenge, signs that exact challenge locally, and completes the
account-scoped enrollment flow. The private key never leaves this machine.

Use --runtime-profile for named presets. A profile expands to the provider,
runtime type, and default local runtime settings. Use --runtime-provider only
when you are not using a profile and need raw runtime settings. Profiles and
\--runtime-provider cannot be combined.

The docker and containerd-runc profiles report container isolation.
containerd-kata-qemu and containerd-kata-firecracker report secure-container isolation
and pin the Kata VMM backend. The microvm profile reports microvm isolation and
requires an explicitly pinned guest artifact version. Joining a subnet does not by itself prove
compatibility with subnet runtime policy; compatibility is enforced when
capacity is reported and workloads are scheduled.

#### Usage

```bash theme={null}
idyl node join [flags]
```

#### Flags

| Flag                                      | Description                                                                                                                                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--containerd-address <string>`           | Socket address for containerd profiles or raw containerd provider config.                                                                                                                         |
| `--containerd-kata-config-path <string>`  | Kata runtime configuration path for Kata profiles or raw Kata provider config.                                                                                                                    |
| `--containerd-kata-vmm-backend <string>`  | Expected Kata VMM backend for raw Kata provider config or advanced profile overrides: qemu or firecracker.                                                                                        |
| `--containerd-namespace <string>`         | The containerd namespace for containerd profiles or raw containerd provider config.                                                                                                               |
| `--containerd-runtime-type <string>`      | The containerd runtime type for raw provider config; cannot be combined with --runtime-profile.                                                                                                   |
| `--display-name <string>`                 | Optional account-owned provider node display name.                                                                                                                                                |
| `--fleet <string>`                        | Fleet ID for fleet-based provider admission.                                                                                                                                                      |
| `--microvm-ack-none`                      | Acknowledge that the microvm none-network containment proof passed on this host.                                                                                                                  |
| `--microvm-ack-restricted-egress`         | Acknowledge that the microvm restricted-egress containment proof passed on this host.                                                                                                             |
| `--microvm-artifact-version <string>`     | Pinned guest artifact version for the microvm profile (required).                                                                                                                                 |
| `--microvm-containerd-address <string>`   | Containerd socket used by the microvm provider for image operations; defaults to /run/containerd/containerd.sock.                                                                                 |
| `--microvm-containerd-namespace <string>` | Containerd namespace used by the microvm provider for image operations; defaults to idyld.                                                                                                        |
| `-o <string>, --output <string>`          | Output format: table, json, or yaml. Default: `table`.                                                                                                                                            |
| `--runtime-profile <string>`              | Named local runtime preset that selects the provider, runtime type, and explicit backend when applicable: docker, containerd-runc, containerd-kata-qemu, containerd-kata-firecracker, or microvm. |
| `--runtime-provider <string>`             | Raw local runtime provider when not using --runtime-profile: docker or containerd. Default: `docker`.                                                                                             |
| `--start`                                 | Start the local node service after admission.                                                                                                                                                     |
| `--subnet <string>`                       | Canonical subnet slug for daemon placement and provider admission.                                                                                                                                |

#### Examples

```bash theme={null}
idyl node join --subnet 100000000001 --display-name gpu-1 --start
idyl node join --subnet 100000000001 --runtime-profile containerd-kata-qemu --start
idyl node join --subnet 100000000001 --runtime-profile containerd-kata-firecracker --start
idyl node join --subnet 100000000001 --runtime-profile microvm --microvm-artifact-version 0.2.4 --microvm-ack-none --start
idyl node join --subnet 100000000001 --runtime-profile containerd-runc --start
idyl node join --fleet 391742608215 --subnet 100000000001 --start
idyl node join --fleet 391742608215
```

### `idyl node logs`

Show local node service logs

#### Usage

```bash theme={null}
idyl node logs [flags]
```

#### Flags

| Flag            | Description                                           |
| --------------- | ----------------------------------------------------- |
| `--follow`      | Stream new log lines as they arrive. Default: `true`. |
| `--lines <int>` | Number of log lines to show. Default: `100`.          |

### `idyl node reset`

Delete local node identity and state

#### Usage

```bash theme={null}
idyl node reset [flags]
```

#### Flags

| Flag                             | Description                                                   |
| -------------------------------- | ------------------------------------------------------------- |
| `--dangerous`                    | Confirm that local node identity and state should be deleted. |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`.        |
| `-y, --yes`                      | Skip confirmation prompts.                                    |

### `idyl node run-service`

Run idyld under the local service wrapper

#### Usage

```bash theme={null}
idyl node run-service
```

### `idyl node service`

Plan and validate production Linux system service installation for the local node daemon. The current command group is report-only.

#### Usage

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

#### Commands

| Command                      | Description                                        |
| ---------------------------- | -------------------------------------------------- |
| `idyl node service plan`     | Render a production node service installation plan |
| `idyl node service validate` | Validate a production node service plan            |

### `idyl node service plan`

Render a production Linux system service installation plan for idyld.

This command is plan-only. It does not install packages, create users or groups,
write systemd units, change file ownership, chmod host paths, alter runtime
socket permissions, or start services.

#### Usage

```bash theme={null}
idyl node service plan [flags]
```

#### Flags

| Flag                             | Description                                                                                                |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`.                                                     |
| `--production`                   | Render the production Linux system service model.                                                          |
| `--runtime-profile <string>`     | Production runtime profile: docker, containerd-runc, containerd-kata-qemu, or containerd-kata-firecracker. |

#### Examples

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

### `idyl node service validate`

Validate the production Linux system service plan for idyld.

This command is validation-only. It does not install packages, create users or
groups, write systemd units, change file ownership, chmod host paths, alter
runtime socket permissions, or start services.

#### Usage

```bash theme={null}
idyl node service validate [flags]
```

#### Flags

| Flag                             | Description                                                                                                |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`.                                                     |
| `--production`                   | Validate the production Linux system service model.                                                        |
| `--runtime-profile <string>`     | Production runtime profile: docker, containerd-runc, containerd-kata-qemu, or containerd-kata-firecracker. |

#### Examples

```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
idyl node service validate --production --runtime-profile containerd-kata-firecracker -o json
```

### `idyl node start`

Install and start the local node service

#### Usage

```bash theme={null}
idyl node start [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

### `idyl node status`

Show local node identity and readiness status. The default node preflight requires production service and daemon state; runtime-provider scope checks only host and runtime prerequisites for direct provider conformance. Remote admission status is not inferred from local files.

#### Usage

```bash theme={null}
idyl node status [flags]
```

#### Flags

| Flag                             | Description                                                 |
| -------------------------------- | ----------------------------------------------------------- |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`.      |
| `--preflight-scope <string>`     | Preflight scope: node or runtime-provider. Default: `node`. |

### `idyl node stop`

Stop the local node service

#### Usage

```bash theme={null}
idyl node stop [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

### `idyl node uninstall-service`

Remove the local node service integration

#### Usage

```bash theme={null}
idyl node uninstall-service [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |