# Cloud Actions

The `cloud` family orchestrates **Sovrium Cloud** tenant apps — provisioning their databases, booting their processes, attaching ingress routes, and tearing them down. Five operators. These actions are **gated**: they only run when the host process is started with the `SOVRIUM_CLOUD_MODE` env flag.

| Operator       | Props                  | Description                                                     |
| -------------- | ---------------------- | --------------------------------------------------------------- |
| `provision-db` | `dbName`               | Provision a logical database for a tenant (e.g. `tenant_acme`). |
| `spawn-app`    | `appSlug`, `configRef` | Boot a tenant app process from a validated config reference.    |
| `route-add`    | `domain`, `port`       | Attach an ingress route (domain → port) to a tenant app.        |
| `disable-app`  | `appSlug`              | Stop a tenant app while preserving its data.                    |
| `destroy-app`  | `appSlug`              | Tear down a tenant app and drop its data.                       |

| Prop        | Description                                                                         |
| ----------- | ----------------------------------------------------------------------------------- |
| `appSlug`   | Tenant app slug — stable lowercase-kebab identifier (e.g. `acme-crm`). Templatable. |
| `dbName`    | Logical tenant database name (e.g. `tenant_acme`). Templatable.                     |
| `configRef` | Reference to the validated tenant config to boot (id / row ref / URL). Templatable. |
| `domain`    | Route domain to attach — a bare host (e.g. `acme.sovrium.app`). Templatable.        |
| `port`      | Tenant app listening port the route targets (1–65535).                              |

```yaml
# Onboard a new tenant when a signup record is approved
automations:
  - name: onboard-tenant
    trigger: { type: record, table: tenant_signups, events: [update] }
    actions:
      - name: db
        type: cloud
        operator: provision-db
        props: { dbName: 'tenant_{{trigger.data.slug}}' }
      - name: boot
        type: cloud
        operator: spawn-app
        props: { appSlug: '{{trigger.data.slug}}', configRef: '{{trigger.data.config_ref}}' }
      - name: route
        type: cloud
        operator: route-add
        props: { domain: '{{trigger.data.slug}}.sovrium.app', port: 3000 }
```

:::callout
**Gated, never schema-controlled.** Cloud actions are accepted by the schema everywhere, but a config that uses them is **rejected at validate time** unless the host runs with the `SOVRIUM_CLOUD_MODE` process-env gate. The gate is a host concern — never a schema field. Use these actions only in a Sovrium Cloud control-plane app.
:::

## Related Pages

- [Actions Overview](/en/docs/automation-actions-overview) — base props and the family map.
- [Triggers](/en/docs/automation-triggers) — record/manual triggers that drive tenant onboarding.
- [Environment Variables](/en/docs/automation-env-vars) — operator-controlled host env (distinct from `app.env`).