# Manage Environments and Deployment Pipelines

Environments and deployment pipelines are organization-level constructs that control *where* your agents run and *how* they are promoted from one stage to the next (for example `Development → Staging → Production`).

* An **environment** represents a runtime context (e.g., `dev`, `test`, `staging`, `production`) where agents are deployed and executed.
* A **deployment pipeline** defines an ordered promotion path across those environments.
* Each **project** is assigned one deployment pipeline, and agents in that project are **promoted** along its path.

Both environments and deployment pipelines live under the **Infrastructure** section of the organization-level navigation.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* Admin access to the WSO2 Agent Manager Console.
* A terminal with `kubectl` and `helm` configured against your cluster (environments are provisioned and removed by a script that installs/uninstalls an API Platform Gateway via Helm).
* At least one [AI Gateway registered](/agent-manager/docs/v1.0.0-alpha1/administration/register-ai-gateway/.md) and active.

***

## Managing Environments[​](#managing-environments "Direct link to Managing Environments")

### Navigate to Environments[​](#navigate-to-environments "Direct link to Navigate to Environments")

1. Log in to the WSO2 Agent Manager Console.

2. Go to the organization level by closing the projects section in the top navigation.

3. In the left sidebar, click **Environments** under the **INFRASTRUCTURE** section.

   > The Environments page lists every environment with its display name, associated gateway, and whether it is a production environment.

### Create an environment[​](#create-an-environment "Direct link to Create an environment")

Environments are provisioned by a script that creates the environment in Agent Manager and installs its API Platform Gateway via Helm. The Console builds the command for you.

1. Click **Create Environment**.

2. Fill in the environment details.

   | Field                      | Description                                                                                                                                                                                                                                                                                                                                  | Example                |
   | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
   | **Display Name**           | Human-readable name shown throughout the Console.                                                                                                                                                                                                                                                                                            | `Production`           |
   | **Isolation Tier**         | Container runtime isolation for agents deployed to this environment. The dropdown lists three sandboxing tiers of increasing strength — `Sandboxing T1 (runc)` (default), `Sandboxing T2 (gVisor)`, and `Sandboxing T3 (Kata Containers)`. Stronger tiers need a dedicated node set up first; see [Isolation tiers](#isolation-tiers) below. | `Sandboxing T1 (runc)` |
   | **Production environment** | Mark this environment as production. Production environments are typically the last stage of a pipeline.                                                                                                                                                                                                                                     | —                      |

3. Copy the generated command using the copy icon. Your access token is substituted into the command automatically when you copy.

4. Run the command from a terminal that has `kubectl` and `helm` configured against your cluster.

   The script creates the environment in Agent Manager and provisions an API Platform Gateway for that environment via Helm.

   > The script is idempotent — it is safe to re-run. Once it completes, the new environment appears in the list.

### Isolation tiers[​](#isolation-tiers "Direct link to Isolation tiers")

Every environment has an **isolation tier** that decides which container runtime its agents run under. The tier is chosen at environment creation time and cannot be changed afterwards.

The Console presents the tiers as three sandboxing levels of increasing strength, each marked by its own shield icon. The environment list shows the tier as a **Sandboxing T1**–**T3** shield chip, and on an agent's Deploy and Overview pages (and in a pipeline's promotion chain) a shield icon next to the environment name identifies its tier — hover over it to see the tier and runtime, e.g. *Sandboxing Tier 2 — gVisor*.

| Console label               | Tier value | Runtime                       | Isolation                              | Requirements                                                                                                                   |
| --------------------------- | ---------- | ----------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Sandboxing T1** (default) | `runc`     | Standard container runtime    | Sandboxed pod, shared host kernel      | None — works everywhere                                                                                                        |
| **Sandboxing T2**           | `gvisor`   | gVisor (`runsc`)              | Userspace kernel intercepts syscalls   | A dedicated x86\_64 node — see the [gVisor guide](/agent-manager/docs/v1.0.0-alpha1/administration/isolation-tiers/gvisor/.md) |
| **Sandboxing T3**           | `kata`     | Kata Containers (`kata-qemu`) | Per-agent VM with its own guest kernel | A dedicated node with KVM — see the [Kata guide](/agent-manager/docs/v1.0.0-alpha1/administration/isolation-tiers/kata/.md)    |

