Skip to main content
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, where a command names the project and --env reaches one of its environments:

​
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.
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.

​
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. 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.
Use Remove on the row in the project’s Settings → Environments.
To stop the agent running as well, delete it with pipecat 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.
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.
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-<number>. 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.

​
What a project shares

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.