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

> ## Agent Instructions
> If you are an AI assistant asked to build, change or ship a Gliss app, read the For AI agents page first (/for-ai-agents.md on this site) and follow its steps.
> Inside an app's folder, the app's own AGENTS.md is the authority; `gliss guide` prints it. Never ask the user for a secret's value.

# Catalog

> The menu your IT team publishes: what apps may ask for, how much of it, and what Publish requires.

The catalog is the menu IT publishes for one Gliss organisation or cluster: which capabilities, sizes and runtimes apps may ask for, how many of each, who an app may be shown to, how Preview and Beta behave when idle, and what Publish to Live requires. Every gliss.yaml is checked against it before anything is built, and refusals name it as \<metadata.name>@\<metadata.revision>, for example acme\@3. Charts, chart versions and the Postgres major version are not in the catalog: they are pinned by the platform release, which IT approves separately. Some values are fixed and appear here as constants so that IT can see them; changing them needs a new contract version, not an edit. Email (SES), connections to SaaS accounts and managed Postgres (RDS) are not offered in v1.

## Sections

### metadata

**name** `string` *required*

Short name of the catalog, usually the customer, for example acme. Refusals cite it.

**revision** `integer` *required*

Increases by one on every published edit. Refusals cite it (acme\@3), so a builder's LLM can tell which menu it was checked against. The control plane rejects a document whose revision is not greater than the one it holds.

At least 1.

**description** `string`

At most 500 characters.

### capabilities

Every capability type gliss.yaml v1 can name, and whether this catalog offers it. A type that is not offered is refused with the list of offered ones. Each entry carries the catalog entry's own version (postgres\@1); a platform release that deprecates a version raises a capability-version-eol finding.

**postgres** `object` *required*

**fields**

**offered** `boolean` *required*

**version** `integer` *required*

At least 1.

**sizes** `object` *required*

Live database sizes this catalog offers. The instance counts are fixed: small is one instance, standard is two for high availability. IT can remove a size and set the storage. Preview and Beta always use the shared stage Postgres.

**fields**

**small** `object`

**fields**

**instances** `1` *required*

**storage** `string` *required*

**standard** `object`

**fields**

**instances** `2` *required*

**storage** `string` *required*

**defaultSize** `small | standard` *required*

Size used when gliss.yaml leaves size out. Must be one of the offered sizes.

**maxPerApp** `integer` *required*

From 1 to 3.

**majors** `object` *required*

Postgres major versions the platform release supports, each with the extensions an app may ask for. The platform release decides which major a database runs; this list says what is allowed on each.

**defaultMajor** `string` *required*

The major new databases get, and the one gliss.yaml extensions are checked against. Must be a key of majors.

**redis** `object` *required*

An in-cluster Redis cache per stage. Not durable.

**fields**

**offered** `boolean` *required*

**version** `integer` *required*

At least 1.

**sizes** `object` *required*

**fields**

**small** `object`

**fields**

**memory** `string` *required*

**standard** `object`

**fields**

**memory** `string` *required*

**defaultSize** `small | standard` *required*

**maxPerApp** `integer` *required*

From 1 to 3.

**bucket** `object` *required*

**fields**

**offered** `boolean` *required*

**version** `integer` *required*

At least 1.

**maxPerApp** `integer` *required*

From 1 to 10.

**hostname** `object` *required*

**fields**

**offered** `boolean` *required*

**version** `integer` *required*

At least 1.

**maxPerApp** `1` *required*

An app has one Live address in v1.

**reservedNames** `string[]` *required*

First labels no app may take. Must include secrets; preview and beta are reserved by the stage gateway and are always refused whatever this list says. IT can add more, such as www or mail.

**If refused:** reservedNames must include secrets, which the secret-intake page uses.

**sso** `object` *required*

**fields**

**offered** `boolean` *required*

**version** `integer` *required*

At least 1.

**maxPerApp** `1` *required*

**audiences** `array` *required*

Live audiences an app may ask for. org: the whole organisation. group: named identity-provider groups (group:\<name>). public: anyone; even when allowed here, publishing a public app needs IT approval unless publish.approval says otherwise.

**healer** `object` *required*

**fields**

**offered** `boolean` *required*

**version** `integer` *required*

At least 1.

**maxPerApp** `1` *required*

**levels** `array` *required*

Healer levels apps may ask for. auto is allowed only when maintenance.tier is managed. Usually a prefix of observe, propose, auto.

**defaultEnabled** `false` *required*

Maintenance is never on unless the app asks for it in gliss.yaml.

### secrets

Limits on declared secrets and secret requests.

**maxPerApp** `integer` *required*

From 0 to 100.

**guestLinks** `boolean` *required*

