Environment Variables & Secrets

Store configuration and credentials for your published site — API keys, tokens, and per-environment settings — without putting them in your code.

Every Ploy site has an Environment tab where you manage the values your site needs at runtime. There are two tiers: Variables, which are readable at build time and in the dashboard, and Secrets, which are write-only and read only at request time. Both are scoped separately for your Preview (staging) and Production environments, so test credentials never leak into your live site.

Where to Find It

In the Ploy dashboard, open your site and go to Settings → Environment. You’ll see two tabs across the top — Preview and Production — and an Add menu for creating values.

The fastest way: Just ask Ploy’s Agent in chat — “Add a Stripe secret key to production.” Ploy surfaces a secure form right in the conversation for you to paste the value. The secret is never seen by Ploy’s Agent, Ploy’s team, or stored in chat history.

Variables vs. Secrets

Pick the tier based on whether the value is sensitive and when your code needs to read it.

Heads up: Because secrets aren’t available at build time, don’t reference them in code that runs during the build (e.g. static page generation). Use a Variable for anything you need while building, and a Secret for anything read on a live request.

Adding a Value

1. Open Settings → Environment and select the Preview or Production tab.
2. Click Add.
3. Enter a Name (e.g. STRIPE_SECRET_KEY), choose a Tier — Variable or Secret — and paste the Value.
4. Click Add. The value applies on your next publish.

Bulk Import a .env File

To add many values at once, paste an entire .env file straight into the Name field in the Add dialog. Ploy parses each KEY=value line and creates the entries for you.

STRIPE_SECRET_KEY=sk_live_51H...
STRIPE_PUBLISHABLE_KEY=pk_live_51H...
RESEND_API_KEY=re_123...
PUBLIC_SITE_NAME=Acme
NEXT_PUBLIC_ANALYTICS_ID=G-XXXXXXX

Every imported line defaults to Secret. Before anything is saved, Ploy drops you into a manual review where you can step through each value, switch any non-sensitive lines to Variable, and confirm the names and values are correct.

Tip: Use the review step to downgrade public, non-sensitive values (site names, public IDs, analytics keys) to Variable so they’re readable at build time — sensitive credentials should stay as Secret.

Preview vs. Production

Each environment has its own independent set of values. This lets you point your staging site at test credentials while production uses live ones — the same variable name can hold a different value in each.

Secrets and the sandbox preview: For security, secrets are not available in your Ploy sandbox preview while editing. They only resolve on your published Preview and Production deploys. Variables, by contrast, are available everywhere.

Applying Changes

Environment changes do not take effect immediately. After adding, editing, or removing a value, you must republish the affected environment for your code to pick up the new values.

1. Make your changes in Settings → Environment.
2. Publish the corresponding environment (Preview or Production).
3. Your site picks up the new values on that deploy.

Tip: Changing a production secret? Update the value, then publish production — there’s no need to touch your code.

How Your Code Reads Values

Variables and secrets are exposed to your site’s runtime through the standard environment. Reference them the way your framework normally reads environment values — for example, in an Astro/Cloudflare Workers site, server-side code reads them at request time. Remember:

• Variables are available at build time and request time.
• Secrets are available at request time only — never during the build or in the sandbox preview.
• Prefix conventions from your framework still apply. Public, client-exposed values should be ordinary Variables — never put a credential in a client-visible value.

Never expose secrets to the browser: Anything readable in client-side code is public. Keep API keys and tokens as Secrets and only read them in server-side / request-time code.

Security

• Secrets are write-only. Once saved, the value is hidden and can’t be retrieved through the dashboard — only replaced.
• Ploy never sees your secrets. When you add one through chat, Ploy’s Agent surfaces a secure form; the value goes straight to encrypted storage and is never visible to Ploy’s Agent, Ploy’s team, or chat history.
• Scoped per environment. Preview and Production values are isolated, so staging credentials can’t reach your live site.
• Excluded from the sandbox preview. Secrets only resolve on published deploys, so they aren’t exposed in the editing environment.

Troubleshooting

• My code can’t see a new value — Republish the environment. Changes only apply on the next publish.
• A secret is undefined during build — Secrets aren’t available at build time. Use a Variable, or move the read to request-time/server code.
• A value works in production but not in the sandbox preview — Secrets don’t resolve in the sandbox preview by design. Test secret-dependent behavior on your published Preview deploy.
• I need to change a secret’s value — You can’t view it, but you can overwrite it. Add it again with the same name and the new value, then republish.
• Wrong value in the wrong environment — Confirm you’re on the correct tab (Preview vs. Production). Each has its own independent set.

What’s Next?

• Publish your changes — See Publishing & Deploys to apply new environment values.
• Work with Ploy’s Agent — Read the Ploy’s Agent guide to add secrets securely from chat.
• Review security — How Ploy protects your data is covered in Security & Compliance.
• Get help — Check the FAQ & Troubleshooting page or email support@ploy.ai.