> ## Documentation Index
> Fetch the complete documentation index at: https://puzzlet-9ba7bb98.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

> The mental model behind AgentMark environments: dev tracks your branch live, and every environment gets its own isolated runtime, API keys, and environment variables.

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](/deploy/environments-and-promotions).

## 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](/deploy/webhooks)**, 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](/deploy/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](/introduction/core-concepts#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](/introduction/core-concepts).

## Where to go next

<CardGroup cols={2}>
  <Card title="Environments" icon="rocket" href="/deploy/environments-and-promotions">
    Create an environment and configure its API keys and variables.
  </Card>

  <Card title="Webhooks" icon="git-merge" href="/deploy/webhooks">
    Register the hosted client an environment dispatches to.
  </Card>

  <Card title="API keys" icon="key" href="/deploy/api-keys">
    Mint a key scoped to a single environment.
  </Card>

  <Card title="Regression gates" icon="shield-check" href="/deploy/regression-gates">
    Fail a CI build when scores regress against a baseline.
  </Card>
</CardGroup>

<div className="mt-8 rounded-lg bg-blue-50 p-6 dark:bg-blue-900/30">
  <h3 className="font-semibold mb-3">Have questions?</h3>
  <p className="mb-4">Reach out any time:</p>

  <ul>
    <li>
      Email the team at <a href="mailto:hello@agentmark.co" className="text-blue-600 hover:text-blue-800 dark:text-blue-400 dark:hover:text-blue-200">[hello@agentmark.co](mailto:hello@agentmark.co)</a> for support
    </li>

    <li>
      Schedule an <a href="https://cal.com/ryan-randall/enterprise" className="text-blue-600 hover:text-blue-800 dark:text-blue-400 dark:hover:text-blue-200">Enterprise Demo</a> to learn about AgentMark's business solutions
    </li>
  </ul>
</div>