Skip to content

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.

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

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.

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

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.

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. frontend or api.
  • Build path - required here, since it’s what tells this service apart from its siblings (e.g. frontend vs backend).

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.

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.

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.

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.

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.

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.

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.