Configure Environment Variables

Environment variables are how your app gets API keys, feature flags, and config without hardcoding them into source files. Hiveku manages them per environment and injects them automatically.

Where to Find Them

Open your project and go to Environment Variables. Project Settings also shows a read only summary (how many variables you have, how many are sensitive, when they last changed) with a Manage button that takes you to the same place. Settings never displays values.

Choosing Environments

Every variable has an environment setting. There are no separate tabs to switch between; each variable row carries its own scope:

Scope	Applies to
All Environments	development, staging and production
Development	development and previews only
Staging	staging only
Production	production only
Development and Staging	both, but not production
Staging and Production	both, but not development

That is how you give the same name a different value per environment. Add STRIPE_SECRET_KEY scoped to Production with your live key, then add it again scoped to Development and Staging with your test key. Hiveku picks the right one based on where your app is running.

If you set both an All Environments value and a more specific one for the same name, the more specific value wins for that environment. The panel flags this so it is not a surprise.

Previews always run as development. A branch or pull-request preview receives your Development and All Environments values, and never your Production values. If a variable only has a Production value, previews will not see it at all; add a Development or All Environments entry for it, usually with a test key.

Adding a Variable

Click Add Variable

A new row appears at the top of the list.

Enter a name and value

Names are normalised to uppercase with underscores as you type, so my key becomes MY_KEY. Names must start with a letter and use only A-Z, 0-9 and underscores.

Pick the environments

Use the dropdown on the row. Defaults to All Environments.

Click Save changes

Nothing is written until you save. The variable is encrypted at rest and injected into your builds and runtime.

Redeploy if needed

Runtime variables take effect on the next restart. Build time variables (NEXT_PUBLIC_*) need a redeploy to reach the browser bundle.

Editing, Renaming and Deleting

Changes are staged and applied together when you click Save changes. A footer appears whenever you have unsaved edits, summarising what will be added, updated or removed, and dirty rows are marked so you can see exactly what you touched.

Rename: edit the name. Saving moves the value to the new name and removes the old one, so you do not end up with two copies.
Change environments: pick a different scope. The row shows you which stored keys will change before you commit to it.
Delete: click the bin icon. The row is struck through with an Undo link and nothing is removed until you save. You get a confirmation naming exactly what will be deleted.
Discard changes: throws away everything unsaved and reloads.

If someone else (a teammate, or the AI agent) changes a variable while you have the page open, saving will stop and tell you which names changed rather than overwriting their work.

Sensitive Variables

Marking a variable Sensitive makes it write only. After you save, the value is hidden everywhere in Hiveku and cannot be revealed again. This applies to everyone and everything:

You, and every member of your account
Hiveku staff and support
AI agents, the MCP tools and the Hiveku CLI
The VS Code extension and hiveku-sync

Your builds and deployments still receive the real value. Only the ability to read it back through Hiveku goes away.

Tick Sensitive on the row

A confirmation explains exactly what you are about to lose access to.

Save changes

The value is hidden from that point on. The row shows Hidden. Sensitive.

Leave it blank to keep it

After the first save, the value field stays blank and shows Hidden. Sensitive. on every later visit. That blank is the convention: saving with the field untouched keeps the stored value exactly as it is. Blank never means clear for a sensitive variable, so you can rename it, change its environments, or edit other rows and save without re-entering anything.

Changing a sensitive value

You cannot un-hide a value, because nobody (including Hiveku) can retrieve it to show you. Click Replace value on the row, type a new value, and save. To make the variable readable again, untick Sensitive and supply a new value at the same time. A replacement cannot be empty: the panel refuses to save a sensitive variable with no value. If you change your mind mid-edit, click Cancel replacement and the stored value stays untouched. If you lose a sensitive value, generate a new one at the provider and replace it.

Marking a variable sensitive does not retroactively un-leak it. Copies already exported to GitHub, written to a local .env file, or held by a teammate are outside Hiveku and are unaffected. If the value may already be exposed, rotate it at the provider rather than relying on the flag.

What sensitive does not protect against

Your deployed app still receives the value in process.env, and you control your own source code. Anyone who can deploy code to your project can write a route that prints it. Sensitive variables protect against casual exposure, restricted teammates, and AI agents reading credentials into a chat transcript. They are not a barrier against someone who can already ship code to your project.

Good candidates: live payment keys, database passwords, service role keys, signing secrets. Poor candidates: anything prefixed NEXT_PUBLIC_, which is public by design and which you will want to read back while debugging.

Importing From a .env File

Click Import and paste the contents of a .env file. The parser handles comments, export prefixes, quoted values, and values containing = signs. Anything it cannot read is reported by line number rather than silently skipped. Imported variables are staged like any other edit, so review them before saving.

Working With the AI Agent

You can ask the AI to manage variables for you:

Add STRIPE_SECRET_KEY=sk_live_abc123 to production

Set NEXT_PUBLIC_ANALYTICS_ID to "G-ABC123" in production and staging

The agent can create, update and delete variables, and it can mark one sensitive. It cannot read the value of a sensitive variable, and it will tell you so rather than guessing. A sensitive variable still counts as configured, so the agent will not report it as missing.

Using Variables Locally

The VS Code extension and the hiveku-sync CLI can pull your variables into a local .env.local file. Sensitive variables are not included, because they cannot be read. Both tools list which names they skipped so your local file is not silently incomplete. Set those by hand if your local build needs them.

Build-Time vs Runtime

This distinction matters.

Build-time (NEXT_PUBLIC_*)
Runtime (everything else)

