Environments

An environment is an isolated slice of one app: its own API keys, environment variables, traces, evals, and metrics. Every app in AgentMark starts with one environment, dev, and you add more (staging, prod, preview, a per-tenant env) as you need them. Environments never read each other’s data. This page explains the model: what makes dev special, and what isolation between environments buys you. For the steps to create an environment, see Environments.

​

Why dev is different

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

• It’s the live mirror of your branch. On every push to your connected branch, context-sync mirrors your app’s .outerlayer/ context directory into the Dashboard and advances dev’s commit pointer, so dev always reflects what’s on HEAD.
• You can’t delete it. AgentMark locks the default environment for the life of the app.

​

Other environments

Environments beyond dev (staging, prod, preview, or whatever names fit your workflow) give you isolated infrastructure to point at your own deployments:

• Their own API keys, scoped so a staging key can’t read prod’s traces or vice versa.
• Their own environment variables, so the same key can hold a different value per environment.
• Their own Webhook URL, so you can register a different hosted client per environment (for example, pointing staging at a preview deployment and prod at your production service).

Creating one of these environments provisions the isolated infrastructure above; you decide what to point each one at.

​

Isolation between environments

Each environment has its own:

• Traces, evals, and metrics: data captured against one environment stays scoped to it.
• Environment variables: the same key can hold a different value per environment, with no app-level fallback. The environment’s registered client reads only its own variables at runtime.
• API keys: AgentMark scopes keys per environment. A prod key can’t read staging’s traces or scores, 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 sit isolated at a higher level.

​

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 context, the client code, and the set of environments.
• A branch is where context-sync mirrors your source from. dev follows that branch’s HEAD.
• An environment is one isolated slice of that app’s API keys, environment variables, and telemetry.

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

​

Where to go next