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

# host

> Provision and operate the current Linux VM with sitectl's managed-host runtime.

`sitectl host` exposes the same tested host-runtime operations used by Cloud
Compose so another provisioning system can assemble and operate a compatible
Linux VM without reimplementing them in shell.

Unlike commands that target a saved sitectl context, `host` acts on the machine
where the command runs. Connect to the VM first or invoke it over SSH:

```bash theme={null}
ssh root@compose.example.org sitectl host diagnostics status
ssh root@compose.example.org sitectl host apps validate
```

Most provisioning operations require root. They also expect the managed-host
layout to have been staged already: a validated `/home/cloud-compose/.env`, an
application manifest, systemd units, and the declared persistent disks. The
commands are composable provisioning primitives, not a one-command installer
for an arbitrary server.

Start with the read-only diagnostics and manifest validation commands. Before
changing filesystems, credentials, backup state, firewall rules, or systemd
units, confirm the target VM and review the command's flags.

## Reference

Provision and operate the current VM using sitectl's managed-host layout.

These commands run on the target host rather than through a saved sitectl context.
They manage host filesystems, runtime tools, application manifests, systemd units,
backups, credentials, and diagnostics. Most provisioning operations require root
and an existing host environment file and application manifest.

```bash theme={null}
sitectl host <command>
```

## Applications

Operate the host application manifest

```bash theme={null}
sitectl host apps <command>
```

Validate the host application manifest

```bash theme={null}
sitectl host apps validate
```

Converge managed project ownership and modes

```bash theme={null}
sitectl host apps converge-filesystems
```

| Flag        | Default         | Description                                         |
| ----------- | --------------- | --------------------------------------------------- |
| `--account` | `cloud-compose` | Runtime account that owns managed application files |

Prepare verified application source checkouts

```bash theme={null}
sitectl host apps prepare
```

| Flag    | Default | Description                                 |
| ------- | ------- | ------------------------------------------- |
| `--app` |         | Prepare only the named manifest application |

Run a validated lifecycle for managed applications

```bash theme={null}
sitectl host apps lifecycle init|up|down|rollout
```

| Flag     | Default                                         | Description                             |
| -------- | ----------------------------------------------- | --------------------------------------- |
| `--app`  |                                                 | Run only the named manifest application |
| `--lock` | `/mnt/disks/data/.cloud-compose-lifecycle.lock` | Host lifecycle lock file                |

## Runtime and host configuration

Configure the managed host account and runtime paths

```bash theme={null}
sitectl host configure
```

Prepare and persist managed host filesystems

```bash theme={null}
sitectl host filesystems
```

| Flag               | Default                         | Description                                                        |
| ------------------ | ------------------------------- | ------------------------------------------------------------------ |
| `--automount-wait` | `1m0s`                          | Maximum wait for provider automount activity                       |
| `--data-device`    |                                 | Block device dedicated to persistent application data              |
| `--data-mount`     | `/mnt/disks/data`               | Mount target for persistent application data                       |
| `--device-wait`    | `10m0s`                         | Maximum wait for each declared block device                        |
| `--fresh-identity` |                                 | Identity recorded only when the data disk is first formatted       |
| `--fstab`          | `/etc/fstab`                    | Filesystem table reconciled with the managed mount block           |
| `--fstab-lock`     | `/run/cloud-compose-fstab.lock` | Lock serializing filesystem table updates                          |
| `--overlay-device` |                                 | Optional read-only production volume block device                  |
| `--overlay-mount`  | `/mnt/disks/prod-readonly`      | Mount target for the optional read-only production disk            |
| `--ready-marker`   |                                 | Root-owned marker published after every required mount is verified |
| `--systemd-dir`    | `/etc/systemd/system`           | Directory containing provider-generated mount units                |
| `--volumes-device` |                                 | Block device dedicated to Docker volume data                       |
| `--volumes-mount`  | `/mnt/disks/volumes`            | Mount target for Docker volume data                                |

Mount declared read-only production volume overlays

```bash theme={null}
sitectl host overlays
```

| Flag             | Default                    | Description                                                    |
| ---------------- | -------------------------- | -------------------------------------------------------------- |
| `--lower-root`   | `/mnt/disks/prod-readonly` | Read-only production volume root                               |
| `--reset`        | `false`                    | Unmount and clear the writable overlay layer before remounting |
| `--volume`       | `[]`                       | Docker volume name to overlay; may be repeated                 |
| `--volumes-root` | `/mnt/disks/volumes`       | Writable Docker volume root                                    |

Install verified Docker Compose and Buildx CLI plugins

```bash theme={null}
sitectl host docker-plugins
```

| Flag                | Default                             | Description                    |
| ------------------- | ----------------------------------- | ------------------------------ |
| `--buildx-version`  | `v0.35.0`                           | Docker Buildx release version  |
| `--compose-version` | `v5.3.1`                            | Docker Compose release version |
| `--directory`       | `/usr/local/lib/docker/cli-plugins` | Docker CLI plugin directory    |

Install the managed sitectl runtime

```bash theme={null}
sitectl host runtime <command>
```

Install the complete verified sitectl package and artifact set

```bash theme={null}
sitectl host runtime install
```

| Flag                  | Default                                             | Description                          |
| --------------------- | --------------------------------------------------- | ------------------------------------ |
| `--artifact-manifest` | `/home/cloud-compose/managed-runtime-artifacts.tsv` | Root-owned managed artifact manifest |
| `--published-dir`     | `/home/cloud-compose/bin`                           | Published managed command directory  |
| `--state-dir`         | `/mnt/disks/data/libops-managed`                    | Root-owned managed runtime state     |

Install verified managed host artifacts

