Declare the environment your code reads

Your tools' code, and the libraries it imports, read settings from the process environment: a service URL, a database your app owns. The pack declares which names it reads:

TypeScript
Python

// in kindgi.config.ts
env: {
  required: ['ORDERS_APP_URL', 'ORDERS_DB_URL'],
  optional: ['ORDERS_API_TIMEOUT_MS'],
},

# in pyproject.toml
[tool.kindgi.env]
required = ["ORDERS_APP_URL", "ORDERS_DB_URL"]
optional = ["ORDERS_API_TIMEOUT_MS"]

required: names the pack service can't work without.
optional: names it reads when they're set.
Names are environment variable names. KINDGI_* names are Kindgi's own settings and are refused:

    ✗ refresh failed [config-invalid] kindgi.config: "KINDGI_X" in `env.required`: `KINDGI_*` names configure Kindgi, not the pack

Your code reads them as usual: process.env.ORDERS_APP_URL, os.environ["ORDERS_APP_URL"] (see the order-link tool in Keep local values in env files).

On your machine

kindgi dev gives the pack service the env files' values, and warns about a required name that has none:

    ⚠ the pack's env.required name ORDERS_DB_URL has no value: add it to the pack's env files (a deployment won't be ready without it)

It warns and carries on, so the rest of the pack keeps working while you fill it in. In a TypeScript pack, kindgi dev doesn't reload on a change to kindgi.config.ts: save a tool or restart it. A Python pack reloads when pyproject.toml changes.

In a deployment

The declaration is part of the pack's index, so the pack service in an image knows what it needs:

Only declared names are injected. The pack service gets each declared name that has a value for that environment, and nothing else. Set values per environment shows where those values come from, and kindgi env plan says when one isn't declared: environments.staging.env.FEATURE_FLAGS isn't declared in env.required or env.optional, so it isn't injected.
A required name with no value keeps the pack service from serving. It starts, says which names are missing, and answers 503 until they're set:

{"kind":"missing-env","check":"strict","names":["ORDERS_DB_URL"]}

{"error":"missing env","missingEnv":["ORDERS_DB_URL"]}

KINDGI_PACK_ENV_CHECK=warn on the pack service makes it serve anyway and only report the names, as kindgi dev does. See the environment variable reference.

What doesn't go here

A secret that belongs to a tenant (an API key a customer gives you) isn't part of the pack's environment: one pack service serves every tenant. A tool declares it and reads it from its context: Give a tool a secret.