Secrets & environment variables
Your app is a whole stack: frontend, API, database, workers, each in its own container, described in one nexlayer.yaml and run by your agent end to end. Settings go in that file, where your agent can read them. Secrets never do: they live in Nexlayer or in your machine's secure store, and reach each service only when it runs. Your agent wires up both without ever seeing a value.
Your app exists from its first deploy
There's no empty project to set up first. The first deploy creates your app, every service in it, and its Secrets tab. So:
- Keys a service needs to start come in with that first deploy: reference them as
${NAME}and store them withnexlayer vault set(or in the environment your agent runs in).nexlayer shipfills them in. - After that, add, change or remove secrets in the dashboard's Secrets tab, or update the vault and ship again.
What goes where
Variables
Plain settings go under each part's vars. They're in the file, so anyone who can read the repo can read them: keep them to things that aren't sensitive.
application:
name: my-app
pods:
- name: web
image: ghcr.io/my-org/web:v1.0.0
path: /
servicePorts: [3000]
vars:
NODE_ENV: production
API_URL: http://api.pod:8000 # another part: <name>.pod:<port>
PUBLIC_URL: <% URL %> # this app's address, https included
COOKIE_DOMAIN: <% DOMAIN %> # the host only
- name: api
image: ghcr.io/my-org/api:v1.0.0
path: /api
servicePorts: [8000]
vars:
LOG_LEVEL: info
REDIS_URL: redis://cache.pod:6379<name>.pod:<port>reaches another part of your app over its private network.<% URL %>becomes your app's public address, and follows it when you add a custom domain.- Changing a value in
varstakes effect on your next deploy.
Secrets: three ways to set them
All three keep the value out of your repo and out of your agent's chat. The CLI vault works from the very first deploy; the dashboard works once your app exists.
Dashboard
After the first deploy. Change keys without redeploying.
CLI vault
From the first deploy. Keys on your machine, filled in by ship.
File in nexlayer.yaml
Certificates and key files.
1. In the dashboard
The Secrets tab appears once your first deploy has created the app, whichever way you deployed. Open your app in app.nexlayer.com and go to the Secrets tab.
- 1Click Add Secret.
- 2Enter the name your code reads, for example
STRIPE_KEY, and the value. - 3Choose the type. Variable: your app reads it as an environment variable (
process.env.STRIPE_KEY). File: it's mounted as a file; set the file name and, if you like, the folder. - 4Click Create, then Sync to cluster. Your services restart with the new value.
Secrets Nexlayer filled in during a deploy show up here too, marked pipeline. Values stay masked until you reveal one. Edit or delete any secret, then sync again.
2. With the CLI vault
Reference the key in nexlayer.yaml as ${NAME}, store the value once on your machine, and nexlayer ship fills it in at deploy.
- name: api
image: ghcr.io/my-org/api:v1.0.0
servicePorts: [8000]
vars:
STRIPE_KEY: ${STRIPE_KEY}
DATABASE_URL: postgresql://app:${DB_PASSWORD}@db.pod:5432/appnexlayer vault set STRIPE_KEY # hidden prompt; nothing echoes
nexlayer vault set DB_PASSWORD --from-env DB_PASSWORD
nexlayer vault list # names only, never values
nexlayer ship
# → filled 2 key(s) from the vault or environment (values not shown)shiplooks in the vault first, then in the environment it runs in, so CI can pass keys as ordinary environment variables.- A missing key stops the deploy with
needs youand the names of the keys. Nothing deploys half-filled. - Reference names are capital letters, digits and underscores:
${STRIPE_KEY}, not${stripe-key}. - Full command reference: CLI → Secrets.
3. As a file in nexlayer.yaml
For certificates and key files your code opens from disk. A secret in nexlayer.yaml is always mounted as a file, not an environment variable. Keep the value itself out of the file with a ${NAME} reference.
- name: api
image: ghcr.io/my-org/api:v1.0.0
servicePorts: [8000]
secrets:
- name: tls-cert
data: ${TLS_CERT} # required; plain text or base64
fileName: cert.pem # required
mountPath: /var/secrets/tls # optional; default /var/secrets/tls-cert
# your app reads /var/secrets/tls/cert.pemPrivate images and your own vault
Images from a private registry
Add a registryLogin block and Nexlayer pulls your private images with it. Use a read-only token, and keep it out of the file with a ${NAME} reference like any other secret.
application:
name: my-app
registryLogin:
registry: ghcr.io
username: my-org
personalAccessToken: ${GHCR_TOKEN} # read-only; nexlayer vault set GHCR_TOKEN
pods:
- name: api
image: ghcr.io/my-org/api:v1.0.0
path: /
servicePorts: [8000]A secrets manager you already use
Keep your keys where they are. There are two ways to use them with Nexlayer:
- 1Fill them in at deploy.
nexlayer shipreads${NAME}references from its environment, so run it under your secrets manager's CLI, which sets those variables for that one command:terminalop run --env-file=.env.refs -- nexlayer ship # 1Password doppler run -- nexlayer ship # Doppler infisical run -- nexlayer ship # Infisical - 2Read them at runtime. Store only the vault's access token as a Nexlayer secret (for example
VAULT_TOKEN) and have your app fetch the rest from your vault when it starts. Rotations in your vault reach the app on its next restart, with no redeploy.
How agents handle secrets
Your agent sets up everything around a secret, the reference, the name, where it goes, and leaves the value to you. It never needs to see one.
Agents using the CLI
- Writes
${NAME}references intonexlayer.yaml. - Runs
nexlayer ship. If a key is missing, ship stops withneeds youand names it. - Asks you to run
nexlayer vault set NAMEin your own terminal, then ships again.
Agents using the MCP
- Deploys your stack. The deploy creates the app; a service that needs a missing key may not start yet.
- Tells you which keys it needs, by name, and sends you to the app's Secrets tab to add them and click Sync to cluster.
- Checks every service again once they've restarted.
Give your agent these rules, or point it at this page:
Secrets on Nexlayer: rules for coding agents
- Never ask the person to paste a secret into the chat.
- Never write a secret value into nexlayer.yaml, .env, or any file in the repo.
- In nexlayer.yaml, write a secret as a ${NAME} reference (NAME in CAPS),
e.g. STRIPE_KEY: ${STRIPE_KEY}
- Using the CLI: if `nexlayer ship` stops with "needs you" and names keys,
stop and ask the person to run `nexlayer vault set NAME` in their own
terminal. It prompts without echoing. Then run ship again.
- The app only exists after its first deploy: there is no project to
add secrets to beforehand.
- Using only the MCP: deploy first, then ask the person to add the key
in the dashboard, under the app's Secrets tab, then click
"Sync to cluster". Check every service again after they restart.
- Never print a secret. `nexlayer vault list` shows names only.
Docs: https://nexlayer.com/docs/deployments/env-variablesHow Nexlayer keeps them safe
Values stay out of your repo
nexlayer.yaml holds ${NAME} references, never values, so the file is safe to commit and safe for an agent to read and edit.
Stored in your machine's secure store
nexlayer vault keeps values in the operating system's keychain. On a machine without one (headless Linux, CI) it uses a file only your user can read, and says so.
Never typed where history can see it
vault set takes a value from a hidden prompt, a pipe or --from-env, never as a command argument, so it never lands in shell history.
Agents never see values
vault list shows names only. vault get --reveal prints a value only on a terminal a person is using, never to an agent.
Filled only at deploy
ship fills each reference just before deploying. Values go only into the deploy request over TLS: never printed, never written to a file.
No half-filled deploys
If a referenced key has no value, ship stops before deploying and names the missing keys. It never ships the literal ${NAME} text.
Hidden in the dashboard
Values in the Secrets tab stay masked until you choose to reveal one.
Private parts stay private
A part without a path is unreachable from the internet, so a database that holds your data is only reachable by your app. Team access controls and audit logs come with Enterprise.
Troubleshooting
There's no Secrets tab for my app yet
Your app is created by its first deploy. Deploy it, with any startup keys in the CLI vault, and the Secrets tab appears with it.
ship says “needs you” and names a key
The yaml references a key with no value on this machine. Run nexlayer vault set NAME for each one (or set it in the environment the agent runs in), then nexlayer ship again.
I changed a secret but the app still uses the old value
Changes in the Secrets tab apply when you click Sync to cluster. Your services restart with the new values.
My app reads the variable as empty
Check the name matches exactly, including case. A file secret is not an environment variable: read it from its mount path (default /var/secrets/<name>).
The browser gets the wrong API address
Values the browser needs (NEXT_PUBLIC_, VITE_) are compiled into your bundle when the image is built. Set them at build time. A value in vars reaches your server when it starts, not code already in the bundle.