To create an environment with a stronger tier, set up the node first (per the guides above), then pick the tier from the **Isolation Tier** dropdown in the **Create Environment** drawer. The generated command automatically includes the matching `ISOLATION_TIER` variable — for `runc` (the default) no variable is added. Selecting gVisor or Kata also shows a warning with a link to the corresponding node setup guide.

If you script environment creation directly instead of using the Console, set the variable yourself:

```
ISOLATION_TIER=gvisor \
  ENV_NAME=... DISPLAY_NAME=... AGENT_MANAGER_TOKEN=... \
  bash add-environment.sh
```

Agents deployed or promoted to that environment automatically run under the tier's runtime — no agent-side changes are needed.

### Delete an environment[​](#delete-an-environment "Direct link to Delete an environment")

1. On the Environments page, open the **Delete** action for the environment you want to remove.

2. Copy the generated command and run it from a terminal configured against your cluster (again with `kubectl` and `helm` configured).

   The script uninstalls the environment's API Platform Gateway Helm release and then deletes the environment in Agent Manager.

   > **Warning:** Deleting an environment is permanent and cannot be undone. Any agent deployed to the environment will no longer be reachable, and the deployment will be permanently deleted.

note

An environment cannot be deleted while it is still referenced by a deployment pipeline. Remove it from any pipeline first.

***

## Managing Deployment Pipelines[​](#managing-deployment-pipelines "Direct link to Managing Deployment Pipelines")

A deployment pipeline defines the promotion path agents follow across environments.

### Navigate to Deployment Pipelines[​](#navigate-to-deployment-pipelines "Direct link to Navigate to Deployment Pipelines")

1. At the organization level, open the left sidebar.

2. Click **Deployment Pipelines** under the **INFRASTRUCTURE** section.

   > The page lists each pipeline with its promotion chain rendered.

### Create a deployment pipeline[​](#create-a-deployment-pipeline "Direct link to Create a deployment pipeline")

1. Click **Create Pipeline**.

2. Under **Pipeline Details**, enter:

   | Field            | Description                                      | Example                      |
   | ---------------- | ------------------------------------------------ | ---------------------------- |
   | **Display Name** | Human-readable name for the pipeline (required). | `Production Pipeline`        |
   | **Description**  | Optional description.                            | `Dev to Prod promotion path` |

3. In the pipeline chain editor, add environments in the order agents should be promoted through them. The chain must contain at least one environment and must form a single linear path.

4. Click **Create**.

### Delete a deployment pipeline[​](#delete-a-deployment-pipeline "Direct link to Delete a deployment pipeline")

1. On the Deployment Pipelines page, hover over the pipeline row and click the **Delete** icon.

2. Confirm in the dialog.

   > **Warning:** Deleting a pipeline cannot be undone. Reassign any project that uses the pipeline to a different one first.

note

A deployment pipeline cannot be deleted while it is still referenced by a project. Reassign any project that uses it to a different pipeline first (see [updating a project's deployment pipeline](#update-a-projects-deployment-pipeline)).

***

## Update a project's deployment pipeline[​](#update-a-projects-deployment-pipeline "Direct link to Update a project's deployment pipeline")

Every project is assigned a deployment pipeline, which determines the environments its agents can be promoted through.

1. At the organization level, open the **Projects** list.

2. Open the **Edit** action for the project you want to change.

3. In the **Edit Project** drawer, open the **Deployment Pipeline** dropdown. Each option shows the pipeline name and its promotion chain.

4. Select the pipeline you want and click **Update Project**.

   > A deployment pipeline is required for a project. Changing it changes the promotion path available to all agents in the project.

***

## Promote an agent[​](#promote-an-agent "Direct link to Promote an agent")

Promoting an agent deploys it from one environment to the next environment in the project's deployment pipeline.

1. Open the agent and go to its **Deploy** page. Each environment in the pipeline is shown as a card.

2. On the source environment's card, click **Promote**.

   > The **Promote** button appears only when the environment has a downstream target in the project's pipeline and the agent is currently **Active** in that environment.

3. In the **Promote** drawer:

   * **Target Environment** — if the source has more than one possible next environment, select the target.

   * **Configuration** — choose how the target is configured:

     <!-- -->

     * Enable **Use config from source environment** to inherit the source environment's environment variables and file mounts.
     * Leave it disabled to set environment-specific **Environment Variables** and **File Mounts** for the target environment.

4. Click **Promote**.

The same build is deployed to the target environment with the configuration you supplied. Repeat the process to advance the agent along the rest of the pipeline.