CLI and config

elan.yaml reference

elan.yaml is the deploy contract: one file per repository, declaring every agent in it and everything the platform must provision, permit or enforce for them. It holds deploy-time facts only — what an agent is lives in its MANIFEST, and the contracts page explains why there are two files.

Most values here are enforced outside your process — by a network policy, a quota, an admission check, an injected secret — which is what makes them binding on code that does not cooperate; the few that are accepted and not yet acted on say so below. The same model parses it in elan validate and on submit, so the two cannot disagree about whether a file is well-formed.

A complete example

Four targets: one isolated agent with its own pod, two sharing a group, and one taking every default.

apiVersion: elan.dev/v1
kind: Project

tenant: acme
project: agents

source:
  repo: https://github.com/acme/agents
  ref: "6f1c0a9e4b2d8f0713ac5e29b4d1f6a8c0e37d52"   # rewritten by elan deploy
  targetsRoot: .

deploy:
  canary: invoice-triage

artifacts:                         # the project's one bucket
  retentionDays: 365
  origins: ["https://app.acme.example"]

defaults:
  resources: {cpu: "500m", memory: "1Gi"}
  scaling:   {minReplicas: 0, maxReplicas: 5}
  llm:
    models: [gemini-flash-latest, gemini-2.5-pro]
    keys:   {google: default}      # a NAME in your own llm secrets
  egress: []

groups:
  back-office:                     # one pod for two agents
    resources: {cpu: "500m", memory: "1Gi"}
    scaling:   {minReplicas: 1, maxReplicas: 4}
    database:  {enabled: true}
    egress:
      - host: api.payments.example

targets:
  invoice-triage:                  # isolated: a pod of its own
    owner: {team: billing}
    resources: {cpu: "1", memory: "2Gi"}
    llm: {models: [gemini-2.5-pro], keys: {google: default}}
    egress:
      - host: api.payments.example
        paths: ["/v1/refunds/*"]   # recorded, NOT enforced
    secrets:
      - {name: payments-api-key, env: PAYMENTS_API_KEY}
    database:  {enabled: true}
    artifacts: {enabled: true}
    env: {INVOICE_REGION: eu}

  expense-notes:                   # shares the back-office pod
    deployment: {runtime: shared, group: back-office}
    secrets:
      - {name: payments-api-key, env: PAYMENTS_API_KEY}

  vendor-lookup:                   # shares the back-office pod
    deployment: {runtime: shared, group: back-office}

  refund-flow: {}                  # takes every default

Top level

source

You do not write ref by hand. elan deploy resolves your branch to a commit and rewrites the field before submitting, so a deployment is reproducible from this file alone. elan init writes forty zeroes until then — quoted, because forty unquoted zeroes are a YAML integer and fail as “not a valid string”.

There is no dockerfile key. The platform owns the build: a tenant-supplied build definition is an attack surface it declines to have, and its own layer order is what keeps one image per repository cheap to rebuild.

deploy

defaults

Inherited by every target, and overridable per target. Only these four blocks may appear here; secrets, env, the database, artifacts, owner, labels and deployment are per-target facts with no default form.

targets

Every agent and workflow in the repository, keyed by slug (5–16 characters). The key set must equal the set of targets the repository actually contains, in both directions: an undeclared target is the one nobody reviewed, and a declared one with no module would provision a database and a topic for nothing. elan new agent <slug> writes both halves so they cannot drift. Every field is optional — {} takes every default.

Per-target fields

The blocks

resources

What one pod asks for — and therefore what it is billed at. You do not choose the machine: the node is shared between tenants, so its size is a packing decision the platform makes for all of them.

Those ceilings bound any one agent. Your tenant as a whole is bounded by a quota on its namespace.

scaling

minReplicas may not exceed maxReplicas. A workload that has drained its queue returns to zero after about five minutes of quiet. A cold start was measured at a median of about thirteen seconds while a sandboxed node is available, and well over a minute when one has to be created — which is why the platform holds one such node warm for the whole cluster. minReplicas: 1 buys that warmth again, per agent, and bills you for it.

llm

models is enforced twice, and the second one is the real one. At deploy time each manifest's model must be in the list. At runtime your egress allowlist is derived from it, so a pod can reach the providers of these models and nothing else — whatever SDK your agent uses, because it is a network rule rather than a library your code could route around. A model starting gemini opens Google's endpoint; gpt, o1, o3, o4 and chatgpt open OpenAI's; claude opens Anthropic's. A model with any other prefix opens nothing, and its call fails at the proxy naming the hostname.

