An **environment** represents a deployment stage — such as Development, Staging, or Production — within a project. Each environment has its own credentials, redirect URIs, and configuration, so you can develop and test without affecting production users.

The resource hierarchy is **Organization > Tenant > Project > Environment**. When you create a project, a default environment is created automatically. You can add more environments and switch between them from the top navigation bar.

## Environment list

Navigate to **Settings > Environments** (`/dashboard/settings?tab=environments`) to see all environments in the current project. Environments are displayed in a table sorted by weight (ascending) with the following columns:

| Column | Details |
|--------|---------|
| **Name** | The environment name in bold text (e.g. "Development", "Staging", "Production"). |
| **Weight** | A numeric value inside an outlined badge. Lower values appear first. |
| **Live** | A badge reading **"Live"** (filled) or **"Dev"** (muted). |
| **ID** | The environment UUID in monospaced text. |
| **Actions** | An ellipsis menu with **"Edit"** and **"Delete"** options. |

When no environments exist, the table is replaced by the message _"No environments found. Create your first environment to get started."_

## Switch environments

Click the **project/environment picker** in the top navigation bar to open the switcher dialog. The dialog has two panels:

- **Left panel — Projects** — lists projects with **Recent**, **Starred**, and **All** tabs, plus a search field. The current project is indicated with a badge.
- **Right panel — Environments** — lists environments for the selected project with **Recent**, **Starred**, and **All** tabs, plus a search field.

Each environment entry in the switcher shows:
- **Name** (e.g. "dev", "prod")
- **Live badge** — a green badge on environments marked as live
- **Pin icon** (left side) — filled in primary color if the environment is pinned
- **Copy icon** — copies the environment ID to your clipboard
- **Pin/Unpin icon** — toggles whether the environment is pinned for quick access
- **Default/Star icon** — sets the environment as the project default (web projects only); acts as a secondary pin toggle for MCP projects

Pinned environments float to the top of the list, above a visual separator. Click an environment, then click **"Apply"** to switch. Click **"Cancel"** to close without changing.

> **Tip**
>
> Press **Shift + Alt + E** to cycle through environments in the current
> project without opening the switcher dialog.

## Pin an environment

Pinning marks frequently used environments for quick access. Click the **pin icon** next to an environment in the switcher dialog to pin or unpin it. A toast notification confirms the action.

- Pinned environments appear at the top of the environment list in the switcher, above a visual separator.
- The **"Starred"** tab in the environment column filters the list to show only pinned environments.
- Pinned environments are stored per-user on the backend (separate storage for web and MCP environments).

## Default environment

The default environment is a project-level setting available only for **web projects** (not MCP servers). It determines which environment is automatically selected when you switch to that project.

To set a default, click the **star icon** on a web project environment entry in the switcher dialog. The star turns yellow and filled. Only one environment per project can be the default — setting a new one replaces the previous.

### Auto-selection priority

When you select a project, the console auto-selects an environment in this order:

1. **Default environment** — if set, selected first.
2. **Pinned environment** — if no default, the first pinned environment (by weight).
3. **Live environment** — if no pinned, the first environment marked as live.
4. **Lowest weight** — as a final fallback, the environment with the lowest weight value.

## Live vs Dev environments

Each environment can be marked as **Live** or left as **Dev** (the default). This is a metadata label — it does not change how authentication, sessions, or API calls behave. Both live and dev environments are functionally identical.

The label helps your team visually distinguish production-facing environments from development or test ones:

- A green **"Live"** badge appears on environments marked as live, both in the environment table and the switcher dialog.
- A muted **"Dev"** badge appears on all other environments.
- When no default or pinned environment is set, the auto-selection logic prefers a **live** environment over a non-live one (see [Auto-selection priority](#auto-selection-priority) above).

To mark an environment as live, toggle **"Mark as Live Environment"** when creating or editing the environment.

> **Tip**
>
> Use the live flag to prevent accidental edits on production environments —
> the badge serves as a visual reminder that you are working in a live context.

## Create an environment

### In the Dashboard

1. Navigate to **Settings > Environments** (`/dashboard/settings?tab=environments`).
2. Click **"New Environment"** in the top-right corner.
3. Enter an **Environment Name** (e.g. "Development", "Staging", "Production").
4. Optionally set a **Weight (Order)** value — lower numbers appear first.
5. Optionally toggle **Mark as Live Environment** to flag this as a live/production environment.
6. Click **"Create Environment"**.

### Programmatically

Use the `createEnvironment` mutation to create an environment via the API:

```graphql
mutation CreateEnvironment($input: CreateEnvironmentInput!) {
  createEnvironment(input: $input) {
    id
    name
    createdAt
  }
}
```

```json
{
  "input": {
    "name": "staging"
  }
}
```

### Form fields

| Field | Required | Details |
|-------|----------|---------|
| **Environment Name** | Yes | Placeholder: _"e.g., Development, Staging, Production"_. |
| **Weight (Order)** | No | Defaults to `0`. Lower numbers appear first (e.g. Dev=0, Staging=1, Prod=2). |
| **Mark as Live Environment** | No | Toggle switch, defaults to off. Controls whether the environment is flagged as live. |

## Edit an environment

Select **"Edit"** from the actions dropdown on any environment row. The edit dialog shows the same three fields (Environment Name, Weight, Mark as Live Environment) pre-filled with the current values. Click **"Save Changes"** to apply.

## Delete an environment

From **Settings > Environments**, select **"Delete"** from the actions dropdown on the environment row. A confirmation dialog asks _"Are you sure you want to delete the environment "{name}"? This action cannot be undone."_ Click **"Delete Environment"** to confirm.

> **Caution**
>
> Deleting an environment is permanent. All credentials, redirect URIs, and
> configuration for that environment will be destroyed and cannot be recovered.
> You cannot delete the last remaining environment in a project.

## Related

| Read | To learn how to |
|------|-----------------|
| [Projects](/docs/console/projects) | Create and manage projects that contain environments |
| [Tenants](/docs/console/tenants) | Manage tenant workspaces that contain projects |
| [Sessions](/docs/console/sessions) | Configure JWT signing and token settings per environment |
| [Multi-tenancy](/docs/concepts/multi-tenancy) | Understand why environments isolate keys and users |