Variables prefixed with NEXT_PUBLIC_ are baked into the browser bundle at build time.

Used on the client (React components, browser JS)
Visible to anyone who views source — never put secrets here
Require a redeploy after changing the value

Examples: NEXT_PUBLIC_ANALYTICS_ID, NEXT_PUBLIC_API_URL, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY.

Variables without the NEXT_PUBLIC_ prefix live on the server.

Never sent to the browser
Safe to store secrets (API keys, DB passwords)
Pick up new values on the next restart of your app (usually instant)

Examples: STRIPE_SECRET_KEY, DATABASE_URL, OPENAI_API_KEY.

Never put a secret in a NEXT_PUBLIC_* variable. Those end up in the browser where anyone can read them.

Auto-Injected Variables

Hiveku sets these for you automatically — you don’t need to add them:

Variable	Meaning
`NODE_ENV`	`production`, `development`, etc
`AWS_REGION`	The region your project runs in
`HIVEKU_PROJECT_ID`	Unique project identifier
`DATABASE_URL`	Postgres connection (if a DB is provisioned)

Your code can use these directly: process.env.DATABASE_URL.

Never Hardcode Secrets

Bad:

const stripe = new Stripe("sk_live_abc123...");

Good:

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

If you hardcode a key into source, it ends up in git history, logs, and potentially the browser bundle — rotate it immediately if that happens.

Reading Variables in Code

Server-side (Node)
Client-side (React)
API routes

const apiKey = process.env.STRIPE_SECRET_KEY;
if (!apiKey) throw new Error("Missing STRIPE_SECRET_KEY");

const analyticsId = process.env.NEXT_PUBLIC_ANALYTICS_ID;
// Only works for NEXT_PUBLIC_* vars

export async function POST(req: Request) {
  const key = process.env.OPENAI_API_KEY!;
  // ...
}

Verifying a Variable Is Set

After adding or changing a variable:

Redeploy if it's NEXT_PUBLIC_*

Click Deploy — the new value won’t reach the browser until then.

Add a test route

Create a quick API route like /api/env-test:

export async function GET() {
  return Response.json({
    hasKey: !!process.env.MY_VAR,
  });
}

Hit the route

Visit the URL. hasKey: true confirms the variable is injected.

Never log the value itself

Logging the value can leak it into your logs. Log only presence (hasKey: true/false).

Troubleshooting

process.env.MY_VAR is undefined in the browser

Only NEXT_PUBLIC_* variables reach the browser. Rename to NEXT_PUBLIC_MY_VAR and redeploy. Regular env vars work server-side only.

I added a variable but my app still errors 'undefined'

Two common causes:

You set it for the wrong environment. Check the scope dropdown on the row: a variable scoped to Staging does nothing in production
It’s a build-time var (NEXT_PUBLIC_*) and you haven’t redeployed yet — runtime vars take effect on the next restart, build-time vars need a full redeploy

A variable shows 'Hidden. Sensitive.' and I need the value

Sensitive variables are write only and cannot be recovered by anyone, including Hiveku. Generate a new value at the provider, click Replace value on the row, and save. If you also want it readable again, untick Sensitive at the same time as supplying the new value.

The AI says it cannot read one of my variables

That variable is marked sensitive. This is working as intended. The agent can still replace it with a new value if you give it one, and it knows the variable is configured rather than missing.

hiveku-sync pull-env did not write all my variables

Sensitive variables are skipped because they cannot be read. The command prints which names it skipped. Set those by hand in your local .env.local.

A preview is missing a variable my live site has

Previews run as development and never receive Production values. If the variable is scoped to Production only, add a second entry with the same name scoped to Development (or All Environments) holding the value previews should use, usually a test key.

Values are hidden and I did not mark anything sensitive

If Hiveku cannot confirm which variables are sensitive, it hides all of them rather than risk exposing one. This is temporary and does not change your configuration. Click Refresh in a moment.

I accidentally committed a secret to git

Rotate the key immediately at the provider (Stripe, OpenAI, etc.) — assume it’s compromised. Then remove it from your source, commit the removal, and store the new value in Hiveku env vars only.

I hit the size limit

All of a project’s variables together are capped at 60KB. The panel warns you before you save and shows the current total. For genuinely large blobs (a full JSON config, a certificate chain), store the blob in object storage and keep only a reference in an environment variable.

Variable shows in Hiveku but not in my app

Check you are reading from the right environment. process.env.NODE_ENV should match the scope you set on the row. If it still fails, redeploy: occasionally runtime injection lags a previous deploy.

​Where to Find Them

​Choosing Environments

​Adding a Variable

​Editing, Renaming and Deleting

​Sensitive Variables

​Leave it blank to keep it

​Changing a sensitive value

​What sensitive does not protect against

​Importing From a .env File

​Working With the AI Agent

​Using Variables Locally

​Build-Time vs Runtime

​Auto-Injected Variables

​Never Hardcode Secrets

​Reading Variables in Code

​Verifying a Variable Is Set

​Troubleshooting

​What’s Next?

Deploy your site

Set up a database

Where to Find Them

Choosing Environments

Adding a Variable

Editing, Renaming and Deleting

Sensitive Variables

Leave it blank to keep it

Changing a sensitive value

What sensitive does not protect against

Importing From a .env File

Working With the AI Agent

Using Variables Locally

Build-Time vs Runtime

Auto-Injected Variables

Never Hardcode Secrets

Reading Variables in Code

Verifying a Variable Is Set

Troubleshooting

What’s Next?