Docs/Deployments/Secrets & environment variables

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 with nexlayer vault set (or in the environment your agent runs in). nexlayer ship fills 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

Settings that aren't sensitiveNODE_ENV, LOG_LEVEL, feature flagsvars
Addresses of your other partshttp://api.pod:8000, redis://cache.pod:6379vars
Your app's own public address<% URL %> or <% DOMAIN %>vars
API keys, tokens, passwordsSTRIPE_KEY, OPENAI_API_KEY, DB passwordSecret
Certificates and key filescert.pem, a service-account JSONFile secret

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.

nexlayer.yaml
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 vars takes 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.

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.

  1. 1
    Click Add Secret.
  2. 2
    Enter the name your code reads, for example STRIPE_KEY, and the value.
  3. 3
    Choose 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.
  4. 4
    Click 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.

nexlayer.yaml
    - 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/app
terminal
nexlayer 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)
  • ship looks 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 you and 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.

nexlayer.yaml
    - 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.pem

Private 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.

nexlayer.yaml
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:

  1. 1
    Fill them in at deploy. nexlayer ship reads ${NAME} references from its environment, so run it under your secrets manager's CLI, which sets those variables for that one command:
    terminal
    op run --env-file=.env.refs -- nexlayer ship     # 1Password
    doppler run -- nexlayer ship                       # Doppler
    infisical run -- nexlayer ship                     # Infisical
  2. 2
    Read 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

  1. Writes ${NAME} references into nexlayer.yaml.
  2. Runs nexlayer ship. If a key is missing, ship stops with needs you and names it.
  3. Asks you to run nexlayer vault set NAME in your own terminal, then ships again.

Agents using the MCP

  1. Deploys your stack. The deploy creates the app; a service that needs a missing key may not start yet.
  2. 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.
  3. Checks every service again once they've restarted.

Give your agent these rules, or point it at this page:

rules for your agent
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-variables

How 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.

Next