Environments

An environment is an isolated runtime that serves one specific version of one app’s prompts and code. Every app in AgentMark starts with one environment, dev, and you add more (staging, prod, preview, a per-tenant env) as you need them. Each environment keeps its own snapshot of that app’s prompts, datasets, traces, evals, environment variables, and API keys, so the environments never read each other’s data. This page explains the model: what makes dev special, what “pinned” means, and the guarantee that ties it together. For the steps to create an environment or run a promotion, see Environments and promotions.

​

The core guarantee

The one idea to take away: the version that runs in prod is the one you already validated in staging, and pushing a fix to dev changes neither. That holds because environments fall into two kinds with different update rules:

• dev tracks your branch HEAD live. Every push to your connected branch deploys to dev immediately. Prompt-only and dataset-only edits show up right away, the way iteration should feel.
• staging, prod, and any other env you create are pinned. Each runs an immutable snapshot of your content and code that does not move on its own. It changes only when you explicitly promote a version into it.

Because a pinned environment only advances when you promote into it, no push can reach prod by accident. You move code toward production deliberately, one promotion at a time. The diagram shows the one-way flow of a version toward production. Your branch HEAD feeds dev automatically on every push. From there, a version moves into staging only when you promote it, and into prod only when you promote again. staging and prod sit at independent pinned versions (here v3 and v2), because each advances on its own promotions, not on yours to the branch.

​

Why dev is different

dev is the one environment every app has from creation, and it plays a role no other environment can:

• It is the live mirror of your branch. It exists so you always have an environment that reflects exactly what is on HEAD, with no promotion step. That is what makes iteration fast.
• It is the source of promotions, never a target. You promote out of dev (or out of another env) into a pinned one. Promoting into dev would move its pointer off HEAD and break the “dev always reflects my branch” invariant, so the model forbids it.
• It cannot be deleted. Because the live-on-HEAD environment is load-bearing for the whole promotion model, the default env is locked for the life of the app.

Everything else about dev follows from “it tracks HEAD”. A push runs the normal deployment pipeline, so build caching, handler detection, and commit-message overrides all apply to it the same way they apply to a regular deploy.

​

What “pinned” means

A pinned environment is frozen at a specific version until you promote a new one in. Two things follow from that:

• A version is a content snapshot plus a built runtime. When you promote, AgentMark writes a fresh, env-keyed copy of the source’s prompts, components, datasets, and schemas for the target, and rebuilds the target’s code at the source’s commit. The target is independent from then on: later edits to the source don’t leak into it.
• Each pinned env has its own version counter. A successful promote advances the target by one (v1, v2, v3), and the current pin is what the env serves. dev has no pin to count, so it sits at version 0.

Because the snapshot is taken at promote time, what you tested is what ships. Promoting from staging carries staging’s current pinned commit; promoting from dev carries the branch’s current HEAD.

​

Isolation between environments

Environments are sealed off from one another, which is the second half of the safety story. Each one has its own:

• Content: an independent snapshot of prompts, components, datasets, and schemas.
• Traces, evals, and metrics: data captured against one env stays scoped to it.
• Environment variables: the same key can hold a different value per env, with no app-level fallback. A build injects only the variables of the env it deploys to, so a fresh staging or prod ships without provider keys until you set that env’s variables.
• API keys: keys are scoped per env. A prod key cannot read staging’s traces, templates, or datasets, and vice versa.

This is why environments are the right tool for running one app across dev, staging, and prod. When you instead have two genuinely unrelated projects, use separate apps, which are isolated at a higher level and don’t share a promotion flow.

​

How this relates to apps and branches

Environments live one level below apps in AgentMark’s hierarchy:

• An app is a single project, backed by one default branch in a connected Git repository. It owns the prompts, the handler code, and the set of environments.
• A branch is where AgentMark reads your source from. dev follows that branch’s HEAD.
• An environment is one running version of that app. Promotions move a version between an app’s environments; they never cross app boundaries.

For the full hierarchy (organizations, apps, branches, environments, and the resources each environment holds), see Core concepts.

​

Where to go next