> ## Documentation Index > Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt > Use this file to discover all available pages before exploring further. # Projects and Environments > How a Pipecat Cloud project, its production environment, its named environments and its PR previews fit together, and what promotion does. A **project** is an agent together with its environments. Each environment is an agent of its own, with its own branch, secrets, scaling and sessions, so the project is where the settings they share live: the repository layout they build from, and whether pull requests get previews. The dashboard lists your projects under **Projects**. In the CLI they are [`pipecat cloud project`](https://docs.pipecat.ai/api-reference/cli/cloud/project), where a command names the project and `--env` reaches one of its environments: ```shell theme={null} pipecat cloud project status my-bot pipecat cloud project logs my-bot --env staging ``` ## Production The project is its own `production` environment. There is no separate agent behind production, so `production` is reserved and cannot be used as an environment name. That is also why promotion has somewhere to go: an environment is promoted onto the project, which is production. `pipecat cloud project env list` shows it as the first row, and `--env production` addresses it, which is the same as naming the project with no `--env`. The commands that act on an environment of the project, `env promote` and `env remove`, take one of the others. ## Environments An environment is an existing agent linked to a project under a name, such as `staging` or `dev`. Linking changes nothing about what the agent runs. It keeps its own repository link, secret sets, scaling and agent profile, and it goes on serving sessions exactly as before. Because each environment holds its own repository binding, each one deploys from its own branch. A project on `main` with a `staging` environment on `staging` gives you two agents from one repository, each shipping its own branch. > [tab] Dashboard > > Open the project's **Settings → Environments** and click **Add > environment**. You can create a new agent for it, with the region fixed to > the project's, or link an agent that already exists. > > The header's environment menu switches between a project's environments, so > logs, sessions and settings all follow the environment you are looking at. > [tab] CLI > > ```shell theme={null} > pipecat cloud project env add my-bot staging --agent my-bot-staging > ``` > > The agent has to exist first. Create it the way you create any agent, with > [`pipecat cloud deploy`](https://docs.pipecat.ai/api-reference/cli/cloud/deploy), then link it. > > ```shell theme={null} > pipecat cloud project env list my-bot > ``` ### Naming An environment name is two to 50 lowercase letters, digits and dashes, starting and ending with a letter or digit. Two names are reserved: `production`, which is the project itself, and anything starting with `pr-`, which belongs to [PR previews](https://docs.pipecat.ai/pipecat-cloud/guides/pr-previews.md). Agent names stay globally unique, so an environment's agent needs a name of its own. Naming it after the project and the environment, as in `my-bot-staging`, keeps the two readable together. ### Removing an environment Unlinking an environment leaves an ordinary agent, running what it was running. Only the link goes. > [tab] Dashboard > > Use **Remove** on the row in the project's **Settings → Environments**. > [tab] CLI > > ```shell theme={null} > pipecat cloud project env remove my-bot staging > ``` To stop the agent running as well, delete it with [`pipecat cloud project delete`](https://docs.pipecat.ai/api-reference/cli/cloud/project#delete). ## Promotion Promoting an environment deploys the code it is running onto the project: the build behind its active deployment, or the image it was deployed from. Promotion moves code only. The project keeps its own secrets, scaling and agent profile, so promoting `staging` to production ships the code you tested without carrying staging's configuration with it. Nothing is rebuilt. The project deploys the same build the environment already ran, which is why an environment shares its project's region. > [tab] Dashboard > > Use **Promote** on the row in the project's **Settings → Environments**. The > dialog names the build or image it will deploy, and warns when the > environment's own deployment is still rolling out or unhealthy. > [tab] CLI > > ```shell theme={null} > pipecat cloud project env promote my-bot staging > ``` > > It confirms before deploying. Pass `--force` in a script. If the project deploys automatically from a branch, the next push to that branch deploys over a promotion, so promote from an environment whose code is already merged. ## PR previews A project can give every pull request an environment of its own, built from the pull request's head and named `pr-`. Previews are a project setting: they are configured on the project and apply to the pull requests that target the branch it deploys from. See [PR previews](https://docs.pipecat.ai/pipecat-cloud/guides/pr-previews.md). ## What a project shares | Setting | Scope | | - | - | | [GitHub installation](https://docs.pipecat.ai/pipecat-cloud/guides/deploy-from-github.md) | The organization. Every project in it uses the same installation. | | [Watch paths](https://docs.pipecat.ai/pipecat-cloud/guides/deploy-from-github.md#watch-paths) | The project. Its environments and previews follow the same list. | | [PR previews](https://docs.pipecat.ai/pipecat-cloud/guides/pr-previews.md) | The project. An environment cannot have previews of its own. | | Repository, branch, Dockerfile path | Each agent. The project and each environment bind their own. | | [Secret sets](https://docs.pipecat.ai/pipecat-cloud/fundamentals/secrets.md) | Each agent, and sets can be shared between them. | | [Scaling](https://docs.pipecat.ai/pipecat-cloud/fundamentals/scaling.md) and agent profile | Each agent. | | [Region](https://docs.pipecat.ai/pipecat-cloud/guides/regions.md) | The project. Every environment is in the project's region. | The dashboard's organization-wide pages, including sessions, deployments, analytics, recordings and storage, filter by project, and a secret set's page lists the projects and environments using it. ## Things to know * **An environment is in the project's region.** Linking an agent from another region is refused. The shared region is what lets promotion reuse a build and lets both agents mount the same secret sets. * **Environments don't nest.** A project with environments cannot become an environment, and an environment cannot have environments of its own. * **A project with previews on cannot become an environment.** Turn its previews off first. * **A PR preview is managed by its pull request.** It cannot be renamed, moved to another project, or unlinked by hand. * **An environment follows its project's watch paths.** Setting watch paths on an environment is refused, with a pointer to the project. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.