> For the complete documentation index, see [llms.txt](https://asus-isg-aidc.gitbook.io/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://asus-isg-aidc.gitbook.io/guide/v1.4.0/cli/commandreference/deploy.md).

# OS Deployment

| Developer | Last modified |
| --------- | ------------- |
| AIDC Team | 2026/02/12    |

## Table of Contents

* [1. Overview](#overview)
* [2. Subcommands](#subcommands)
* [3. Deployment Workflow](#deployment-workflow)
* [4. Usage Examples](#usage-examples)

***

## 1. Overview <a href="#overview" id="overview"></a>

The `deploy` command handles OS deployment via PXE boot, including DHCP service management, ISO image downloading, SSH access key distribution, and proxy configuration.

```bash
aidc-cli deploy <subcommand> [flags]
```

***

## 2. Subcommands <a href="#subcommands" id="subcommands"></a>

### 2.1 `install` — Install OS via PXE

Triggers unattended OS installation on target nodes via PXE boot.

```bash
aidc-cli deploy install
```

**Pre-flight checks:**

* Validates CSV IPs against DHCP subnet configuration
* Prompts for confirmation if mismatches are detected
* Requires DHCP to be enabled and an active image to be set

***

### 2.2 `dhcp-enabled` — Enable DHCP Service

Starts and enables the DHCP service on the management node.

```bash
aidc-cli deploy dhcp-enabled
```

***

### 2.3 `dhcp-disabled` — Disable DHCP Service

Stops and disables the DHCP service. Useful after deployment is complete to prevent unintended PXE boots.

```bash
aidc-cli deploy dhcp-disabled
```

{% hint style="warning" %}
It is strongly recommended to disable the DHCP server after OS deployment is complete. Leaving DHCP enabled may cause unexpected PXE boots on newly connected machines in the network.
{% endhint %}

***

### 2.4 `image-download` — Download OS Image

Downloads the currently active OS image ISO to the management node.

```bash
aidc-cli deploy image-download
```

{% hint style="info" %}
Set the active image first with `aidc-cli init image-active` before downloading.
{% endhint %}

***

### 2.5 `access-key` — Setup SSH Access Key

Distributes SSH public key to target nodes for passwordless access. This also enables integration of non-AIDC-deployed machines into the management scope.

```bash
aidc-cli deploy access-key [-f]
```

| Flag      | Short | Required | Description                                      |
| --------- | :---: | :------: | ------------------------------------------------ |
| `--force` |  `-f` |     ❌    | Force regenerate and overwrite existing SSH keys |

***

### 2.6 `proxy-enabled` — Enable Proxy

Configures proxy settings on target nodes for internet access. This is a one-way package retrieval proxy from the AIDC server.

```bash
aidc-cli deploy proxy-enabled
```

{% hint style="info" %}
The proxy allows target nodes to retrieve packages from the AIDC server when they do not have direct internet access.
{% endhint %}

***

## 3. Deployment Workflow <a href="#deployment-workflow" id="deployment-workflow"></a>

```mermaid
flowchart TD
    A["Configure DHCP<br>init dhcp-set"] --> B["Validate DHCP<br>init dhcp-validate"]
    B --> C["Set PXE Boot<br>bmc pxe-boot"]
    C --> D["Download Image<br>deploy image-download"]
    D --> E["Enable DHCP<br>deploy dhcp-enabled"]
    E --> F["Install OS<br>deploy install"]
    F --> G["Distribute SSH Keys<br>deploy access-key"]
    G --> H["Disable DHCP<br>deploy dhcp-disabled"]
```

***

## 4. Usage Examples <a href="#usage-examples" id="usage-examples"></a>

```bash
# Complete PXE deployment flow
aidc-cli deploy dhcp-enabled
aidc-cli deploy image-download
aidc-cli deploy install
aidc-cli deploy access-key
aidc-cli deploy dhcp-disabled

# Deploy on specific nodes
aidc-cli deploy install -l node01,node02

# Force overwrite SSH keys
aidc-cli deploy access-key -f
```