Variables

References

Write a reference inside any value and shed replaces it with the value it points to. This is how an app gets its database URL without anyone copying a password around.

A reference is expanded in the scope of the service that owns the value. When web uses ${{ postgres.DATABASE_URL }}, the ${{ POSTGRES_USER }} inside it means postgres's user, not web's, even if web has a variable with the same name.

DATABASE_URL=${{ postgres.DATABASE_URL }}
REDIS_URL=${{ redis.REDIS_URL }}
PUBLIC_URL=https://${{ SHED_PUBLIC_DOMAIN }}

References resolve when a deployment starts, and the result is written into the new container's environment. Editing a variable does not change containers that are already running; deploy again to apply it. Builds get the resolved variables too, see build secrets. Saving only checks key names ([A-Za-z_][A-Za-z0-9_]*), so a bad reference shows up as a failed deployment, not as a save error.

The variables table hides every value; use the eye button to reveal one, or edit the row or switch to raw mode to see them all. Copying a saved value with references copies it resolved, as the next deployment would see it, with SHED_GIT_COMMIT_SHA taken from the active deployment. An unsaved value is copied as typed.

Injected variables

shed adds a few variables to every service. You can reference them like any other, from the same service or another one (${{ postgres.SHED_PRIVATE_DOMAIN }}).

Your own variables win. If you store a variable with the same name as an injected one, yours replaces it. The merged set is then resolved, and the container receives it sorted by key.

Database templates

Creating a database writes its variables for you. Passwords are 24 random characters from A-Za-z0-9, drawn uniformly at random, so they are safe to embed in a URL without escaping. Every database also gets a volume at the template's data path, see volumes.

The connection strings are themselves references, so they stay correct if you rename the user or the database. This is what postgres starts with:

POSTGRES_USER=postgres
POSTGRES_PASSWORD=<24 random characters>
POSTGRES_DB=app
DATABASE_URL=postgresql://${{POSTGRES_USER}}:${{POSTGRES_PASSWORD}}@${{SHED_PRIVATE_DOMAIN}}:5432/${{POSTGRES_DB}}

Two details matter in practice. Redis runs redis-server --requirepass with $REDIS_PASSWORD and --appendonly yes, so changing the password variable takes effect on the next deploy. Postgres, MySQL, and MongoDB only read their password variables when the data directory is first initialized, so changing them later does not change the password inside an existing database.

Resolver playground

This runs the resolver on a sample project with a web app, postgres, and redis. Pick a service and it merges the injected variables, applies the stored ones, and expands every reference the way a deployment does. Click a reference to jump to its source. Edit any value to watch the result change, or add a scratch variable to cause a cycle.

How resolution works

shed expands each of the service's variables depth first, remembering finished values and tracking which variables it is currently inside of. The rules, in order:

1. Keys are visited in sorted order, so the first cycle reported is always the same one.

2. A variable that is missing resolves to an empty string before any other check, even if it would be on the stack.

3. A variable already on the stack is a cycle. The error lists the loop:

   error

   vars: reference cycle: web.A -> web.B -> web.A
   

4. Reaching a variable deeper than 64 levels, or one over the size limits, is an error.

5. Finished values are memoized, so a diamond (A uses B and C, both use D) is not a cycle, and two services may refer to each other as long as the variables do not.

The first error fails the whole set, and therefore the deployment, with deploy: resolve variables: ... in the build log. Only the variables of the service being deployed are walked: another service's broken value does not matter unless something you deploy references it.

After resolution, the values of your stored variables become literal secrets that shed masks in build and runtime logs. Injected values like PORT are not masked. See secret redaction.

Limits

Limits are checked as values are expanded, before the bytes are appended, so a hostile chain cannot exhaust memory. All sizes are UTF-8 bytes.

The playground shows the resolved size against the 1 MiB budget. The total counts each variable once, including ones reached through another service. The resolver internals cover the algorithm in code.