Skip to content

Environment variables (env.yaml)

Agent bundles that ship in containers, pods, or systemd units frequently need deployment-specific values — GCP project, cluster name, oncall address, ticket prefix, API tokens. .agents/env.yaml (or .env.json) is core-agent’s declaration file for those values: the recipe author lists which env vars the bundle expects, the daemon validates them at boot, and ${env:VAR} references throughout AGENTS.md, skill files, and mcp.json get resolved to the actual environment values.

Bundles without a manifest keep working unchanged — the mechanism is opt-in. Only bundles that ship an env.yaml (or env.json) get manifest-driven validation and interpolation.

In AGENTS.md and skill files, ${env:VAR} does nothing without a manifest. There is no ambient-env fallback there for a bundle that ships no env.yaml: the placeholder is handed to the model as literal text. (mcp.json is the exception — its env / headers values have always interpolated straight from the process env, with or without a manifest.) The instruction-side behaviour is the opt-in working as designed, but it is easy to walk into by accident, so the daemon says so at boot whenever loaded content still contains ${env:…} placeholders after the load.


Drop a manifest next to AGENTS.md:

.agents/env.yaml
version: 1
env:
- name: GCP_PROJECT
required: true
description: GCP project ID this daemon operates in
used_by: [AGENTS.md]
- name: ONCALL_EMAIL
required: false
default: unassigned@example.com
description: CC address for INCIDENT SUMMARY escalation blocks
- name: SLACK_TOKEN
required: true
sensitive: true
description: Bearer token for the Slack MCP
used_by: [mcp.json]

Reference them in any instruction file with the ${env:VAR} syntax:

.agents/AGENTS.md
You are the on-call agent for `${env:GCP_PROJECT}`.
When escalating, CC `${env:ONCALL_EMAIL}`.

Set the env vars via whatever mechanism your runtime provides:

  • Kubernetes: env: on the container, or envFrom: a ConfigMap.
  • Docker: -e GCP_PROJECT=... or --env-file.
  • systemd: Environment=GCP_PROJECT=....
  • Local dev: shell export or a .env file.

The daemon reads env at process start, validates required vars, and fails loud with a clear error if anything’s missing.


Both env.yaml and env.json share this shape. Shipping both files in the same .agents/ directory is an error (ambiguous which one wins).

FieldTypePurpose
versionintCurrently 1. Future breaking changes bump this and old versions get rejected with a clear upgrade path.
envlistEnv-var entries; order irrelevant.

Each entry:

FieldTypePurpose
namestringEnv var name. Must be a valid identifier (letters, digits, underscore; not starting with a digit) — the same shape as ${env:NAME} accepts.
requiredboolIf true and the env var is unset at boot, daemon fails to start with a clear error. Default false.
defaultstringValue used when required: false and the env var is unset. Ignored when the env var IS set.
sensitiveboolMarks the resolved value as sensitive — redacted in verbose logs, eventlog, and /stats-style diagnostic surfaces. Set true for tokens, passwords, API keys.
descriptionstringFree-text explanation of what the var is for. Surfaces in the “required var missing” error message so operators see context without hunting through the manifest.
used_bylist of stringsOptional grep-friendly hint about which files reference this var. The loader doesn’t validate the entries.

${env:VAR} in any of these gets substituted at load time:

  • .agents/AGENTS.md (and everything under AGENTS.d/, and @included files).
  • .agents/skills/**/SKILL.md and skill reference files under references/.
  • .agents/mcp.json values (Env, Headers) — same syntax that shipped with mcp.json originally.