Whether a request link may be forwarded to a guest outside the organisation. Guests may only ever set credential secrets; endpoint secrets always need a signed-in member.

**requestLinkTtlHours** `integer` *required*

How long a single-use request link works. sets 72 hours; IT may shorten it, not lengthen it.

From 1 to 72.

### config

Limits on gliss.yaml config values, per stage after overrides are applied.

**maxPerApp** `integer` *required*

How many config values one stage of an app may have.

From 0 to 100.

**maxTotalBytes** `integer` *required*

Total size of one stage's config, counting names and values.

From 1024 to 65536.

### egress

Rules for the hostnames apps list under gliss.yaml egress. The platform enforces the result with network policy.

**maxPerApp** `integer` *required*

From 0 to 50.

**allowWildcards** `boolean` *required*

Whether an app may list \*.example.com.

**allowIpAddresses** `boolean` *required*

Whether an app may list IP addresses or ranges.

**approvedDomains** `array | null` *required*

null: any public hostname not blocked is approved. A list: only these hostnames, or hostnames under a listed \*.domain, are approved.

**blockedDomains** `string[]` *required*

Hostnames, or \*.domain patterns, no app may list.

### runtimes

Runtimes a component may name. A runtime with a dev variant reloads in Preview through Git-backed sync; one without rebuilds on each change.

Each entry in `runtimes` has:

**name** `string` *required*

**devVariant** `any` *required*

### quotas

**componentsPerApp** `integer` *required*

From 1 to 20.

**previewsPerBuilder** `integer`

Optional cap on live Preview namespaces per builder, across apps.

At least 1.

**namespace** `object` *required*

The ResourceQuota each stage namespace gets.

**fields**

**preview** `object` *required*

**fields**

**pods** `integer` *required*

At least 1.

**cpu** `string` *required*

**memory** `string` *required*

**containerCpu** `string` *required*

**containerMemory** `string` *required*

**beta** `object` *required*

**fields**

**pods** `integer` *required*

At least 1.

**cpu** `string` *required*

**memory** `string` *required*

**containerCpu** `string` *required*

**containerMemory** `string` *required*

**live** `object` *required*

**fields**

**pods** `integer` *required*

At least 1.

**cpu** `string` *required*

**memory** `string` *required*

**containerCpu** `string` *required*

**containerMemory** `string` *required*

### stages

Lifecycle defaults per stage. Scale-to-zero for Preview and Beta is mandatory and cannot be switched off, only tuned.

**preview** `object` *required*

**fields**

**scaleToZeroAfterIdleMinutes** `integer` *required*

From 5 to 240. Default: `30`.

**deleteAfterIdleDays** `integer` *required*

From 1 to 30. Default: `7`.

**secretsDefault** `mock | request` *required*

Default: `"mock"`.

**beta** `object` *required*

**fields**

**scaleToZeroAfterIdleMinutes** `integer` *required*

From 5 to 240. Default: `30`.

**secretsDefault** `mock | request` *required*

Default: `"request"`.

**live** `object` *required*

**fields**

**secretsDefault** `request` *required*

Every secret declared for Live is requested, and must be set before Publish.

### publish

What Publish (Beta to Live) requires. The gates marked const are fixed. The approval policy is the organisation default; IT can tighten or loosen it per app in the console.

**gates** `object` *required*

**fields**

**ciGreen** `true` *required*

**betaHealthyMinutes** `integer` *required*

How long Beta must have run the release and stayed healthy before it can be published. Default 10 minutes; IT can change it.

From 0 to 10080. Default: `10`.

**noBlockingFindings** `true` *required*

**liveSecretsSet** `true` *required*

**approval** `object` *required*

**fields**

**default** `owner | it` *required*

owner: the app owner publishes their own app. it: every Publish needs IT approval.

**itApprovalWhen** `object` *required*

Cases that need IT approval even when the default is owner. defaults all three to true.

**fields**

**publicAudience** `boolean` *required*

The app's audience is public.

**endpointSecrets** `boolean` *required*

The app declares an endpoint secret.

**customLevel** `boolean` *required*

The project is at level 2 (custom charts).

### levels

Which levels projects may use. Level 0 (gliss.yaml only) is always on.

**composed** `object` *required*

Level 1: gliss.yaml plus garden.yml using Gliss action types. Validated against this same catalog.

**fields**

**offered** `boolean` *required*

**custom** `object` *required*

Level 2: the team's own charts, checked against IT's policy instead of the catalog. Post-MVP. Off by default, and enabled per project by IT or a system owner.

**fields**

**offered** `boolean` *required*

**enabledProjects** `string[]` *required*

Repositories (\<organisation>/\<repository>) that may use level 2. Must be empty while offered is false.

### maintenance

