> ## 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

> Run the same app across isolated environments like dev, staging, and prod.

A new app starts with one environment, `dev`, that tracks your branch HEAD live. Create `staging` and `prod` to give the same app its own API keys, environment variables, and traces per environment.

For the model behind this (what "pinned" means and why `dev` is special), see [Environments](/concepts/environments). This page covers the steps.

## The `dev` environment

Every app has exactly one default environment, named `dev`, created automatically with the app. Two behaviors matter when you work with it:

* **It tracks branch HEAD live.** `dev` always reflects your connected branch's current commit.
* **You can't delete it.** The default env stays locked for the lifetime of the app.

## Creating an environment

Open the environment dropdown in the breadcrumb at the top of the Dashboard and click **New environment**.

<img src="https://mintcdn.com/puzzlet-9ba7bb98/2-DXfPaZM6zlgeng/images/platform/deploy/environments-and-promotions/env-dropdown-open.png?fit=max&auto=format&n=2-DXfPaZM6zlgeng&q=85&s=fd04b1735299d6cc143fb94d626b20a9" alt="Breadcrumb environment dropdown open from a non-default env, listing dev with the default suffix and staging with the no-pin suffix, plus the New environment menu item" className="w-full rounded-xl border border-gray-800 shadow-2xl mb-8" width="1440" height="900" data-path="images/platform/deploy/environments-and-promotions/env-dropdown-open.png" />

The dropdown shows every env on the app and hosts **New environment** for creating another one.

Names must match `^[a-z][a-z0-9-]{1,39}$`: lowercase letters, digits, and hyphens, starting with a letter, 2–40 characters. Common choices are `staging`, `prod`, `preview`, `eu`, `tenant-acme`.

<img src="https://mintcdn.com/puzzlet-9ba7bb98/2-DXfPaZM6zlgeng/images/platform/deploy/environments-and-promotions/create-env-dialog.png?fit=max&auto=format&n=2-DXfPaZM6zlgeng&q=85&s=51ae64c606c25443425d8c8ae3ee19e4" alt="Create environment modal dialog with a single Name field and helper text reading 'Lowercase letters, digits, and hyphens. Must start with a letter. 2–40 chars.', plus Cancel and Create actions" className="w-full rounded-xl border border-gray-800 shadow-2xl mb-8" width="1440" height="900" data-path="images/platform/deploy/environments-and-promotions/create-env-dialog.png" />

A newly-created env starts in the **no-pin** state, with no pinned version yet.

<Tip>
  Creating an env doesn't auto-mint an API key. The post-create dialog links straight to the [API keys](/deploy/api-keys) page filtered to the new env so you can mint one scoped to it. A key pinned to one env can't reach another env's traces, templates, or datasets, so a `prod` key can't reach `staging`. A key scoped to environment **kinds** instead reaches every env of those kinds (including future PR previews) and picks the target per request: see [API key environment scope](/api-reference/authentication#api-key-environment-scope).
</Tip>

<img src="https://mintcdn.com/puzzlet-9ba7bb98/2-DXfPaZM6zlgeng/images/platform/deploy/environments-and-promotions/post-create-cta-dialog.png?fit=max&auto=format&n=2-DXfPaZM6zlgeng&q=85&s=c5ec9f9f2512e19f8a23b051ff874be2" alt="Environment created dialog appearing after a successful create, naming the new environment (preview), with an info note that AgentMark created no API key automatically and a primary Create an API key for this environment button alongside a Later button" className="w-full rounded-xl border border-gray-800 shadow-2xl mb-8" width="1440" height="900" data-path="images/platform/deploy/environments-and-promotions/post-create-cta-dialog.png" />

<Warning>
  Environments per app are tier-limited: 1 on Free, 3 on Growth, 5 on Team, and configurable on Enterprise. The default `dev` env counts toward the limit, so on Free it consumes the only slot and creating any additional environment fails with a message naming your current plan. See [Billing and usage](/deploy/billing-and-usage#usage-limits).
</Warning>

## Permissions

These per-app permissions gate environment actions:

| Permission           | Action                                                          |
| -------------------- | --------------------------------------------------------------- |
| `environment.read`   | See the env dropdown and per-env settings                       |
| `environment.insert` | Create a new environment                                        |
| `environment.delete` | Delete a non-default environment (with typed-name confirmation) |

See [Users and access control](/deploy/users-and-access-control) for how permissions roll up into roles, and [API keys](/deploy/api-keys) for scoping a key to a specific env.

## API reference

The same actions are available over the API. Every endpoint operates on the app passed in the `X-Agentmark-App-Id` header. See the [API reference](/api-reference/overview) under the Environments tag for full request and response schemas.

| Method   | Path                    | Description                                                             |
| -------- | ----------------------- | ----------------------------------------------------------------------- |
| `GET`    | `/v1/environments`      | List environments for the app (default env first)                       |
| `POST`   | `/v1/environments`      | Create a non-default environment                                        |
| `GET`    | `/v1/environments/{id}` | Get one env, including a cascade-preview for delete                     |
| `DELETE` | `/v1/environments/{id}` | Delete a non-default env (requires typed-name confirmation in the body) |

## Related reading

* [API keys](/deploy/api-keys): each environment has its own keys
* [Users and access control](/deploy/users-and-access-control): env permissions and roles
* [Regression gates](/deploy/regression-gates): fail a CI build when scores regress against a baseline

<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>