Syntax rules:

  • ${env:NAME} — matches when NAME starts with a letter or underscore, followed by letters/digits/underscores.
  • Unset non-declared vars fall through to the ambient process env (via os.Getenv), then resolve to empty string. Undeclared references surface as drift warnings at boot (see below).
  • Anything that doesn’t match the syntax (${envFOO}, $env:FOO}, ${env :FOO}) passes through as literal text. A near-miss that still opens with ${env: — ${env:my-var}, ${env:2FA_TOKEN} — is reported at boot (see below), because a hyphen or a leading digit in the name is far more likely to be a typo than a deliberate literal.

Interpolation runs once per file at daemon startup (or /reload). It’s not dynamic — changing an env var while the daemon is running has no effect on already-loaded prompts until the daemon restarts.


The daemon runs the manifest through four phases at startup:

  1. Schema validation — parses the file, rejects malformed entries (empty names, duplicates, invalid identifiers).
  2. Required-var check — every entry with required: true must have a value in the process env. Missing → fatal error, daemon exits with ExitConfigError. Errors are batched (all missing vars listed at once), not fail-first, so operators see everything to fix in one round-trip.
  3. Drift diagnostics (warn only) — after all bundle files have been loaded and interpolated:
    • Names referenced via ${env:NAME} but not declared in the manifest surface as "${env:NAME} is referenced but not declared in the manifest".
    • Names named by a *_env config field but not declared in the manifest surface as "config names env var \"X\" (a *_env field) but it is not declared in the manifest".
    • Names declared in the manifest but reached by neither route surface as "manifest declares X but nothing in the bundle references it".
  4. Surviving placeholders (warn only) — see below. This one runs even when there is no manifest at all, because that is the case it exists for.

Drift diagnostics and the surviving-placeholder check are advisory. The daemon keeps running; the recipe author sees the warnings and cleans up on their next iteration.

Once every instruction file, skill, and subagent content root has loaded, the daemon checks the loaded text for ${env:…} placeholders that are still there. (mcp.json is not in scope: its values interpolate unconditionally, so nothing can survive that pass for lack of a manifest.) Anything it finds would reach the model verbatim, so it is named on stderr with the rest of the startup lines:

core-agent: agentenv: 2 ${env:...} placeholder(s) survived loading and will reach the
model as literal text: ${env:GKE_CLUSTER}, ${env:GOOGLE_CLOUD_PROJECT} — no env.yaml
or env.json in /app/.agents, so interpolation is OFF

Two situations produce it:

  • No manifest. Interpolation never ran. The remedy is to add env.yaml declaring those names — or to delete the placeholders if the bundle wasn’t meant to use the mechanism.
  • A manifest is active, but a placeholder doesn’t match the ${env:NAME} syntax. Interpolation ran and skipped it. The warning says so, and the remedy is to fix the name.

The second case used to be worse than a warning, and it is worth knowing why it no longer is (#1139). The commonest way to miss the syntax is to write the shell spelling, ${GKE_CLUSTER} — and the agent’s system prompt was handed to the model runtime as a template, whose own placeholder syntax is {name}. ${GKE_CLUSTER} matched it, named a variable nothing had set, and ended every turn before a token was sent, with an error that named neither the file nor the token. So the remedy above described a run that could not happen: you would not see the warning and a degraded prompt, you would see the warning and a dead agent. Instruction text is no longer a template of any kind — braces reach the model exactly as written — so ${env:NAME} is the one substitution that happens in loaded content, and everything else in braces is literal text, warned about and passed through.

The check reads the loaded content rather than inferring from the manifest’s absence, so a bundle that ships no manifest and references nothing stays silent — which is most bundles.

It is a warning, not a fatal error, because ${env:...} shows up legitimately as literal text in content that documents the feature — a skill whose reference file quotes an example mcp.json is a real and correct thing to ship. If your persona is one of those, the line is noise you can ignore; there is no suppression flag, and adding one would recreate the silence this exists to break.

${env:NAME} is not the only reference the drift check counts, because it is not the only way the bundle reaches the environment:

ConventionWhereWhat it doesWhen it resolves
${env:NAME}AGENTS.md, skills, mcp.json valuessplices the value into text the model readsonce, at load
a *_env config fieldconfig.jsonhands the name to the component that owns the fieldlate, at use

The second exists because some values must not be spliced. alerts.targets[].url_env is re-read on every fire, so rotating the Secret needs no restart, and the webhook URL never lands in the in-memory config that log and status surfaces can echo. Config is parsed by pkg/config and never flows through the interpolator, so writing "url": "${env:MY_WEBHOOK}" does not work — it isn’t expanded, and the URL validator rejects the literal for having no scheme.

The fields that name an env var are, today:

  • alerts.targets[].url_env
  • alerts.targets[].auth.bearer_env
  • alerts.targets[].auth.basic_env_user / basic_env_pass
  • attach.token_env
  • tools.call_peer.token_env

Both routes count as a reference, so declaring a var in env.yaml and using it only from config is not drift. Before this landed it was reported as unreferenced — a live kube-platform-native deployment warned that nothing referenced PLATFORM_AGENT_ALERT_WEBHOOK while an alert target was reading it by name.

Discovery is by JSON-tag convention (*_env), not a hand-maintained list, so a new *_env field is picked up with no wiring. The corollary: an env-name field tagged something else — webhook_secret, token_var — is invisible to the check. Name new fields with the suffix.

Those variables are the daemon’s, not the agent’s

Section titled “Those variables are the daemon’s, not the agent’s”

Every variable named by a *_env field, plus the one --attach-token names, is withheld from every process the daemon starts: bash tool commands, hooks, MCP stdio servers, and sciontool. Startup says which:

core-agent: child processes do not inherit ALERT_BEARER, CORE_AGENT_ATTACH_TOKEN

The attach token answers the agent’s own permission prompts. Inherited, it let the agent approve its own pending prompt, add a standing allow rule, or reset a tripped guardrail — not by a direct curl, which is itself a gated call an operator sees, but through test code it wrote and an approved go test then ran (#1157). An alert bearer, inherited the same way, let it post as the daemon.

Scrubbing the child’s environment is not enough on its own. /proc/<pid>/environ holds the environment a process was started with, and any same-user process can read it, so a child could recover the token with cat /proc/$PPID/environ. While the daemon holds one of these credentials it therefore also makes itself non-dumpable on Linux (prctl(PR_SET_DUMPABLE, 0)), which closes that read along with /proc/<pid>/mem and same-user ptrace. The cost is no core dumps and no attaching a debugger to a running daemon as the same user; launching it under a debugger still works.

The same names are never spliced into model-visible text either: ${env:NAME} for a withheld name interpolates to nothing, with one log line, whether or not env.yaml declares it. Skill resources are re-read from disk on every load and loading them never prompts, so without this an agent could write ${env:…} into a skill file and read the token back.

Behaviour change for hooks and MCP servers. A hook that used one of these variables — say, posting to the alert webhook from a *_env field — no longer sees it, and hooks have no env block to hand it back. Read the secret from a file the hook owns instead. An MCP server can be handed a value explicitly through mcp.json’s env block, applied on top of the scrubbed environment — but that server is an ordinary, dumpable process, so the value is readable from its /proc/<pid>/environ by any same-user process, the agent’s included. Hand over only what the server cannot work without.

A listener that needs no credential is refused. If the agent has the bash tool, the daemon will not start an attach listener with no authentication, whether on loopback or on a Unix socket (#1201). Such a listener would let the agent’s bash call perms/respond with nothing to steal, which makes everything above moot. --attach-allow-unauthenticated-local is the explicit opt-out. See Attach HTTP → Auth model.

What this does not cover:

  • An ancestor’s environment, when the token comes from an env var. A daemon started with --attach-token from a shell that exported the token leaves it in that shell’s /proc/<pid>/environ, which nothing in the daemon controls. In a container the daemon is PID 1 and has no such ancestor. On a workstation, use --attach-token-file instead (#1201): the token is read from a file once and never enters any process’s environment. --attach-token-file <(printf '%s\n' "$tok") with an unexported shell variable leaves nothing on disk either. If you stay on --attach-token, put the token in the daemon’s environment only (CORE_AGENT_ATTACH_TOKEN=… core-agent …), not in your shell’s.

  • Files and other processes on the same host that hold the token. The attach clients (core-agent-tui, core-agent attach, core-agent ls) take the token named by --token-env: they read it once, drop it from their environment so their own children (an $EDITOR, a clipboard helper) never see it, and on Linux make themselves non-dumpable (#1201). With --token-file the token never enters the client’s environment, which also closes the few milliseconds between exec and the read. What is left: a regular token file stays where it is (neither the daemon nor the clients delete it, and file permissions do not stop the same user). The daemon’s agent file tools, @include and directly-named bash reads are refused on the daemon’s own token file, but bash can reach it by other spellings, along with the shell history of a command that carried the token and any other process holding it. The agent can read all of those like anything else its user owns. Use a pipe (<(…)), or keep the file where the agent’s user cannot read it.

  • Credential files, beyond what the gate can see. The multi-session bearer table (attach.multi_session.auth.table_file) is the attach credential in that mode, and the daemon’s attach token file (--attach-token-file / attach.token_file) is the credential otherwise. Agent file tools are refused on it in every mode, an instruction file can’t @include it, and a bash command that names it directly is refused. The daemon is also non-dumpable while it’s configured (#1201). But bash isn’t path-scoped: cd and a bare name, a glob or a variable still reach the file whenever the daemon’s user can read it. Startup warns when that’s the case. For the bearer table, store token_sha256 digests instead of tokens (#1213). Then reading it yields nothing that authenticates, and startup warns by identity about any row still holding a plaintext token. That covers reading only: an agent that can write the table can still add its own row for the next boot, so mount it read-only. The single-user attach token file has no hashed form yet. For it, and for a table with plaintext rows, disable bash on that daemon, or make the file unreadable to its user once loaded. See Keeping the table away from the agent.

  • A daemon running as root with CAP_SYS_PTRACE. Non-dumpable only stops processes without CAP_SYS_PTRACE. A root daemon passes its capability bounding and inheritable sets to every process the agent starts, so those processes can read the daemon’s /proc/<pid>/environ and memory anyway. Startup warns about this; it doesn’t refuse to start (#1201). The warning fires while the daemon holds a credential, in either of two cases: it runs as root (real or effective uid 0) with CAP_SYS_PTRACE in its bounding or inheritable set, or it holds that capability in its ambient set.

    core-agent: warning: this daemon runs as root with CAP_SYS_PTRACE in its capability bounding set, so every process the agent starts can read this daemon's memory ...

    Run as a non-root user, or drop the capability. In Kubernetes that means securityContext.capabilities.drop: [ALL] (or [SYS_PTRACE]) and no privileged pod. Docker’s default capability set already drops it.

  • Provider and cloud credentials (ANTHROPIC_API_KEY, ADC, GH_TOKEN). SDKs consume them, not config by name, so they are not in the set, and a coding agent’s own tooling legitimately needs them.

  • Operator-triggered helpers in the local TUI ($EDITOR, the clipboard helper) start from the full environment. The operator launches them, not the model — but an editor opened in a repository can run configuration that repository controls.


Setting sensitive: true doesn’t change where the value ends up (it still gets interpolated into the prompt, which the model sees) — it flags the value for redaction in log paths that already sanitize secrets:

  • Verbose daemon logs.
  • Eventlog transcripts.
  • /stats and /mcp diagnostic renderers.

For MCP header values that carry tokens, the existing mcp.json redaction already applies — sensitive: true on a manifest entry adds a second layer for the same value.


  • Bundles without env.yaml / env.json behave exactly as before #322 landed: no interpolation happens, no validation runs, no drift warnings. Existing operators are unaffected. The one thing that changed since is the surviving-placeholder warning — a boot line only, and only for bundles whose content actually contains ${env: markers.
  • mcp.json’s pre-existing ${env:VAR} support in Env / Headers keeps working identically. The regex + resolver moved to pkg/agentenv internally but the semantics are preserved.
  • Adopting the mechanism is a per-bundle opt-in: drop a manifest, replace literals with ${env:VAR} references, populate env at deploy time.

Migrating a bundle that currently uses sed-based placeholders (e.g. the gke-troubleshoot-agent recipe used __GCP_PROJECT__ before #322):

  1. Add .agents/env.yaml declaring the three variables (required: true).
  2. Replace __GCP_PROJECT__ → ${env:GCP_PROJECT} throughout the bundle files.
  3. Remove any operator-facing sed step from setup scripts / docs.
  4. Populate the env vars via ConfigMap envFrom / Deployment env: / whatever the runtime already uses.
  5. Deploy and rely on fail-loud validation to catch missed values.

See examples/gke-troubleshoot-agent/deploy/base/config/env.yaml for the canonical shape.