Skip to main content
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. 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. 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 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. 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 A newly-created env starts in the no-pin state, with no pinned version yet.
Creating an env doesn’t auto-mint an API key. The post-create dialog links straight to the 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.
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
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.

​
Permissions

These per-app permissions gate environment actions: See Users and access control for how permissions roll up into roles, and 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 under the Environments tag for full request and response schemas.

​
Related reading

​
Have questions?

Reach out any time: