> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cogniagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

> Run the same agent with other values, its own files and rows, and its own ways in, such as Demo with sample data next to Production.

An environment is everything an agent runs with, except its items. **Production** holds your real values, rows, files and phone line. Another environment, such as **Demo**, can hold sample values, sample rows and a test number, while the workflows, conversation flows and coworkers stay the same.

An agent that never adds an environment stays in Production and shows nothing new.

## What an environment holds

| Part | What each environment has of its own |
| - | - |
| **Values** | A value for each [agent variable](https://docs.cogniagent.ai/features/agent-variables.md#environments), secrets and Connection variables included |
| **Files and rows** | Its own files in each File Store, and its own rows in each Database, that is **Separate in each environment** |
| **Ways in** | Its own channels, endpoints, trigger settings and schedules |

Everything else is one set for every environment: the workflows (their trigger steps included), conversation flows, coworkers and knowledge bases, the variables themselves (their names and types), each Database's tables, every store set to **The same in every environment**, and the agent's endpoint keys.

## Production and the ones you add

* **Production** is built in. Every agent has it, and it can't be renamed or deleted.
* **Every other environment is one you add and name**, such as "Demo", "Staging" or "QA". The names are yours to choose. An agent can have up to 20 besides Production.
* **One runs at a time.** The agent runs in one environment, and everything in it uses that one's values, files, rows and ways in. Once there is more than one, the agent's header shows **Environment: Demo**, the agent in the sidebar carries a tag when it is not in Production, and `{{agent.environment}}` reads the name.
* **Only the agent's owner or an admin** adds, renames, deletes and switches environments. Everyone else who can open the agent sees them.

## The Environments tab

Open the agent, then **Settings → Environments**. Production is listed first, and the one the agent runs in is marked **Current**. Each row says:

* how many variables in use have no value there, such as "2 variables in use have no value";
* **Contents**: the size of its own files and rows, such as "4.9 KB in 2 stores";
* **Ways in**: its own ways in that are switched on, such as "2 channels, 1 endpoint";
* a pill while its files or rows are **Copying**, **Failed**, **Not set up** or **Behind**, with a line that says why and **Retry**.

**Make current** switches the agent to that environment. **Rename…** and **Delete…** are in the row's menu.

## Add an environment

With only Production, the tab explains environments and offers **Add an environment**. Once there are more, the button sits at the top.

**1. Name it**

Letters, digits, spaces, `-` and `_`, up to 60 characters, and unique in the agent. Production is taken.

**2. Start from**

Where its values come from: **Copy Production**, **Copy** another environment, or **Start empty**. A copy takes the plain values. Secrets and the accounts of Connection variables start empty, unless you tick **Copy secrets and accounts too**: "Demo will use the same live accounts and keys as Production."

**3. Files and rows**

Each File Store and Database that is separate in each environment gets a choice: **Empty**, the default, or **A copy of** an environment, such as "A copy of Production (2 KB)". An empty Database has the tables with no rows. An environment whose files or rows are not ready yet can't be copied. A store that is the same in every environment is listed with no choice.

**4. Ways in**

**Its ways in**: **A copy of Production's**, a copy of another environment's, or **None**. One choice covers its channels, endpoints, trigger settings and schedules. It starts on a copy of the environment the values come from, or on **None** when they start empty. "A copy is separate and works only while the agent runs in Demo: changing it never changes the original." See [Ways in](#ways-in).

**5. Add it**

Click **Add**. The message names any secrets and accounts that start empty, such as "Its secrets and accounts start empty: Billing › api key." Set them in the new environment before the agent runs in it. A way in you may not use as it is gets copied switched off: a channel or trigger on an account you cannot use, an endpoint that runs as someone you cannot run it as, or a schedule of a coworker you cannot change. The message names each one and says why, such as "Lead intake was copied switched off: it runs as someone you cannot run it as. Someone who can may switch it on in Demo."

Copies count toward your workspace's storage. Under the stores, the dialog says how much the copies need: "The copies need 1.2 GB of the workspace's storage." Copies that would take the workspace above 80% of a storage limit are refused, and **Add** stays off: "Copying Leads needs 1.2 GB; the workspace would be over 80% of its 20 GB."

A large copy goes on after the environment is added: "Some files or rows are still being copied. The agent can switch to it once they are ready." The Environments tab and the store's page show how far it is. A copy that stops is picked up again by itself. After 6 tries, or a day, it is marked **Failed**, and **Retry** sets it up again.

## Switch the environment

Use **Make current** on the Environments tab, or the **Environment** menu in the agent's header. You can switch only while the agent is stopped. Otherwise both say "Stop the agent first." Stop the agent, switch, then start it again.

Before it switches, a dialog titled **Switch to Demo?** shows what changes, in four groups:

| Group | What it says |
| - | - |
| **Values** | How many variables the items use have no value in Demo: "Start is refused until they have one." |
| **Data** | What the agent will see in each separate store: "Leads: Demo's 120 rows", "Brochures: Demo's 14 files" |
| **Ways in** | The channels, endpoints, triggers and schedules that stop or start: "Stops answering on +1 555 0100 (Production's)", "The New lead trigger of Lead intake (Demo's)" |
| **Work that ends** | Each run, session, open conversation and workflow listening on its own that the switch ends, by name |

A group with more than six lines shows one summary line, with **Show all**. Click **Switch** to go ahead. When nothing would change, it switches without asking.

The switch is refused while a store's files or rows in Demo are not ready. The dialog is then titled **Demo is not ready yet**, says why, such as "Demo's files in Brochures are still being copied (40%).", and offers only **Close**. It is refused too while a Database's tables in Demo have not taken a change yet: "Leads: Demo's tables are not up to date." See [Database](https://docs.cogniagent.ai/features/databases.md#in-each-environment).

After the switch, the message says "The agent now uses Demo", and how many values are still empty there. **Start** asks for those first. See [Start needs values](https://docs.cogniagent.ai/features/agent-variables.md#start-needs-values).

### What a switch ends

No work crosses environments. While the agent is stopped, people can still run workflows, test conversation flows and give coworkers sessions, and a workflow can [listen on its own](https://docs.cogniagent.ai/applications/execution-modes.md). A switch ends that work: "Switching ends 2 runs, 1 task and 3 open conversations started while the agent was stopped."

* Workflows listening on their own stop listening.
* An endpoint call in progress stops when the run, session or conversation it started ends.
* A coworker's chat thread starts fresh: its next message starts a new session.

Start them again after the switch if you still need them. Anything the switch misses stops at its next step: "This started in Production, and its agent now runs in Demo. Start it again."

Once the agent has more than Production, its run history, conversations, coworker sessions, endpoint calls and each store's **Activity** show the environment each one ran in, and can be filtered by it.

## Files and rows

Each File Store and Database is one of two kinds:

* **Separate in each environment**: each environment has its own files or rows, and work in one never touches another's. A new store is separate.
* **The same in every environment**: one set of files or rows that every environment reads and changes.

A variable group always has a value per environment. A Database's tables are the same in every environment either way. See [File Stores](https://docs.cogniagent.ai/features/file-stores.md#in-each-environment) and [Database](https://docs.cogniagent.ai/features/databases.md#in-each-environment).

## Ways in

Each environment has its own ways in: its channels, endpoints, trigger settings and schedules, with their own account, settings, timing and reach. Only those of the environment the agent runs in answer, take calls, listen and fire. The others are off, and their rows say **Off in Demo**.

Adding an environment can copy another one's ways in, or start with none. **Copy to Demo**, in a row's menu, copies one later, to an environment that has no copy of it yet. A copy is separate: changing it never changes the original.

| Way in | What a copy keeps | Where each environment's are |
| - | - | - |
| A channel | Its address. Only the copy where the agent runs answers | **Settings → Channels** |
| An endpoint | Its address and its MCP tool name. A call reaches the copy where the agent runs | **Settings → External access** |
| A trigger step | The step itself, which is part of the shared workflow. Its settings are per environment: account, filters, time, token | **Settings → Triggers**. Production's are also the ones on the canvas |
| A schedule | Its times and what it does. A copy fires as its own owner, the person who copied it | The coworker's **Schedules** tab, and **Settings → Triggers** |

Each of these tabs shows one environment at a time: pick it under **Environment**. A trigger step with no settings in Demo does not listen there, and a call that finds no copy where the agent runs is refused, such as "Lead intake has no copy in Demo. Copy it to Demo on the Endpoints tab." See [Channels](https://docs.cogniagent.ai/features/ways-in.md#in-each-environment), [Endpoints](https://docs.cogniagent.ai/features/endpoints.md#in-each-environment), [Triggers](https://docs.cogniagent.ai/features/agents.md#in-each-environment) and [Schedules](https://docs.cogniagent.ai/cowork/autonomy/schedules.md#in-each-environment).

## Stores other agents share

A store another agent shares with yours always reaches that agent's Production: its values, rows and files, whatever environment either agent runs in. While your agent runs in another environment, it can read the store but not change it: "Demo can read Leads from Sales but not change it. Only Production can." So a demo never writes into another agent's real data. See [Use a store another agent shares](https://docs.cogniagent.ai/features/data-stores.md#use-a-store-another-agent-shares).

## Rename or delete

* **Rename** any environment but Production. Items that read `{{agent.environment}}` get the new name.
* **Delete** any environment but Production and the one the agent runs in: "Switch the agent to another environment first." Its values go with it, secrets included, and its own files and rows go to the Trash. Its channels, endpoints, trigger settings and schedules are deleted with it, and the confirm names them per kind, such as 'Its endpoint "Lead intake" is deleted with it, with its call log.' and 'Copies in other environments stay.'

## Sharing and moving

* **A shared copy has only Production.** In the **Share** window, **Share from** picks the environment whose values, channels, endpoints and trigger settings the copy gets, and whose rows and files where **Include contents** is on. They become the copy's Production. Schedules never travel. See [Share from an environment](https://docs.cogniagent.ai/features/sharing-agents.md#share-from-an-environment).
* **A store moved to another agent** takes its Production files or rows. Its own files and rows in the other environments go to the Trash, and in the new agent's other environments it starts empty. The move window says so first: "Demo's rows in Leads go to the Trash. Undo brings the store back, not those rows."
* **A variable group moved to another agent** takes its Production values. In the new agent's other environments its variables start empty.
* **A conversation flow or coworker moved to another agent** takes its Production channels, into that agent's Production. Its channels in other environments stay behind, off, with no one answering, and the move window names them. See [Moving and deleting](https://docs.cogniagent.ai/features/ways-in.md#moving-and-deleting).
* **An item moved to another agent** takes its Production endpoints, trigger settings and schedules, into that agent's Production. Their copies in other environments are deleted, and the move window names them first: "Other environments' copies of 1 endpoint and 1 schedule are deleted: only Production's move into Billing. Undo does not bring them back."

## Next steps

> [card] [Agent variables and secrets](https://docs.cogniagent.ai/features/agent-variables.md)
>
> Values per environment, Compare, and what Start asks for.

> [card] [File Stores](https://docs.cogniagent.ai/features/file-stores.md)
>
> Files per environment, copies and Retry.

> [card] [Database](https://docs.cogniagent.ai/features/databases.md)
>
> Rows per environment, and one set of tables for all.

> [card] [Channels](https://docs.cogniagent.ai/features/ways-in.md)
>
> Each environment's own channels, and copies.

> [card] [Endpoints](https://docs.cogniagent.ai/features/endpoints.md#in-each-environment)
>
> Each environment's own endpoints, on one address.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.