Env groups

Keep variables that several services need — a shared API key, a feature flag, an SMTP login — in one place, and change them once.

What an env group is

An env group is a named set of variables owned by your team. Each variable in it has the same options as a service variable — a target (build, runtime or both) and a Secret switch — and the same limits. See Environment variables.

A service reads a group's variables when it deploys. Editing a group therefore changes nothing in a running container; each service picks up the new values on its next deploy.

Create a group

Create it
In the dashboard, go to Settings → Environment groups and click New Group. Give it a name — letters, digits, dashes and underscores — and an optional description.
Add variables
On the group's page, add variables under Variables one at a time, or paste several at once with Import .env.
Link services, if you need an order
Under Linked Services, pick a service, give the link a Priority from 0 to 100, and click Link. Linking is how you decide which group wins when two groups set the same key.
Deploy
Redeploy the services that should pick up the variables.

A service's Settings → Variables tab lists the groups linked to it under Linked Environment Groups, where you can also unlink one.

Scope a group to a project or environment

A group can be narrowed to one project, or to one environment of a project — for example, Stripe's test keys for Staging and live keys for Production, without copying the rest of the configuration. The dashboard does not set a scope yet; create the group through the API with projectId and, optionally, environmentId:

bash

curl -X POST https://hoststack.dev/api/env-groups/<team-id> \
  -H "Authorization: Bearer $HOSTSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "stripe-staging", "projectId": 12, "environmentId": 34}'

Both ids are numeric. An environment scope needs the project scope as well. A scoped group applies to every service in that project or environment, and can only be linked to services inside its scope.

Which value wins

Variables set on the service always beat group variables, and PORT and HOSTSTACK_* beat both. Between groups, later rows override earlier ones:

Applied	Groups
First	Groups with no scope (team-wide)
Then	Groups scoped to the service’s project
Then	Groups scoped to the service’s environment
Last	Groups linked to the service, lowest priority first — the highest priority wins

Two groups in the same scope that set the same key and are not linked have no defined order. When that matters, link both to the service with different priorities. The whole chain — groups, linked databases, hoststack.yaml — is under Environment variables → Precedence.

Secrets and access

Every group value is encrypted at rest. A secret's value is shown as •••••• and can be revealed on the group's page; each reveal is recorded in the activity log.
A secret on the Build + Runtime target is withheld from the build, as on a service.
Deleting a group needs the admin role. It removes the group, its variables and its links; services lose the variables on their next deploy.

Next steps

Was this page helpful?