> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compute-desk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud-Init

> Configure instances on first boot with cloud-init scripts

## Overview

Pass a `cloud_init` script when procuring an offer to configure the instance automatically on first boot. Two formats are supported:

## Cloud-config YAML

Use `#cloud-config` for declarative configuration — package installation, file creation, and commands:

```json theme={null}
{
  "offer_id": "abc-123",
  "ssh_public_key": "ssh-ed25519 AAAA...",
  "cloud_init": "#cloud-config\npackages:\n  - htop\n  - jq\n  - python3-pip\nwrite_files:\n  - path: /opt/config.yml\n    content: |\n      model: llama-3\n      batch_size: 32\nruncmd:\n  - pip3 install numpy torch\n  - echo 'Setup complete' > /tmp/ready.txt"
}
```

Supported directives:

* `packages` — apt packages to install
* `write_files` — files to create (with optional permissions)
* `runcmd` — shell commands to run after boot

## Shell script

Use `#!/bin/bash` for full shell scripting control:

```json theme={null}
{
  "offer_id": "abc-123",
  "ssh_public_key": "ssh-ed25519 AAAA...",
  "cloud_init": "#!/bin/bash\nset -e\napt-get update && apt-get install -y htop jq\npip3 install torch\necho 'Setup complete' > /tmp/ready.txt"
}
```

## How it works

The cloud-init script is injected into the instance's startup script. Some vendors support native cloud-init (Lambda Labs, Nebius), while others convert the script to bash commands automatically. The conversion is transparent — you always pass the same `#cloud-config` YAML or `#!/bin/bash` script regardless of vendor.

<Warning>
  Scripts run as `root` and with `set -e` — any command failure will stop execution of remaining commands. For pip installs that may fail on older systems, use fallback patterns:

  ```bash theme={null}
  pip3 install --break-system-packages numpy 2>/dev/null || pip3 install numpy
  ```
</Warning>

## Verifying cloud-init ran

SSH into the instance and check your expected outputs:

```bash theme={null}
# Check if packages are installed
which htop jq

# Check if files were created
cat /opt/config.yml

# Check runcmd output
cat /tmp/ready.txt
```

## Limitations

* Cloud-init runs once on first boot only
* Maximum script size varies by vendor (generally 16KB-64KB)
* `#cloud-config` `packages` directive requires `apt` (Ubuntu/Debian images)
* Some vendors may have delays between instance readiness and cloud-init completion