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.

One exception: deployed Development and Staging sites fill gaps from each other. When Development has no value of its own for a name, it uses the Staging value, and Staging uses the Development value the same way. A value borrowed like this wins over an All Environments value. Production and previews never borrow. To keep a value out of Development or Staging, give that environment a value of its own. Previews always run as development. The live preview and branch previews receive 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

Saving also updates your deployed site’s runtime variables, without a redeploy. If Hiveku cannot update the running site, the save message says so: redeploy to apply them. Build time variables (NEXT_PUBLIC_*) always 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 an AI tool) saves a change to these variables while you have the page open, your save stops and nothing is saved, so their work is never overwritten. Reload variables shows the latest, so you can make your change again; Keep editing keeps your edits on screen.

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. When several sites use the same values (a shared API key, a mail provider’s settings), keep them in an environment group and link the group to each site. A change to the group reaches every linked site. The site’s own variables always win over a group’s: the Environment groups card on this page shows which group variables the site replaces.

Working With AI

Hiveku AI

You can ask the AI chat in the editor 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

Hiveku AI can add, change and delete variables and list their names, within what your own role allows. It never reads a value, sensitive or not. A sensitive variable still counts as configured, so it will not report one as missing.

AI tools you connect

Claude Code with the Hiveku plugin, Codex, the VS Code extension and Hiveku Sync work with the same variables through Hiveku’s tools. A tool can do only what the person whose Hiveku key it uses can do on this page. What they can read

Names, environments and whether each variable is sensitive, never values: project_secrets_list (it requires metadata_only: true) and project_secrets_get. project_env_matrix compares environments without showing any value, including the variables a site gets from its linked environment groups.
A non-sensitive value, only through project_secrets_reveal, after a person approves it (below).
Never a sensitive variable or a platform credential (such as the staging and production database URLs or the Supabase service role key), nor any value that names or holds the credentials of a database production can run with. A reveal lists those names as withheld, with the reason.

How a reveal is approved

The tool asks

Its first call answers with an approval link instead of values.

A person decides

Anyone in the account who can see the site’s variables opens the link. The page (“An AI tool asked to see this site’s variable values”) shows who asked, for which environment, and which names can be shown, never a value. Click Approve or Decline.

The tool reads once

The tool repeats its call. The approval works once, within 10 minutes, and only for the names the person saw.

Some clients ask you themselves, and their own prompt is the approval, so no link is needed: Claude Code with the Hiveku plugin 0.27.30 or later, Claude Code in a folder set up by the VS Code extension 0.91.8 or later (in older folders, run Hiveku: Refresh Setup), the Codex plugin 0.3.14 or later, and Codex set up by Hiveku Sync 0.5.5 or later. Every other tool gets the link. Every reveal, and every approval of one, is recorded in the site’s variable history: the names, the environment and who, never a value. AI tools read that history with project_secrets_history. A project allows 20 reveals and 20 approval requests an hour. What they can change

Set a variable for one environment with tier (development, staging or production). A name set without a tier applies to every environment, production included.
Generate values on the server instead of sending them, for up to 20 names at a time. Generated values are never shown or logged, are sensitive unless the tool says otherwise, and fill only names that have no value yet, unless the tool asks to rotate them.
Check the version first with expected_version: a change made against an older read of the variables is refused (409 stale_version), so two writers never overwrite each other.
Mark sensitive, one way only: an AI tool can make a variable write-only (project_secrets_mark_sensitive, or sensitive: true when it sets one), but only a person can make it readable again, on this page, with a new value.
Replace one environment’s variables with exactly the set it gives (project_secrets_replace). It runs as a dry run first, listing what would be added, changed, removed and kept, and is applied with the version that dry run read. Variables the tool could not see (sensitive ones, platform credentials, database URLs) are kept unless it names them, and a replace never changes the database connection Hiveku set up for the site.
Delete one variable at a time. Deleting every variable needs an owner’s or admin’s key and a confirmation.

A set, a delete and an applied replace answer takes_effect for each environment they reach: live (the running site already uses it), applying (an update already under way applies it in a moment) or next_deploy (the next deploy of that environment applies it; always so for NEXT_PUBLIC_* values, which are built in). For the preview, it says whether the running preview has it (applied), gets it when it next starts (next_start), needs a restart (restart_needed), or keeps the old value until it is rebuilt (next_rebuild).

Claude Code with the Hiveku plugin, Claude Code in folders the VS Code extension sets up, and Codex ask you before every change to your variables and before every reveal.

Using Variables Locally

Three tools write a site’s values into a local file for your dev server. All three go through the same reveal, so a person approves every pull.

Tool	Command	Environments
Claude Code with the Hiveku plugin	`/hiveku:env`, which runs `hiveku env pull`	Development by default; staging or production when you ask for one by name
VS Code extension	Hiveku: Pull Env to .env.local	Development
Hiveku Sync	`hiveku-sync pull-env`	Development by default; `--target staging`, or `--target production` with `--yes`

The tool shows an approval link (the VS Code extension opens the approval page). Anyone in the account who can see the site’s variables can approve it, you included. The tool waits up to 10 minutes and writes the file as soon as the approval lands.
Development values go to .env.local, staging values to .env.staging.local, and production values to .env.production.local. The file is readable by you only.
Sensitive variables and platform credentials are never written. Their names are listed in the file as comments, with the reason, so your local file is not silently incomplete. Set those by hand if your local build needs them.
If no value comes back, nothing is written and an existing file is left as it is.
Values the site gets from its linked environment groups are included, under the same rules; the site’s own value wins over a group’s.

In VS Code, Hiveku: Push .env.local to Hiveku saves what is in .env.local as Development values only, so it can never change Staging or Production.

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)
Reach your deployed site when you save, without a redeploy (if Hiveku cannot update it, the save says so: redeploy)

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 reach the deployed site when you save (the save message says so if they could not), 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

This is working as intended. AI tools never read sensitive variables or platform credentials, and Hiveku AI reads no values at all. The AI can still set a new value if you give it one, and it knows the variable is configured rather than missing. For a non-sensitive value, an AI tool you connect can ask for a reveal, which a person approves.

An AI tool gave me a link to approve

The tool asked to read some of the site’s non-sensitive values. The page shows who asked, for which environment, and which names, never a value. Approve only a request you expected; otherwise click Decline. An approval works once, within 10 minutes. If the link has run out, ask the tool to request it again.

A local pull did not write all my variables

Sensitive variables and platform credentials are never written to a local file. Their names are in the file as comments, with the reason. Set those by hand in your local env file if your local build needs them.

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.

What’s Next?

Deploy your site

Push env changes live

Set up a database

Uses DATABASE_URL automatically

Share variables across sites

Environment groups several sites link to

​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

​Sharing Variables Between Sites

​Working With AI

​Hiveku AI

​AI tools you connect

​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

Share variables across sites

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

Sharing Variables Between Sites

Working With AI

Hiveku AI

AI tools you connect

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?