```bash theme={null}
sitectl host artifacts <command>
```

Install every artifact in the root-owned manifest

```bash theme={null}
sitectl host artifacts install
```

| Flag          | Default                                             | Description                            |
| ------------- | --------------------------------------------------- | -------------------------------------- |
| `--manifest`  | `/home/cloud-compose/managed-runtime-artifacts.tsv` | Root-owned managed artifact manifest   |
| `--state-dir` | `/mnt/disks/data/libops-managed/artifacts`          | Managed artifact audit state directory |

Enforce the managed host runtime trust boundary

```bash theme={null}
sitectl host security <command>
```

Normalize and verify managed runtime ownership and modes

```bash theme={null}
sitectl host security secure-runtime
```

| Flag     | Default               | Description               |
| -------- | --------------------- | ------------------------- |
| `--home` | `/home/cloud-compose` | Managed host runtime home |

## Environment files

Manage host-owned environment files

```bash theme={null}
sitectl host env <command>
```

Atomically set a host environment value

```bash theme={null}
sitectl host env set FILE NAME VALUE
```

Atomically set a managed Compose environment override

```bash theme={null}
sitectl host env compose-set FILE NAME VALUE
```

Reconcile application environment data into a Compose dotenv file

```bash theme={null}
sitectl host env compose-sync FILE JSON_FILE
```

## Services and readiness

Converge Cloud Compose systemd services

```bash theme={null}
sitectl host systemd <command>
```

Start host bootstrap when its readiness marker is absent

```bash theme={null}
sitectl host systemd ensure-bootstrap
```

| Flag        | Default                                     | Description                        |
| ----------- | ------------------------------------------- | ---------------------------------- |
| `--marker`  | `/var/lib/cloud-compose/bootstrap-complete` | Durable bootstrap readiness marker |
| `--timeout` | `3h0m0s`                                    | Maximum wait for host bootstrap    |

Start a oneshot unit and wait for its terminal state

```bash theme={null}
sitectl host systemd start-wait UNIT
```

| Flag        | Default  | Description                          |
| ----------- | -------- | ------------------------------------ |
| `--timeout` | `3h0m0s` | Maximum wait for the oneshot service |

Remove retired Cloud Compose systemd units

```bash theme={null}
sitectl host systemd migrate-legacy
```

Manage Cloud Compose readiness markers

```bash theme={null}
sitectl host marker <command>
```

Check whether a readiness marker is safe and valid

```bash theme={null}
sitectl host marker valid PATH
```

Publish a root-owned readiness marker

```bash theme={null}
sitectl host marker publish PATH
```

Validate and consume a fresh-filesystem marker

```bash theme={null}
sitectl host marker consume-fresh PATH IDENTITY
```

Report whether application initialization is required

```bash theme={null}
sitectl host marker app-status DURABLE CURRENT_BOOT
```

Require durable or current-boot application initialization

```bash theme={null}
sitectl host marker require-initialized DURABLE CURRENT_BOOT
```

Initialize or check the managed Vault Agent

```bash theme={null}
sitectl host vault-agent init|assert-ready
```

Manage Vault Agent sink-token readiness

```bash theme={null}
sitectl host vault-readiness prepare|wait|clear
```

| Flag             | Default                                | Description                                 |
| ---------------- | -------------------------------------- | ------------------------------------------- |
| `--ready-marker` | `/run/cloud-compose/vault-agent.ready` | Current-boot Vault Agent readiness marker   |
| `--safe-dir`     | `/mnt/disks/data/vault`                | Root-only Vault Agent state directory       |
| `--timeout`      | `1m0s`                                 | Maximum wait for the Vault Agent sink token |
| `--token`        | `/mnt/disks/data/vault/token`          | Dedicated Vault Agent sink-token path       |

Run the validated managed rollout service

```bash theme={null}
sitectl host rollout-serve
```

## Backups and maintenance

Run managed backup and recovery operations

```bash theme={null}
sitectl host backup <command>
```

Create daily MariaDB recovery artifacts

```bash theme={null}
sitectl host backup mariadb
```

Hand complete recovery coverage to the off-host driver

```bash theme={null}
sitectl host backup offhost
```

Prove the latest off-host backup in disposable recovery

```bash theme={null}
sitectl host backup restore-test
```

Run managed host maintenance

```bash theme={null}
sitectl host maintenance <command>
```

Prune old unused Docker data

```bash theme={null}
sitectl host maintenance docker-prune
```

## GCP host operations

Configure GCP host and container metadata isolation

```bash theme={null}
sitectl host metadata-firewall [full|pre-docker]
```

Rotate managed GCP service-account keys

```bash theme={null}
sitectl host keys <command>
```

Converge every enabled managed service-account key

```bash theme={null}
sitectl host keys daily
```

Operate app service-account credentials

```bash theme={null}
sitectl host keys app <command>
```

rotate app service-account credentials

```bash theme={null}
sitectl host keys app rotate
```

rollback app service-account credentials

```bash theme={null}
sitectl host keys app rollback
```

retire app service-account credentials

```bash theme={null}
sitectl host keys app retire
```

Operate internal service-account credentials

```bash theme={null}
sitectl host keys internal <command>
```

rotate internal service-account credentials

```bash theme={null}
sitectl host keys internal rotate
```

rollback internal service-account credentials

```bash theme={null}
sitectl host keys internal rollback
```

## Diagnostics

Inspect managed host provisioning state

```bash theme={null}
sitectl host diagnostics <command>
```

Print managed host status

```bash theme={null}
sitectl host diagnostics status
```

Print the bootstrap state

```bash theme={null}
sitectl host diagnostics state
```

Print managed host dump

```bash theme={null}
sitectl host diagnostics dump
```