Variables

Where

Variables in the sidebar (instance-wide)

Merge

Linked environments in order < Infisical < own env

Reference

${{vars.KEY}}

Concepts

Open Variables in the sidebar to see the sets you can use. Each environment has a tab with the variable names and masked values. The eye button on a row shows that value, the copy button copies it without showing it, Reveal all shows every value (secret-flagged ones stay masked until you press their eye button) and Edit opens the editor. Shown values hide again after 60 seconds and are dropped from the page, also when you switch tabs or leave. Fetching the values is recorded in the audit log: one entry covers the whole environment for those 60 seconds, a later reveal is a new entry.

Sharing

A set is shared with all projects (current and future) or with selected projects. Only applications and stacks in those projects can link it, and only members of those projects see it. A set shared with nobody is visible to instance owners and admins only.

• Creating, renaming, sharing and deleting sets, and adding or deleting environments, is for instance owners and admins.
• A project cannot lose access while something in it still links the set: the change is refused with the names of those applications and stacks. Unlink them first. Deleting a set or an environment is refused the same way while anything links it.

Who can do what

Your role on a set comes from your role in the projects it is shared with (the best one counts). Instance owners and admins are instance admins on every set.

• Editing includes restoring a version and promoting; reading history lists and comparing names is open to every role.
• Protected environments are stricter than in 0.1.0-alpha.9: a project admin can no longer reveal or edit them.

Linking to applications and stacks

On an application's or stack's Environment tab, the Variable sets card lists the linked environments in merge order. Add one with Link, move it up or down, or unlink it. The create forms (application, stack, template) also accept an optional set environment.

• At most 10 links; an environment can be linked once per application or stack.
• The set must be shared with the project (or with all projects).
• Changing links needs the developer role or higher. Adding or removing a link to a protected environment needs the project admin role; reordering links that stay is always allowed.
• Changes apply on the next deploy; running containers are not touched. The same holds for editing a linked environment.
• The card points out conflicts: keys overridden by a later link and keys overridden by the own env.

Merge order

1. 01link 1the first linked set environment (lowest)
2. 02link 2 … 10each later link overrides earlier ones on the same key
3. 03secret sourceInfisical secrets, when sync is on
4. 04own envthe application's or stack's own env always wins
5. 05containerreferences resolved, the result goes into the container

The merge happens every time the container is created (deploy, rollback, a recreate after a domain or mount change), never at build time. Each key keeps the secret flag of the layer its value comes from.

# shared/production
LOG_LEVEL=info
SENTRY_DSN=https://abc@sentry.example.com/1

# backend/production
LOG_LEVEL=warn
API_HOST=api.example.com

# own env of the application
LOG_LEVEL=debug
API_URL=https://${{vars.API_HOST}}/v1

LOG_LEVEL=debug          # own env wins
SENTRY_DSN=https://abc@sentry.example.com/1
API_HOST=api.example.com
API_URL=https://api.example.com/v1

References: ${{vars.KEY}}

• ${{vars.KEY}} is the merged value of KEY across the linked set environments (the same order as above). It can be used in the own env and in set values; a set value may refer to a key of another set linked to the same application.
• Expansion is one level: the referenced value is used as written. With URL=https://${{vars.HOST}} in a set, URL is expanded where it is used, but FULL=${{vars.URL}} receives the raw https://${{vars.HOST}}.
• An unknown key is refused with 400 when you save the links or the own env, and fails the deployment (naming the reference) if it only breaks later, for example after a set edit removed the key.
• ${{project.KEY}} no longer exists: it is refused with "was renamed to ${{vars.KEY}}". The upgrade rewrites existing references for you. ${{database.…}} and ${{secret.…}} work as before (see Environment variables).

History and restore

• Every change to an environment is kept as a version: an edit in the dashboard, aoox env set|unset|push, a restore or a promotion. History shows who (a user or a token), when, and the names added, changed and removed; values only when you reveal a version.
• Restore this version writes that text back as a new version, so nothing is lost and a restore can be undone. It is refused when it equals the current content or no longer passes today's checks.
• The first recorded change also saves a baseline of what was there before. The newest 50 versions are kept, encrypted like the live text.
• Who can restore: the same people who can edit that environment.

Compare and promote

• Compare two environments of one set: names only on one side, names with different values, and how many are the same. Values are compared on the server and never sent to the browser; if you cannot read both sides you only see which names exist where.
• Select variables and Promote them into the other environment: each is copied with its value and secret flag, the target keeps its comments and order, new ones go at the end, and a version Promoted from <source> is recorded.
• Promotion needs the right to read the source and to edit the target, so a protected side needs an instance owner or admin. A change made by someone else in between is refused; nothing is written.

