> ## 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.

# Writing gliss.yaml

> How your AI asks Gliss for what an app needs, and what it must leave out.

Your AI writes `gliss.yaml` at the root of the repository. You rarely need to edit it yourself, but knowing its shape helps you review what your AI asked for.

```yaml gliss.yaml theme={null}
apiVersion: gliss.dev/v1
app: expense-tracker
owner: dana@customer.com
components:
  web: { build: ./frontend, port: 8080, runtime: vite }
  api: { build: ./backend, port: 8000, runtime: python, migrate: "alembic upgrade head" }
capabilities:
  database: { type: postgres, size: small }
  auth:     { type: sso, audience: org }
  hostname: { type: hostname, name: expenses }
  secrets:  { SALESFORCE_TOKEN: credential }
config:
  LOG_LEVEL: info
egress: [login.salesforce.com]
```

## The parts

* **`app` and `owner`**: the app's name, which becomes part of its addresses, and the owner's work email.
* **`components`**: each one is a folder with a Dockerfile that becomes a container. Give it a `port` if it serves web traffic.
* **`capabilities`**: what the app needs from the platform. Each key is a name your AI chooses, and `type` picks the catalog entry. See the capability pages under [Capabilities](https://docs.glissando.dev/build/capabilities/postgres.md).
* **`config`**: plain, non-secret settings the app reads as environment variables.
* **`egress`**: the outside services the app may call. Everything else is blocked.
* **`stages`**: optional per-stage overrides. See [Preview, Beta and Live](https://docs.glissando.dev/build/stages.md).

## What never goes in gliss.yaml

* **Secret values.** Declare the name and type under `capabilities.secrets`; a person sets the value through a [secret request](https://docs.glissando.dev/build/secrets-and-mock-mode.md).
* **Scripts, kubectl, Helm charts or Kubernetes objects.** Charts belong to the catalog. Fields such as `env`, `helm` and `manifests` are refused.
* **Database passwords or AWS keys.** The platform creates them and hands them to the app.

## When Gliss says no

If `gliss.yaml` asks for something your catalog does not offer, Gliss refuses it before anything is built. Every problem is listed at once, with how to fix it:

```text theme={null}
capabilities.cache: type 'redis' is not offered in catalog acme@3; offered: postgres, bucket, hostname, sso
```

Your AI reads the refusal, fixes the file and tries again. See [Refusal messages](https://docs.glissando.dev/reference/refusals.md) for every case, and the [gliss.yaml reference](https://docs.glissando.dev/reference/gliss-yaml.md) for every field.


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