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

# Spec format reference

> Complete reference for the stack-spec.yaml specification format

The `stack-spec.yaml` file (also accepted as `kombination.yaml`) is your deployment contract. This reference documents all available fields and their valid values.

## Top-level fields

| Field      | Type         | Required | Description                                              |
| ---------- | ------------ | -------- | -------------------------------------------------------- |
| `version`  | string       | Yes      | Spec version (currently `"1.0"`)                         |
| `stackkit` | string       | Yes      | StackKit to use (`base-kit`, `ha-kit`, `modern-homelab`) |
| `meta`     | object       | Yes      | Metadata about your homelab                              |
| `nodes`    | array        | Yes      | Server definitions                                       |
| `services` | array/object | Yes      | Services to deploy                                       |

## Meta section

```yaml theme={null}
meta:
  name: my-homelab          # Required: unique name
  domain: home.example.com  # Required: base domain
  email: you@example.com    # Optional: for Let's Encrypt
```

| Field    | Type   | Required | Description                                       |
| -------- | ------ | -------- | ------------------------------------------------- |
| `name`   | string | Yes      | Unique homelab identifier (alphanumeric, hyphens) |
| `domain` | string | Yes      | Base domain for services                          |
| `email`  | string | No       | Email for TLS certificate generation              |

## Nodes section

```yaml theme={null}
nodes:
  - name: server-1
    type: hypervisor
    connection:
      host: 192.168.1.100
      user: root
      ssh_key: ~/.ssh/id_ed25519
    resources:
      cpu: 4
      memory: 16384
```

### Node fields

| Field        | Type   | Required | Description                                     |
| ------------ | ------ | -------- | ----------------------------------------------- |
| `name`       | string | Yes      | Unique node identifier                          |
| `type`       | string | Yes      | Node type: `hypervisor`, `docker`, `bare-metal` |
| `connection` | object | Yes      | How to reach this node                          |
| `resources`  | object | No       | Resource constraints                            |

### Connection fields

| Field     | Type   | Required | Description                |
| --------- | ------ | -------- | -------------------------- |
| `host`    | string | Yes      | IP address or hostname     |
| `port`    | int    | No       | SSH port (default: `22`)   |
| `user`    | string | No       | SSH user (default: `root`) |
| `ssh_key` | string | No       | Path to SSH private key    |

## Services section

Services can be specified as a simple list or as detailed objects:

```yaml theme={null}
# Simple: enable with defaults
services:
  - traefik
  - immich
  - vaultwarden

# Detailed: customize per service
services:
  traefik:
    enabled: true
    config:
      dashboard: true
      log_level: INFO
  immich:
    enabled: true
    config:
      upload_limit: 10GB
```

## Environment variables

Services support environment variable overrides:

```yaml theme={null}
services:
  immich:
    enabled: true
    env:
      UPLOAD_LOCATION: /data/photos
      DB_PASSWORD: "${IMMICH_DB_PASSWORD}"
```

<Warning>
  Never hardcode secrets in your `stack-spec.yaml`. Use environment variable references with `${VAR_NAME}` syntax.
</Warning>

## Validation

Validate your spec before deployment:

```bash theme={null}
stackkit validate
```

The validator checks:

* Required fields are present
* Types match the CUE schema
* Node connections are reachable
* Service dependencies are satisfied
* No port conflicts exist

## Example: Complete spec

```yaml theme={null}
version: "1.0"
stackkit: base-kit

meta:
  name: family-cloud
  domain: home.example.com
  email: admin@example.com

nodes:
  - name: main-server
    type: docker
    connection:
      host: 192.168.1.100
      user: deploy
      ssh_key: ~/.ssh/id_ed25519

services:
  traefik:
    enabled: true
    config:
      dashboard: true
  vaultwarden:
    enabled: true
  immich:
    enabled: true
    config:
      upload_limit: 50GB
  homepage:
    enabled: true
```