Notes

A variable's note is the block of # lines directly above it. A blank line in between breaks the link, so a section header followed by a blank line stays an ordinary comment.

# Payments

# Base URL of the payments API, including the /v1 prefix.
PAYMENTS_URL=https://pay.example.com/v1
# Must equal WEBHOOK_SECRET in the payments service.
WEBHOOK_SECRET=…

• Here PAYMENTS_URL and WEBHOOK_SECRET have a note; # Payments is a standalone comment.
• On the set page a note icon appears next to each variable that has one; hover, click or tap it to read the note. In Edit, Rows view shows the note under the variable and lets you add or change it; Text view shows the # lines.
• Notes are visible without revealing values, to everyone who can see the set, viewers included. Do not put secrets in them.
• Notes are part of the text, so they travel with it: history and restore, aoox env pull / push, and export and import. Promote brings the note of a variable that is new to the target; a variable the target already has keeps its own note. A note is cut at 1000 characters.

Secret variables

• Set the flag with the Secret switch in the editor or aoox env set KEY=VALUE --secret / --no-secret. New variables whose name contains password, secret, token, key, private or credential are marked secret automatically.
• Flags are stored next to the names, not in the text, so pulled files and the compose .aoox.env are unchanged. Masking applies to deployment logs, job output and error notifications.
• What the flag does not do: every value is stored encrypted, secret or not. The flag does not decide who may see a value: in the dashboard it stays hidden until you reveal or copy it (audited), and access follows roles and protected environments. The container always receives the real value. The flag only controls masking with *** in logs.
• Known false positive: the automatic name rule also matches names such as MONKEY or KEYBOARD, because they contain "key". Turn the switch off for those.
• Tip: turn it on for passwords, tokens, API keys and connection strings; turn it off for plain values like NODE_ENV, PORT and LOG_LEVEL so they stay readable in logs.

API token scopes

An API token can be limited to some set environments with the token's variables limit (Settings → Account → API tokens; variableScopes in the API, at most 20 entries):

• No entries: the token may use every set environment its owner can. Entries only narrow access; a token never gets more than its owner.
• The scope covers reveal, edit, restore, promote and creating or deleting environments. Comparing treats an out-of-scope side as not comparable. Linking is not narrowed by it.
• A read-only token may still reveal (reading is audited but changes nothing); every write is refused.

From a terminal

$ aoox env list                                   # sets, environments, variable counts
$ aoox env set API_URL=https://api.example.com --set backend --env staging
$ aoox env pull --set backend --env development  # ./.env (mode 0600)
$ aoox env links                                  # what the linked app uses, in order
$ aoox env link --set shared --env production --position 1
$ aoox run -- npm run dev                         # linked environments + own env

Details in CLI: aoox env and aoox run. To run your app locally with one environment, see Local development.

Export and import

• A project export lists, for each application and stack, its links by set and environment name in merge order.
• The sets themselves (with values) are only included when the owner exports with secrets: the sets shared with the project explicitly or linked by one of its applications or stacks.
• On import, a set whose name already exists is reused and never overwritten (a warning says so); a new one is created and shared with the imported project only. A link to an existing set that is not shared with the new project is shared by an instance owner or admin, or skipped with a warning for anyone else.
• Older files (0.1.0-alpha.9 environments) become one set named after the new project, and ${{project. becomes ${{vars..

Upgrading from 0.1.0-alpha.9

• Each project whose environments have content becomes one set named after the project, shared with that project only, with the same environments, values, secret flags and history. Applications and stacks keep their environment as their first link.
• Empty environments are dropped; a project with only empty environments gets no set, and links to them are removed.
• ${{project.KEY}} becomes ${{vars.KEY}} in application and stack env and in every stored text and version.
• An API token's environments list becomes scopes of the form */<name> (the same meaning: that name in every set). Re-issue tokens with set-specific scopes when you want them narrower.
• Protected environments are now instance owner/admin only. Project admins who revealed or edited production need an instance admin, or the environment unprotected.
• ENCRYPTION_KEY must be set (it already is on a normal install) because stored texts are re-encrypted. Update the CLI as well: the old aoox env commands called endpoints that are gone.

Limits

• No per-set roles: access follows project roles.
• Slugs cannot be renamed, and environments cannot be moved between sets.
• References expand one level.

Next steps