keys names a provider, not a variable. The platform injects the key under the variable that provider's SDK reads: google as GOOGLE_API_KEY, openai as OPENAI_API_KEY, anthropic as ANTHROPIC_API_KEY. You cannot write those names yourself because GOOGLE_ is a reserved prefix. The secret is set with elan secret set llm <name> and is scoped to your tenant, so it cannot name another tenant's. A provider other than those three passes validation and fails the deploy later, after resources have been provisioned — check the spelling.

egress

Third-party hosts your tools may reach. Default deny: anything not listed is refused. Your model providers are added from llm.models automatically.

secrets

A name, never a value: the value is set out of band and appears in neither this file nor git. Not inheritable and not allowed under defaults — each workload's secret holds only what its targets declared, because a shared one would put every agent's credentials in reach of every agent. A running pod keeps the value it started with until something replaces it. The secrets guide covers the whole chain, including a secret that was declared and never set.

Unlike env, a secret's env is checked only against that pattern: the contract does not refuse a reserved name here. Do not use one.

database

The pod connects with a role that can read and write rows and cannot change the schema; the session tables are created when the database is provisioned. Another workload's database is unreadable from yours — but the members of a group share one.

artifacts

Retention and browser origins belong to the bucket every agent in the project shares, so they are declared on the project. Putting either here is refused with that explanation, because a per-target value would leave provisioning order deciding which one won.

A filename prefix chooses the scope, the way ADK's own user: does, so there is nothing new to call:

await tool_context.save_artifact("report.pdf", part)        # this conversation
await tool_context.save_artifact("user:prefs.json", part)   # this end user
await tool_context.load_artifact("agent:tone.md")           # this agent
await tool_context.load_artifact("project:policy.md")       # every agent here

The two shared scopes are read-only to an agent, held by storage permissions and not only by a check. See files and multi-modal for what reaches a model, and the group caveat below before you share a pod.

Project artifacts

At the top level, beside defaults rather than inside it, because defaults means “inherited by every target” and these describe one bucket.

Retention ages each version on its own, so old versions of a live file go before the newest does; a read with no version is unaffected, a caller pinned to an old version is not. origins has to be declared because it cannot be derived: the browser uploads cross-origin to the storage host, from a page on your site. List every origin a page might be served from, http://localhost:<port> included, or that one fails as an opaque network error with nothing in any log. The upload is still authorized by your backend; declaring an origin only configures the bucket.

owner

env

Plain environment variables for the pod, as a map. Names must match ^[A-Z][A-Z0-9_]*$ and must not be reserved; both are refused when the file is parsed. Values are visible in the rendered manifest, so anything sensitive belongs in secrets.

labels

A map of strings, on a target or a group. It is accepted and kept in the file, and the platform does not apply it to anything today — your workloads carry only the platform's own labels.

deployment

Isolated and shared deployment

By default every target gets its own pod, its own service account, its own database and its own scaling, and moves to a new image only when something it is built from changes — its own directory, or code it shares with the rest of the repository. That is runtime: isolated, and every guarantee on this page holds unless you trade it away.

Why you might not want that

Every pod is billed at a 250m / 512Mi floor whatever it requests, so a project with five small agents pays for 1.25 vCPU before doing any work — and if they scale to zero, you wait through five cold starts instead of one. A group is several targets sharing one pod, one service account, one environment and one database:

groups:
  back-office:
    resources: {cpu: "500m", memory: "1Gi"}
    scaling:   {minReplicas: 1, maxReplicas: 4}

targets:
  expense-notes:
    deployment: {runtime: shared, group: back-office}
  vendor-lookup:
    deployment: {runtime: shared, group: back-office}
  receipt-ocr:
    deployment: {runtime: shared, group: back-office}

Three agents, one pod, one bill, one warm process.

What you trade away

What does not change

Addressing. A caller names the agent — elan invoke expense-notes --text … — and there is no group anywhere in the topic, the subscription, the CLI or the API. So moving an agent into a group to save money breaks nothing that calls it, and moving it back out does not either.

Session identity. Each member keeps its own ADK app name, <tenant>--<project>--<agent>, so conversations do not blur together although their rows live in one database. Everything outside the process — the gVisor sandbox, the default-deny network policy, the egress proxy, image signing and the namespace quota — applies exactly as before.