Which maintenance tier the customer has. Set from the subscription; IT cannot raise it by editing the catalog.

**tier** `self-maintained | managed` *required*

self-maintained: IT's LLM or people act on findings. managed: Gliss maintenance bots do. The healer level auto needs managed.

## Example

The example catalog `acme@3`, which every `gliss.yaml` example in these docs is checked against.

```json example.catalog.json theme={null}
{
  "apiVersion": "gliss.dev/catalog/v1",
  "kind": "Catalog",
  "metadata": {
    "name": "acme",
    "revision": 3,
    "description": "Example catalog for a design partner at the MVP. The gliss.yaml fixtures are checked against it."
  },
  "capabilities": {
    "postgres": {
      "offered": true,
      "version": 1,
      "sizes": {
        "small": {
          "instances": 1,
          "storage": "10Gi"
        },
        "standard": {
          "instances": 2,
          "storage": "20Gi"
        }
      },
      "defaultSize": "small",
      "maxPerApp": 1,
      "majors": {
        "17": {
          "extensions": ["vector", "pg_trgm", "uuid-ossp", "pgcrypto", "citext", "hstore"]
        },
        "16": {
          "extensions": ["vector", "pg_trgm", "uuid-ossp", "pgcrypto", "citext"]
        }
      },
      "defaultMajor": "17"
    },
    "redis": {
      "offered": true,
      "version": 1,
      "sizes": {
        "small": {
          "memory": "256Mi"
        },
        "standard": {
          "memory": "1Gi"
        }
      },
      "defaultSize": "small",
      "maxPerApp": 1
    },
    "bucket": {
      "offered": true,
      "version": 1,
      "maxPerApp": 3
    },
    "hostname": {
      "offered": true,
      "version": 1,
      "maxPerApp": 1,
      "reservedNames": ["secrets", "www", "mail"]
    },
    "sso": {
      "offered": true,
      "version": 1,
      "maxPerApp": 1,
      "audiences": ["org", "group", "public"]
    },
    "healer": {
      "offered": true,
      "version": 1,
      "maxPerApp": 1,
      "levels": ["observe", "propose"],
      "defaultEnabled": false
    }
  },
  "secrets": {
    "maxPerApp": 20,
    "guestLinks": true,
    "requestLinkTtlHours": 72
  },
  "config": {
    "maxPerApp": 50,
    "maxTotalBytes": 16384
  },
  "egress": {
    "maxPerApp": 20,
    "allowWildcards": false,
    "allowIpAddresses": false,
    "approvedDomains": null,
    "blockedDomains": ["pastebin.com", "*.ngrok.io", "*.ngrok-free.app", "transfer.sh"]
  },
  "runtimes": [
    {
      "name": "python",
      "devVariant": {
        "reload": "uvicorn --reload",
        "reinstallOn": ["requirements.txt", "pyproject.toml"]
      }
    },
    {
      "name": "vite",
      "devVariant": {
        "reload": "Vite hot module replacement",
        "reinstallOn": ["package.json"]
      }
    },
    {
      "name": "node",
      "devVariant": null
    },
    {
      "name": "go",
      "devVariant": null
    },
    {
      "name": "static",
      "devVariant": null
    }
  ],
  "quotas": {
    "componentsPerApp": 6,
    "previewsPerBuilder": 5,
    "namespace": {
      "preview": {
        "pods": 4,
        "cpu": "2",
        "memory": "4Gi",
        "containerCpu": "1",
        "containerMemory": "1Gi"
      },
      "beta": {
        "pods": 8,
        "cpu": "4",
        "memory": "8Gi",
        "containerCpu": "2",
        "containerMemory": "2Gi"
      },
      "live": {
        "pods": 8,
        "cpu": "4",
        "memory": "8Gi",
        "containerCpu": "2",
        "containerMemory": "2Gi"
      }
    }
  },
  "stages": {
    "preview": {
      "scaleToZeroAfterIdleMinutes": 30,
      "deleteAfterIdleDays": 7,
      "secretsDefault": "mock"
    },
    "beta": {
      "scaleToZeroAfterIdleMinutes": 30,
      "secretsDefault": "request"
    },
    "live": {
      "secretsDefault": "request"
    }
  },
  "publish": {
    "gates": {
      "ciGreen": true,
      "betaHealthyMinutes": 10,
      "noBlockingFindings": true,
      "liveSecretsSet": true
    },
    "approval": {
      "default": "owner",
      "itApprovalWhen": {
        "publicAudience": true,
        "endpointSecrets": true,
        "customLevel": true
      }
    }
  },
  "levels": {
    "composed": {
      "offered": true
    },
    "custom": {
      "offered": false,
      "enabledProjects": []
    }
  },
  "maintenance": {
    "tier": "self-maintained"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.