Environment variables

Where env comes from at every layer, and how to override it at deploy time.

Three sources, in order

When you deploy, the container's env is composed from three layers — later sources override earlier ones:

1. Bindings on the server      (MONGODB_URL, ANTHROPIC_API_KEY, ...)
2. Sandbox env set in dev      (anything you `agentry env set`)
3. Deployment env (dashboard)  (final overrides at deploy time)

The deployment's env tab is the source of truth for what runs in production. The other two are starting points the deployment env inherits unless you change them.

During development

In a fresh sandbox:

$ printenv | grep -E "(MONGODB|ANTHROPIC|AGENTRY)"
MONGODB_URL=mongodb://...
ANTHROPIC_API_KEY=sk-ant-...
AGENTRY_APP_NAME=quill

Bound services landed automatically. AGENTRY_APP_NAME is the sandbox id; your code uses it for per-app namespacing (DB name, S3 prefix, etc.).

Setting sandbox-only env

For values that should live in dev but not be inherited at deploy time:

agentry env set --sandbox <sandbox-id> DEBUG_MODE true

Or from the agent:

Set DEBUG_MODE=true in the sandbox env.

These vars are available immediately to new processes (existing processes need a restart). They're shown in the deployment form pre-filled — you can choose to carry them through or remove them.

Setting deployment-time env

In the deployment form (Deploy button) or the deployment detail page → Env tab:

• Inherited rows are pre-filled from the sandbox. You can edit, override, or delete each one.
• Add lets you set vars that weren't in the sandbox at all.
• Click Save and redeploy to apply.

These values are the only ones the production container sees.

Build-time vs runtime

Some env vars are read at build time (during npm run build), some at runtime (when the request hits the handler). Frameworks vary.

Next.js

Variable shape	When it's read	Where it lives
process.env.X inside a function body	Runtime	Server-side only, hidden from client
process.env.X outside a function body	Build time	Baked into image layers
process.env.NEXT_PUBLIC_X	Build time	Baked AND exposed to client JS

Implication: a secret used as process.env.STRIPE_SECRET_KEY inside a route handler is safe. The same secret named NEXT_PUBLIC_STRIPE_SECRET is baked into client-side bundles and shipped to every browser. Don't do that.

Vite / Astro / SvelteKit

Similar pattern — vars prefixed PUBLIC_ (or VITE_) are exposed at build time. Everything else is runtime-only.

Overrides for dev vs prod

Common pattern: prototype against a dev database, deploy against production.

1. Bind your dev MongoDB to the server: agentry service bind mongodb → enter dev URL.
2. Build and verify in the sandbox.
3. At deploy time, in the Env tab, override MONGODB_URL with the prod URL.
4. Deploy.

Production points at prod DB; dev sandboxes keep pointing at dev. No code change needed.

You can also bind two custom services with different names (mongodb-dev, mongodb-prod) and choose which env var name your code reads. That's clearer in audit logs but requires telling the agent up front.

Editing env after deploy

Same Env tab on the deployment detail page. Save and the dashboard prompts you to redeploy (env changes require a container restart).

Secrets in env

agentry stores deployment env encrypted at rest. Values flow through the build into image layers when referenced at build time (see Next.js note above). Considerations:

• Images are pushed to the private registry you connect — never anywhere public. With no registry connected, the image stays on your server only.
• Anyone with access to that registry (or shell on your server) can read baked-in build values from the image layers.
• Each build has a unique image tag, so one app's image isn't mistaken for another's.

For genuinely sensitive secrets (DB root creds, root API keys), bind a secret manager (HashiCorp Vault, AWS Secrets Manager, etc.) and have your app read at runtime instead of baking values in.

Listing env

CLI (sandbox only):

agentry env ls --sandbox <sandbox-id>

For deployments, use the dashboard → deployment detail page → Env tab. Sandbox env is also in the dashboard at sandbox detail page → Env tab.

Next

• Logs + status — diagnosing deployments that boot but misbehave.
• Ship an app — the deploy flow.
• Bindings — automatic env from server-level service bindings.