What a group is not

It is not a security boundary. Members share a process, a service account, an environment and a database — each can already read the others' DATABASE_URL. Group agents because they are operationally alike, not because you trust them equally.

# payroll must not read expense-notes' files:
targets:
  payroll: {}                            # isolated: its own pod, its own identity
  expense-notes:
    deployment: {runtime: shared, group: back-office}

The rules, and why each is a refusal

A group is checked when the file is parsed — before a build — and each of these is refused rather than defaulted, because every plausible default fails much later and much worse:

One thing is not refused: a shared target's own database and artifacts blocks are replaced by the group's without a word. State them on the group.

groups

A group is the pod, so every pod-shaped fact lives here. Group slugs follow the target rules — 5–16 characters — and share their namespace.

There is no llm, env, secrets or owner on a group. Those stay on each member — model choice may differ between members — and only the names that become environment variables have to agree.

How values are resolved

For an isolated target:

resources  = target.resources ?? defaults.resources
scaling    = target.scaling   ?? defaults.scaling
llm        = target.llm       ?? defaults.llm
egress     = target.egress    ?? defaults.egress
database   = target.database
artifacts  = target.artifacts

For a shared target:

resources  = group.resources  ?? defaults.resources   # the target cannot state these
scaling    = group.scaling    ?? defaults.scaling
egress     = group.egress     ?? defaults.egress
llm        = target.llm       ?? defaults.llm        # still per target
database   = group.database                         # shared
artifacts  = group.artifacts                        # shared

Always per block, never per field. secrets, env, owner and labels are the target's own in both cases.

Reserved environment variables

These are refused as a key of env, when the file is parsed. Most would let a pod point itself at somebody else's resources.

TARGET_SLUG           TARGET_SLUGS          TARGETS_ROOT
BUILD_SHA             MODEL_OVERRIDE        DATABASE_URL
ARTIFACT_BUCKET       BROKER                EVENTS_TOPIC
DLQ_TOPIC             INVOKE_SUBSCRIPTION   RESUME_SUBSCRIPTION
TENANT_SLUG           PROJECT_SLUG          PUSH_TRANSPORT
PUSH_SA_EMAIL         EXPECTED_AUDIENCE     LEDGER_SERVICE_URL
OBSERVABILITY_SERVICE_URL                   ACTIONS_SERVICE_URL
AUTH_MODE             JWKS_URL              JWT_ISSUER
JWT_AUDIENCE          JWT_ALGORITHMS

and every name starting:
AGENTKIT_    PUBSUB_    GOOGLE_    GCLOUD_    CLOUDSDK_

• INVOKE_SUBSCRIPTION would point your pod at another agent's invocations — reading somebody else's messages and acknowledging them away.
• TENANT_SLUG and PROJECT_SLUG name every topic and subscription a pod derives, so they are the same attack, less obviously.
• MODEL_OVERRIDE substitutes the model after the llm.models check has passed, so the allowlist would stop describing what runs. It works only on your own machine, under AGENTKIT_ENV=local.

As noted under secrets, a secret's env is not checked against this list. Treat it as reserved there too.

Limits and patterns

The crosscheck against your MANIFESTs

After the build, the platform reads every target's manifest out of the image — inside the sandboxed builder, never by importing your code in its own process — and checks the two files against each other. A deploy is refused when:

• a key in targets has no matching module in the repository;
• a module in the repository is not declared in targets;
• a MANIFEST.model is not in that target's resolved llm.models;
• a tool binding's URL names a host that is not one of that target's egress hosts;
• an MCP tool binding has no tool_filter, so it would offer every tool that server has — including whatever it adds next.

elan validate runs those five on your machine, after the same parse the service does. Three more checks happen only on submit, because only the platform knows the answer:

• the file's tenant must be your token's;
• a target whose own directory changed must bump its MANIFEST version — not on its first deploy, and not when only shared code changed, since that would mean editing every manifest to ship one fix;
• the account must have no unpaid balance.

Every problem is reported, not just the first: fixing one, pushing and waiting for a build to report the next is how a five-minute edit becomes an afternoon. A refusal on submit comes back as 422 with problems[], each naming the field by its dotted path — see the deployments API, and the projects API to validate a file without deploying it. What goes in a manifest is in building an agent.