Environment Variables

Configure your application with environment variables. All values are encrypted at rest.

Setting Variables

Set variables through the dashboard, CLI, or SDK:

Dashboard

Service → Settings → Environment Variables → Add Variable

CLI

hoststack env set <service-id> DATABASE_URL=postgres://...
hoststack env set <service-id> NODE_ENV=production

SDK

await client.envVars.create(teamId, 'svc_abc123', {
  key: 'DATABASE_URL',
  value: 'postgres://...',
  target: 'runtime',
  isSecret: true,
});

Variable Targets

Control when variables are available to your application:

Build

Available only during the build, and withheld from the running container. An explicit choice, so a secret is honoured here too — this is how you hand a build a private-registry token.

Runtime

Available only when the container is running. Never reaches the build.

Both

Available during build and runtime. This is the default. One exception: a variable also marked Secret is withheld from the build, because build arguments are baked into image history — pick Build to override that deliberately.

A build-time variable behaves differently from a runtime one

It is read once, while the image builds. Changing it does nothing until you deploy again — the old value is already inside the image.
Your own Dockerfile must declare it with ARG. Docker passes a build argument only to a Dockerfile that names it, and ignores the rest. Add ARG VITE_API_URL above the step that needs it (and ENV VITE_API_URL=$VITE_API_URL if it must be set at runtime as well). Services that build without a Dockerfile of their own — every static site — get this generated for them. HostStack warns you in the deploy log when it hands the build a variable your Dockerfile never declared.
In a frontend bundle, missing is silent. The bundler replaces an absent variable with undefined, whatever it guarded is dropped as dead code, and the build still succeeds. Nothing fails — the feature is just gone from the file you shipped. If a value matters, log it once at startup, or check the built asset: curl -s https://your-app/assets/index-*.js | grep -c the-value.

Variables HostStack Provides

Every service gets these injected automatically. You don't set them, and they refresh on each deploy — so reading one always describes the deploy your code is running in. They take precedence over a variable of the same name that you set yourself.

Variable	Value
`PORT`	The port your app must listen on. We route to exactly this port, so binding anything else makes the health check fail.
`HOSTSTACK_COMMIT_SHA`	Full 40-character git commit this deploy built. Absent when a deploy has no commit — fall back rather than assuming it is set.
`HOSTSTACK_COMMIT_SHORT_SHA`	The same commit, first 7 characters.
`HOSTSTACK_BRANCH`	Branch this deploy was built from.
`HOSTSTACK_DEPLOY_ID`	Unique per deploy — distinguishes two deploys of the same commit.
`HOSTSTACK_SERVICE_NAME`	Service name as shown in the dashboard.
`HOSTSTACK_SERVICE_ID`	Stable service identifier (svc_…).
`HOSTSTACK_PROJECT_ID`	Project this service sits in.
`HOSTSTACK_TEAM_ID`	Owning team.
`HOSTSTACK_INTERNAL_URL`	Private hostname other services in the project can reach this one on.
`HOSTSTACK_TMP_DIR`	Writable scratch directory (/tmp). Memory-backed and cleared on restart — use a volume for anything you need to keep.

Reporting which version is live is the usual reason to reach for these:

Example: a /version endpoint

import os

COMMIT = os.getenv("HOSTSTACK_COMMIT_SHA", "unknown")

@app.get("/version")
def version():
    return {"commit": COMMIT, "deploy": os.getenv("HOSTSTACK_DEPLOY_ID")}

The commit is also passed to your image build as the build argument HOSTSTACK_COMMIT, for when you need it baked in at build time — stamping a version into a compiled frontend bundle, for example. Declare ARG HOSTSTACK_COMMIT in a custom Dockerfile, or reference $HOSTSTACK_COMMIT from your Build Command.

Secret Variables

Mark a variable as Secret to hide its value in the dashboard and API responses. The value is still available to your application at runtime. Secrets are stored using AES-256-GCM encryption.

Environment Groups

Environment Groups let you share a set of variables across multiple services. Create a group, add variables, then link it to any service. When variables conflict, higher-priority groups take precedence.

Example: Shared database credentials

Group: "production-database"
  DATABASE_URL = postgres://...
  DATABASE_POOL_SIZE = 10

Linked to:
  → api-service (priority 0)
  → worker-service (priority 0)

Linked Databases

When you create a managed database and link it to a service, HostStack automatically injects the connection URL as an environment variable. No manual configuration needed.

Next: Managed Databases