Reference

cloudgrid.yaml Full Schema

# ─── Identity ─────────────────────────────────────────────────
name: <slug>                          # Required. 2-42 chars, lowercase a-z0-9-
description: <text>                   # Optional. Max 280 chars
icon: <emoji-or-text>                 # Optional. Max 64 chars

# ─── Domains & Routing ────────────────────────────────────────
custom_domains:                       # Optional. List of FQDNs
  - dashboard.example.com
expose: true                          # Optional. Default true. false = internal-only
probe:                                # Optional. Health probe override
  path: /healthz
  expected: "200"

# ─── Services ─────────────────────────────────────────────────
services:                             # Required. Map of service-name to config
  <service-name>:
    type: node|nextjs|python|static|cron    # Required
    lang: javascript|typescript             # Optional. node type only
    path: /<url-path>|false                 # Optional. false = no public route
    port: <1-65535>                         # Optional. Default 8080
    source:                                 # Optional. Custom source path
      path: <relative-dir>
    node_version: "18"|"20"|"22"|"24"       # Optional. static/build only. Default "22"
    build:                                  # Optional. Static type with build step
      command: "npm run build"
      output: "dist"
      env:
        VITE_API_URL: "https://..."
    env:                                    # Optional. Runtime env vars
      KEY: VALUE
    health: true|false|"/health"            # Optional. HTTP health probe
    schedule: "<cron-expr>"                 # Required for cron type
    run: "job"|"http://..."|"https://..."   # Cron only. Default "job"
    timezone: UTC|EST|PST                   # Cron only. Default UTC
    depends_on: [<svc-name>, ...]           # Optional. Sibling dependencies
    persist:                                # Optional. File persistence (granular)
      - name: "uploads"
        path: "/app/uploads"
        size: "2Gi"

# ─── Dependencies ─────────────────────────────────────────────
requires:                             # Optional. Shared resources
  - db                                # Org-tier MongoDB (MONGODB_URL injected)
  - redis                            # Org-tier Redis (REDIS_URL injected)
  - ai                               # Runtime Gateway (RUNTIME_GATEWAY_URL injected)
  - n8n                              # N8N (N8N_WEBHOOK_URL injected)
  - { db: private }                   # Entity-namespace MongoDB
  - { redis: private }               # Entity-namespace Redis
  - { db: external, secret: KEY }     # External MongoDB (KEY from vault)
  - { redis: external, secret: KEY }  # External Redis (KEY from vault)
  - { external_db: native, port: 5432 }  # Native egress (Postgres, MySQL, etc.)
  - { gcp: { services: [bigquery, pubsub, storage] } }  # GCP services

# ─── Secrets ───────────────────────────────────────────────────
vault:                                # Optional. Env var to vault item mapping
  MY_SECRET_KEY: vault-item-key

# ─── Persistence (entity-level) ───────────────────────────────
persist: true                         # Optional. Simple 1Gi volume
# persist: { size: "5Gi" }           # Optional. Custom size

# ─── Deploy order ─────────────────────────────────────────────
deploy_order: auto                    # Optional. Default auto. When no service declares
                                      # depends_on:, the platform sequences data stores →
                                      # backend → frontend on first deploy. off = disable

# ─── Notifications ────────────────────────────────────────────
notify: true                          # Optional. Default true. Opt out of deploy Slack

# ─── Inter-App Communication ──────────────────────────────────
calls:                                # Optional. Outbound dependencies
  - your-org:other-app
callers:                              # Optional. Inbound caller policy
  policy: auto|manual                 # Default: manual
  scope: org|space|explicit           # Default: org
  fallback: deny|warn                 # Default: deny
  allowed_apps:                       # Required if scope: explicit
    - your-org:calling-app

# ─── Connectors & Hooks ───────────────────────────────────────
connectors:                           # Optional. External integrations
  - id: org-slack
    target: system|org
    channel: "#deploys"

hooks:                                # Optional. Outbound event hooks
  - on: release.published|deploy.failed|feedback.received|entity.created
    via: <connector-id>
    template: "{entity} {error}"
    channel: "#override"

triggers:                             # Optional. Inbound event routes
  - from: <connector-id>
    event: message
    channel: "#bot-commands"
    route: /webhooks/slack

# ─── Dev Configuration ────────────────────────────────────────
dev:                                  # Optional. Dev Grid config
  snapshot:
    mask:                             # Fields to redact in dev snapshots
      - users.email
      - users.password

# ─── Agent Block ───────────────────────────────────────────────
agent:                                # Optional. Makes entity an agent
  purpose: <text>
  schedule: <cron-expression>
  memory:
    collection: <name>
    retention: <duration>
  budget:
    tokens_per_month: <number>
    hard_stop: true|false

Validation rules

• Name: ^[a-z][a-z0-9-]{0,40}[a-z0-9]$ (2-42 chars, no leading/trailing hyphen)
• Reserved names: default, kube-system, kube-public, n8n, sharedgrid, cloudgrid, cloudgrid-system, istio-system, cert-manager, ingress-nginx, monitoring
• Port: Integer 1-65535 (default 8080)
• Env var keys: ^[A-Z_][A-Z0-9_]*$
• Vault keys: ^[A-Z][A-Z0-9_]*$
• Persist PVC names: ^[a-z]([a-z0-9-]{0,38}[a-z0-9])?$ (1-40 chars)
• Persist mount paths: Absolute paths, cannot be /, /proc, /sys, /dev
• Connector IDs: ^[a-z][a-z0-9-]{1,38}[a-z0-9]$ (3-40 chars)

Reserved environment variables

The following keys cannot be set via grid env set or services.<svc>.env:

PORT, APP_NAME, SERVICE_NAME, NODE_ENV, MONGODB_URL, REDIS_URL, RUNTIME_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_* (any prefix), CLOUDGRID_PERSIST_PATH, CLOUDGRID_CALLER_TOKEN_*.