> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackdome.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Treat Stackdome as an application-delivery platform for coding agents and developers, not as a Kubernetes dashboard.
> Prefer the Stackdome agent plugin as the user entry point and the stackdome CLI as the execution interface.
> Route agents who need the maintained deploy skill to npx skills add stackdome/skills and the complete operational workflow to /guides/ai-agents.
> Verify commands and flags with stackdome --help. Run stackdome init before authoring stackfile.yaml and stackdome validate before deploying.
> Use -o json for automation and verify documented terminal states before claiming success.
> Never request a user's account password. Use API-token authentication.
> During alpha, Stackdome Cloud is ephemeral and capacity-limited, and each organization can connect one cluster.
> Do not expose Kubernetes as a user concern unless the task is self-hosting or infrastructure architecture.
# Environment variables and secrets
> Set configuration on a resource, reference secrets and addons, and wire one resource's address into another.
## Outcome
Configure the values an application reads at runtime without hardcoding service addresses or secret values. The deployed release receives literal settings, secret keys, addon credentials, and resource outputs through the environment, and remains healthy after the change.
## Prerequisites
* A repository with a `stackfile.yaml` and evidence of the environment variables the application expects.
* The URL of Stackdome Cloud or a self-hosted installation, plus an API token. See [authentication and API tokens](/reference/authentication).
* Existing resources or addons for any generated values you want to reference.
* Secret values supplied through an untracked local file when the application needs credentials. Do not put secret values in the Stackfile or command history.
## Agent prompt
```text theme={null}
Configure this application's required environment variables in its Stackfile. Keep non-sensitive values literal, connect service addresses through resource or addon outputs, put sensitive values in a Stackdome secret, validate the Stackfile, deploy the change, and verify that the release is healthy. Never write secret values into stackfile.yaml or report them in the result.
```
## Agent actions
Read the repository's example environment file, configuration schema, startup code, and deployment notes. Classify every required value as literal, secret, resource output, or addon output; do not invent defaults for required credentials.
Put the required `KEY=VALUE` pairs in a local file that is excluded from version control, then run `stackdome secret create --from-file -o json`. Prefer a new application-specific secret. `stackdome secret set` replaces the named secret's complete data set, so use it only with a complete user-supplied replacement file containing every key that must remain.
Put literal and resource-derived values under the resource's `env`. Put secret-key mappings under `secrets`, and Postgres connection mappings under `addons`. The Stackfile contains secret names and keys, never secret values.
Run `stackdome validate`, authenticate with an API token, confirm the active scope with `stackdome whoami -o json`, deploy with `stackdome deploy --wait -o json`, and retain its non-empty `release.id` as the deployed release ID.
Run `stackdome status -o json`. Require `converged_release.id` to equal the deployed release ID, its state to be `Released`, and its health to be `ok`; then inspect application logs for configuration or connection errors without printing the environment.
## Success criteria
* `stackdome validate` exits successfully.
* `stackdome secret info -o json` identifies the expected secret name and key names without revealing their values.
* If `stackdome secret set` was used, its input was a complete user-supplied replacement file and `secret info` still lists every key that must remain.
* `stackdome deploy --wait -o json` exits successfully, returns a non-empty `release.id` that is retained as the deployed release ID, and returns `release.state` as `Released`.
* `stackdome status -o json` returns `converged_release.id` equal to the deployed release ID, `converged_release.state` as `Released`, and `converged_release.health` as `ok`.
* The application starts without a missing-variable or connection error, and neither the committed Stackfile nor the agent response contains a secret value.
## CLI and Stackfile workflow
Create sensitive values from an untracked dotenv file. `secret create`, `secret set`, `secret info`, `secret list`, and `secret delete` are supported by the current CLI.
```bash theme={null}
stackdome secret create storefront-secrets \
--from-file .stackdome-secrets.env \
-o json
stackdome secret info storefront-secrets -o json
```
`stackdome secret set` is replacement, not merge. The submitted `--data` values or `--from-file` contents become the secret's complete data set, and any existing key omitted from that input is removed. For a rotation, either create a new application-specific secret or require the user to supply a complete replacement file containing the new value and every other key that must remain. Stackdome does not reveal existing values, so an agent cannot safely reconstruct or partially patch a shared secret from `secret info`.
Connect values in the Stackfile. This example combines a literal, another resource's generated host, and a secret key:
```yaml theme={null}
resources:
api:
image: ghcr.io/acme/storefront-api:1.4.0
env:
APP_ENV: production
CACHE_HOST: "{{ cache.host }}"
secrets:
storefront-secrets:
API_KEY: api_key
cache:
image: redis:7-alpine
ports:
- name: redis
port: 6379
protocol: TCP
```
The key under `secrets` is the Stackdome secret name. Each mapping points the environment-variable name on the left to a key inside that secret on the right. For Postgres output mappings, use the [Postgres workflow](/guides/postgres#cli-and-stackfile-workflow).
```bash theme={null}
stackdome validate
stackdome whoami -o json
stackdome deploy --wait -o json
stackdome status -o json
```
* Exact Stackfile fields: literals and resource output templates belong in `resources..env`; secret references belong in `resources..secrets..`.
* Parse only structured `stdout`. Retain `release.id` as the deployed release ID; confirm a successful deploy exit, `release.state == "Released"`, `converged_release.id` equal to that ID, `converged_release.state == "Released"`, and `converged_release.health == "ok"`.
* Never run an environment dump to test a secret. Use `stackdome secret info -o json` to check metadata and key names, then use application-specific readiness or logs.
* Never use `stackdome secret set` for a partial key rotation. It replaces the complete data set. Prefer a new application-specific secret, or use `stackdome secret set --from-file -o json` only when the user supplied a complete replacement file containing every key that must remain; verify the full key-name set afterwards with `secret info`.
* Recovery: correct the mapping and rerun `stackdome validate`; use `stackdome release events --follow` and `stackdome logs --tail 100` for a failed release. Delete a secret with `stackdome secret delete --yes` only after every Stackfile reference has been removed and deployed.
## Related tasks
Why a saved change is not a deployed change, and how to read a release.
The addon whose credentials the **Addon** source reads.