Creating Projects & Environments (Dashboard)
The Getting Started and
Environments & Services pages cover the canopy CLI.
This page walks the same territory from the web dashboard
(app.canopy.pm) instead, step by step, for anyone who’d rather click
through the UI than run commands.
Concepts, quickly
Section titled “Concepts, quickly”- A project groups environments together - usually one project per app. Projects belong to a team.
- An environment is the actual deployable unit: its own workload, build, domains, database, storage mounts, and variables, tracked against a specific git branch.
- If your repository is a monorepo (more than one deployable app in one repo - e.g. a frontend and a backend in separate folders), you can put them in one environment as separate app services. Each service has its own build and runtime settings, and may have its own domain and service-scoped variables, but services in an environment ship together in one release. Use separate environments when you need independent deployment lifecycles. See Adding a service for a monorepo below.
Finding your way around an environment
Section titled “Finding your way around an environment”An environment’s sidebar has up to eleven entries: Overview, Source, Deployments, Architecture, Logs,
Monitoring, Variables, Domains & Access, Previews, Backups and Settings. Source appears when
host.source is available; Previews appears when preview deployments are enabled. Several entries hold more than one
page, shown as a row of sections above the page: Deployments has Pipelines, Releases, Timeline and Definition;
Architecture has Blueprint (when available; Topology is shown when Blueprint is unavailable), Services, Databases and
caches and Repositories (when multi-repository is enabled); Monitoring has Incidents; Backups has Residency; Settings has
Webhooks. Previews lists the temporary copies made for pull requests, with their state and address, who can open each one, and
lets you approve or reject a fork’s preview and remove one. Domains & Access also sets who can open the environment
itself. Every page keeps the address it always had, so a bookmark still works. Where this guide says “the Pipelines tab” or “the Databases and caches tab”, it means that section.
A project has its own sections: Overview, Architecture (when Blueprint is available), Deployments, Versions, Policies, and Security (when Canopy Security findings are available). The project’s Overview lists each environment with what is live, its last deploy status and time, and a badge showing how many deploys are waiting for approval.
1. Start a project or add an environment
Section titled “1. Start a project or add an environment”To start a project, go to Projects and click New project
(/projects/create). This opens the deployment wizard. Enter the project
name and team there; Canopy creates the project together with its first
environment when you deploy. The dashboard does not first create an empty
project.
To add another environment, open an existing project’s Overview and choose Add environment. The wizard uses that project and skips the project name and team fields.
Deleting a project
Section titled “Deleting a project”Deleting a project permanently removes it and all of its environments. The API requires the project’s slug as confirmation, so nothing can delete one by accident:
DELETE /projects/{id}?confirm=<project slug>A request without confirm, or with anything other than the slug, answers 409 with error_code: confirmation_required and the name of the project; nothing is deleted. The dashboard asks you to type the slug
before the Delete project button turns on. canopy projects rm <slug> already takes the slug as its argument and
sends it as the confirmation (it refuses an id), and sdk.projects.delete(projectId, slug) takes it as the second
argument. This was added on 2026-10-07; a script that called the endpoint directly must now add confirm.
2. Create an environment
Section titled “2. Create an environment”From the project page, click Add environment
(/projects/[project]/environments/create).
If your team has any templates set up, you’ll first see a gallery step - pick Deploy your own repository to skip templates and go straight to the form below (or pick a template to deploy from a preset instead).
Source
- Repository - pick the repo from the connected-provider picker. If you have not connected a Git provider yet, the page first asks you to connect one (or to deploy a container image instead, which needs no Git account).
- Branch - a dropdown of the repository’s branches with the default one already chosen. A push to this branch triggers a deploy automatically.
Services - once a repository and branch are chosen, Canopy reads the repository and lists the services it
describes (a compose.yaml, else a Procfile, else its Dockerfiles). Nothing is created yet. For each service you see
its kind (web, worker or job) and how sure Canopy is, how it is built, its port, its language and framework, and
why it was proposed (for example “builds app/Dockerfile (compose.yaml, line 15)”). You can include or leave out each
service, rename it, change its kind and, for a service whose kind Canopy is unsure of, choose it. Values the file does
not carry, such as a password, are listed per service and must be entered before Deploy turns on. The databases and
caches, the links between services, public domains and outside hosts Canopy detected are part of the proposal and are
created with it. Topology of this proposal is open by default: a diagram of the services and how they connect
(a list on a narrow screen), which Hide topology folds away. If nothing is found, the repository cannot be read, or
you turn the step off, the environment is created as one service. A repository with a single service starts with the
step off.
More environments - add up to three more environments of the same repository on other branches. They start with the same services and no secret values or domain; set those per environment afterwards.
More repositories - attach other repositories to every new environment before its services (needs the multi-repository feature on your team). The services review still proposes services from the primary repository only.
Press Deploy. When creating a new project, Canopy creates the project, environments, their repositories, services, databases and links, and the first deploy through one setup operation. When adding an environment to an existing project, the operation uses that project instead of creating another one. The page lists setup steps as they finish. If a step fails, the page says which step and why and offers Try again, which continues from the step that failed without repeating what is done; Deploy as a single service and opening the environment are offered too. Nothing is built before the services are set up.
Advanced options (collapsed by default - a badge shows how many are set once you’ve touched any of them):
- Build path - for a monorepo, the subdirectory containing this
app’s Dockerfile (e.g.
apps/web). Leave blank if the repository only contains one app at its root. - Build steps - extra build commands, if needed.
- Custom domain - point your DNS at the IP shown on this step first; see Domains below for how TLS gets provisioned.
- Database - the databases Canopy detected are already in the proposal; add one here only if the repository does not describe it.
When the steps are done you are taken to the new environment; the first build and deploy run in the background and show on its Deployments page.
Adding a service for a monorepo
Section titled “Adding a service for a monorepo”Once an environment exists, open it and find the Services section, then click Add service. This reuses the same repository/branch as the root by default, so you only need to fill in:
- Service name - e.g.
frontendorapi. - Build path - required here, since it’s what tells this service
apart from its siblings (e.g.
frontendvsbackend).
Repeat for each app in the monorepo. Each service gets its own build and runtime settings; domains and variables can be scoped to a service. A deploy rolls the environment’s services out as one release, and removing a service changes the environment’s service set. Use a separate environment when a service needs an independent deploy history or lifecycle.
3. Environment variables
Section titled “3. Environment variables”Open an environment and go to its Variables tab.
Variables are split into two groups:
- System Variables - managed by Canopy itself (shown with a lock icon), not editable here.
- User Variables - yours to add, edit, and delete.
To add one: fill in Name and Value under “Add variable” and submit. Values are encrypted at rest and masked by default in the list - click the eye icon on a row to reveal one, or use the copy icon next to it to copy just that value to your clipboard.
To edit or delete one: use the pencil/trash icons on that variable’s row.
To copy variables from another environment (e.g. bringing staging’s config into production, or seeding a brand-new service from its root): click Copy from another environment above the tabs, pick the source environment from the dropdown, and click Copy variables. Every non-system variable from the source is added here - a variable that already exists under the same name is overwritten with the source’s value, so this is safe to run more than once. System variables are never copied.
A banner will show up automatically if two environments in the same project have drifted apart (one has a variable the other doesn’t) - that’s a hint, not an error, and the copy action above is the fastest way to reconcile it.
Note: a variable that’s read at build time (e.g. a Next.js app’s
NEXT_PUBLIC_* values) needs a fresh deploy to take effect - setting or
copying it doesn’t retroactively change an already-built image.
4. Storage mounts
Section titled “4. Storage mounts”Open an environment and go to its Databases and caches tab (this is also where database provisioning lives). Under Storage mounts, click Add mount and fill in:
- Host path - a path on the underlying host.
- Container path - where that path is mounted inside your app’s container.
Changes here take effect on the next deploy, not the currently running container - trigger one from the environment’s Pipelines tab (or just push a commit) after adding or removing a mount.
Domains
Section titled “Domains”Open an environment and go to its Domains tab to add a custom domain. Point your DNS at Canopy’s IP first (shown on the create-environment form); TLS is provisioned automatically after the first successful deploy once DNS has propagated. If a certificate doesn’t show up, a retry option is available on the same tab rather than waiting for another deploy.
Deploying
Section titled “Deploying”A push to an environment’s linked branch triggers a deploy automatically via webhook - no dashboard action needed. See Deploys & the Staged Pipeline for what happens during a build, and each environment’s Pipelines tab for build history and live logs.
Pipelines
Section titled “Pipelines”A project’s Pipelines section lists each environment’s canopy.pipeline.ts with links to view it, edit it and see
its runs. An environment without one offers Create a pipeline. The editor shows a pipeline as steps you can select
(image, command, CPUs, memory, timeout, GPU, attempts, when it runs) and as code, checks it in the same sandbox a real
build uses, and saves it to the repository as a commit or a pull request. See
Canopy Pipelines.
Team pages
Section titled “Team pages”The Teams area has the pages that belong to a whole team rather than one project:
- Machines - the Macs and Linux machines that run steps for the team, with their agent version and any update, checks, GPUs and pools; add one with the command shown there, diagnose it, or revoke it. See Native machines.
- Compute jobs - the jobs submitted to those machines, where each step ran and why, the output, a cancel button and the GPU budget. See Compute jobs.
- Pipeline secrets - the named values pipeline steps read; a value is write-only.
- Git access - the identities Canopy clones your repositories with. See Clone identities.