Environments & Services
Environments
Section titled “Environments”An environment is one deployable unit: its own workload, build, domains,
database, storage mounts, and environment variables, tracked against a
specific git branch. Most projects start with a single environment (e.g.
main).
The CLI examples below use <environment_id>/<project_id> placeholders
(UUIDs) since that’s what the CLI accepts today. The underlying REST API
also accepts a project’s or environment’s slug anywhere it accepts an id
(see the API Reference) - CLI support
for slugs is planned but not shipped yet.
When an environment cannot be created
Section titled “When an environment cannot be created”An authorized team member with environment:create can request an environment, subject to billing status, plan
quotas, spend limits, deployment policy, valid configuration and runtime capacity. These placement failures are returned
before an environment is created:
error_code |
Meaning | What to do |
|---|---|---|
no_runtime_grove |
No Grove in the region can run new environments right now | Retry shortly or choose another region; if it persists, a runtime Grove has to be enrolled or brought back |
forest_unavailable |
The Forest substrate is switched off | Retry later; staff switch it back on |
These are not the only reasons a create request can be refused. For example, an expired trial, the plan’s environment limit, a team spend limit, a policy denial, invalid input or a region that does not exist can also prevent creation.
Both carry retryable: true and a suggested_action.
Several deployables in one environment
Section titled “Several deployables in one environment”A monorepo with, say, a Next.js frontend and a Python backend in separate folders is one environment with
several app services, built and shipped together as one release: see App services
below. Add one with canopy app-services create --name backend --env <environment_id> --source-path backend.
The earlier child-environment model has been removed. A parent_environment_id on POST /environments answers
410 with error_code: moved_to_app_service; add a service with canopy app-services create instead. Existing child
environments were made standalone; they keep their own
builds, domains and variables.
Deleting an environment that holds volumes or databases asks you to confirm and choose what happens to them first -
see Deleting an environment that holds data.
App services
Section titled “App services”Every environment is made of one or more app services. A new environment has a single service named
default; the build and runtime settings you set on the environment (build_path, start_command,
verification_path, resource limits and so on) are that service’s settings, and the environment API keeps
returning them under the same names. The full list is under app_services on the environment, and also at:
GET /environments/{id}/app-servicesGET /environments/{id}/app-services/{service_id}Adding a second service needs a Forest environment; the host.environment_services platform feature is generally
available and on for every team unless staff switch it off. A service has a kind:
| Kind | Runs as | Notes |
|---|---|---|
web |
long-running, serves a port | port and the health settings apply |
worker |
long-running, no port | replicas applies; runs one process named worker |
job |
run to completion, on demand or on a schedule | job_timeout_seconds and schedule apply; no replicas, no port; runs one process named job |
A worker or job runs exactly one process, named after its kind. When the repository’s .canopy.yml declares
processes, the worker takes the entry named like the service, else the entry named worker (job for a job); a
web entry is never used for it. The service’s own settings (start command, CPU, memory, replicas) override that entry,
and a canopy scale override overrides the service’s replicas. When several services build from the same folder, only
the first of them (the default service when it is one of them) runs the folder’s release: tasks and cron: entries.
POST /environments/{id}/app-services { "name": "worker", "kind": "worker", "source_path": "services/worker" }PATCH /environments/{id}/app-services/{service_id}DELETE /environments/{id}/app-services/{service_id}A service is built from the environment’s repository (source_kind: "repository", the default) or runs a
published image (source_kind: "image" with an image_ref, for example a database or a cache). A service builds
from the environment’s repository unless the team has the preview host.multi_repository feature, which lets it name
another attached repository (see Multi-repository environments); without the feature a request
that names one (a source object or a repository_id) is refused with 422 and
error_code: multi_repository_unsupported. Every service shows the repository it builds from as source
(repository, provider, branch; null for an image service). An image service has
no source_path, build_type, build_command or dockerfile_path. When every service of an environment runs an
image, canopy deploys create imports each image by digest into the platform registry (up to three at a time) and
rolls them out as one release, all-or-nothing, with the same rollback as any other release; the services take their
images from their own image_ref, so a deploy takes no image argument. Create one with
canopy app-services create --name cache --kind worker --image docker.io/library/redis:7.4 --env <id>.
Restarting a service and how its pods roll
Section titled “Restarting a service and how its pods roll”POST /environments/{id}/app-services/{service_id}/restart rolls every pod of one service from the image it already
runs, with the same configuration (environment:restart, the same tier as scaling). A job cannot be restarted. The
rollout follows the service’s rollout setting:
rollout |
Behaviour |
|---|---|
recreate |
Every pod stops before the new ones start. One instance never runs twice and no spare capacity is needed. The default for a worker. |
rolling |
The new pod starts and must be ready before the old one stops. The default for a web service; a process with a persistent volume is always recreated. |
grace_period_seconds (1 to 3600, default 30) is how long a process gets after SIGTERM before it is killed. A worker
has no port to probe, so give it commands instead: liveness_command runs inside the container every 30 seconds after
a 60 second start-up grace and restarts it after three failures in a row, and readiness_probe_command marks the pod
not ready while it fails. (readiness_command is a different, older setting that runs once per deploy.)
GET /environments/{id}/logs?previous=true returns the complete log of the newest container that was restarted, which is
where a crash is explained. The live log of a worker also includes pods that are running but not Ready.
Changing a service’s kind
Section titled “Changing a service’s kind”An environment can start as a worker: POST /environments takes kind: "worker" for its default service. A worker gets
no default hostname, no public check and no domain, and its deployment verification reads not_applicable instead of
unknown. public_check: true and port are refused on a worker or a job (public_check_requires_web,
port_requires_web); health_mode and health_path are ignored there.
canopy app-services update <service> --env <id> --kind worker (or PATCH with {"kind": "worker"}) moves a service
between web, worker and job. It takes effect on the next deploy, which recompiles the workload: a worker or job
gets no port, no health probes, no Service and no routes, even when .canopy.yml declares a web process with a port
and a readiness path. This is the way to convert a queue poller that was migrated as a web service and never became
ready. The name cannot change.
- Moving off
webclears the service’s port, turns its public check off and removes the default hostname Canopy gave it (moving back towebturns the public check on again). It is refused with 409kind_change_has_domainswhile a domain you added points at it (an environment’s default service also owns domains that name no service). Remove or move the domains first. - Moving to
jobclears the replica count and is refused with 409kind_change_has_volumeswhile volumes are attached. - Moving to
webleaves the port unset until you give one; the job timeout is cleared on leavingjob. - Sending a port, replicas or a job timeout together with a kind that cannot have it is a 422.
How a release rolls out
Section titled “How a release rolls out”By default a release puts every web and worker service to the Grove, then waits for them to be running (jobs are
sequential, or the Rollout setting under Edit) Canopy waits for each web or worker service to be running before it touches the next, in build order, so a service that fails stops the rollout before the services after it were changed; the ones already changed are put back, exactly as for any failed release. It is slower, and the same timeout applies to each service. The release becomes live when every web and worker service reports running/ready; jobs are not waited on. After a successful deploy, a separate public verification probes each eligible web service with its public check enabled and a configured domain. It records healthy/unhealthy independently and does not delay or fail the release. A worker or job has no public check and its verification is not_applicable`.
Deploying a template as one environment
Section titled “Deploying a template as one environment”canopy environments create --template <id> (and POST /projects/{id}/deploy-template) creates one environment
whose services are the template’s services, deployed as one release. It needs Forest placement for the team, and
host.environment_services when the template has more than one service. What a template service becomes:
| Template service | Becomes |
|---|---|
| runs an image | an image app service |
| built from the template’s repository | an app service built from its build_path (one repository per template; its build_steps are that service’s) |
| a database (postgres or redis) | a managed instance of the environment, bound (service_bindings) to every service that depends_on it, whose credentials arrive as environment variables |
Services are web services in dependency order; the first answers on the environment’s name, the others on
<environment>-<service>. ${services.<key>.host} in a variable names that host, or a managed database’s in-cluster
address; ${services.<key>.env.NAME} reads the template’s own value. Each service gets its variables and volumes,
service_overrides can replace a service’s image_ref, branch or migrate_command, and required_variables of a
single-service template are generated (random) or taken from --var. Services, instances and the first deployment
follow the response, so poll the environment’s deploy_status; one environment counts against the plan. A template
that cannot run this way (two repositories, a readiness command, a database other than postgres or redis, a pinned
database image) answers 422 template_not_deployable with the reason.
name cannot change after creation. kind can move between web, worker and job, but a web service that still
has domains cannot become a worker or job (kind_change_has_domains), and a service with volumes cannot become a job
(kind_change_has_volumes). The default service can be changed but not deleted. A service
that still has domains or volumes cannot be deleted. An environment holds at most 20 services. An
image-based environment is always a single service.
Failures carry a machine-readable error_code next to the usual problem fields, for example name_taken,
too_many_services, forest_only, port_requires_web, replicas_not_for_job, service_has_domains,
service_instance_name_conflict (a managed database’s name is already used by another environment of the project on the same
Grove; deploying a template with databases answers 409 before creating anything).
Database variable names
Section titled “Database variable names”A service bound to a managed database or cache (service_bindings) receives the credentials of its instance Secret.
By default the Secret’s own lowercase keys arrive under the binding’s env_prefix: MAIN_DB_uri, MAIN_DB_host,
MAIN_DB_password. That is names: "secret_keys", the default, and what a binding without names does.
A binding with names: "conventional" also receives the variables most frameworks read, built from the same Secret.
The values never pass through Canopy Host; they reach the container as references to the Secret.
| Instance | Variables (prefix DATABASE_ or REDIS_ unless env_prefix says otherwise) |
|---|---|
| postgres | DATABASE_URL, DATABASE_HOST, DATABASE_PORT, DATABASE_USER, DATABASE_PASSWORD, DATABASE_NAME |
| redis (Valkey) | REDIS_URL, REDIS_HOST, REDIS_PORT, REDIS_PASSWORD |
{ "service_bindings": [ { "instance_name": "main-db", "env_prefix": "DATABASE_", "names": "conventional" } ] }- The lowercase
envFromvariables stay as well, so switching a binding toconventionalremoves nothing. env_prefixis used as written,MAIN_DB_givesMAIN_DB_URL. Without one the prefix follows the instance kind.- The redis URL is
redis://:<password>@<host>:<port>, put together by Kubernetes from the three Secret keys; it has no database number and no TLS. - A
conventionalbinding of an external instance only gets the plain keys, its Secret layout is unknown. - When two bindings want the same variable the first in the list keeps it and the second gets no conventional
variables. A variable your own environment variables already define is left alone. Both are shown as the
ServiceBindingNamescondition (ConventionalNameConflict,ConventionalNameShadowed) on the workload status. - It needs a Grove running a controller that knows the field; an older controller ignores
names. - A Blueprint link sets it with the link option
names(canopy links add --names conventional).
Waiting for a database
Section titled “Waiting for a database”A binding with wait_for_ready: true is held back: a deploy of that service is refused (binding_instance_not_ready)
while the instance has no credentials yet or its operator reports it as anything but active (provisioning,
degraded, failed), instead of starting a pod without the variables. A release of several services is refused before
any of them rolls out, and so is a preview. The check is that Forest has reported the instance’s credential Secret and
that the operator’s own readiness says active (an external instance counts as ready); the Host does not dial the
database itself, it cannot reach an in-cluster address. A phase nobody has reported yet does not hold a deploy. A
binding without the flag keeps its old behaviour: the service starts and picks the variables up once they exist.
Blueprint links set the flag by default (link option waitForReady); service_bindings written through
app-services do not unless they say so.
Domains, variables and jobs per service
Section titled “Domains, variables and jobs per service”A domain points at one web service. On an environment with several services, name it when you add it
(canopy domains add app.example.com --env <id> --service dashboard, or app_service_id in the API), and move it
later with canopy domains move <domain_id> --service worker-ui. A worker or a job cannot receive a domain
(domain_target_not_web). Each service has its own default hostname.
A variable is shared by every service unless you scope it:
canopy variables set RUBICON_API_KEY <value> --env <id> --service assessment --secret. A service sees the shared
variables and its own, and its own value wins over a shared one of the same name. Each service’s secrets are
delivered only to that service.
A job service is defined by the release but never started by it. Run one with
canopy app-services run assessment --env <id> -- <command...> (the command defaults to the service’s start
command, or the image’s own command when the service has none); only one execution of a service runs at a time.
canopy app-services executions assessment --env <id> lists them with status, exit code and duration;
canopy app-services executions assessment <execution_id> --env <id> also prints what the job printed (the last
64 KiB, via GET .../executions/{execution_id}/output). The job runs with the service’s variables, so its output
can contain secrets and reading it needs permission to deploy. A job that printed nothing has an empty output
(200 with "output": ""); an execution whose log could not be read answers 404 with output_unavailable or
output_capture_failed, and one that has not reported yet with output_not_reported.
Running a job on a schedule
Section titled “Running a job on a schedule”Give a job a schedule and Canopy runs its start command on it, in UTC, with the service’s variables:
canopy app-services update nightly --env <id> --schedule "0 3 * * *" --max-attempts 3 --starting-deadline 900scheduleis a five-field cron expression (*/5 * * * *,0 3 * * 1). The job needs astart_command: it is the command every run executes.--schedule offremoves the schedule.- Runs never overlap. A tick that arrives while the previous run is still going is skipped, so give the job a
job_timeout_secondsif a stuck run must not hold the schedule. max_attempts(1 to 5, default 1) is how many times a scheduled run is tried; a failed run is retried with growing delays (10 seconds, 20 seconds, 40 seconds and so on). A run you start yourself is never retried.starting_deadline_seconds(10 to 86400, default 300) is how late a run may still start, for example after the Grove was down. A run that missed its deadline is skipped, not run late.- A schedule needs the update to be deployed, like every service setting. A preview of the environment does not run the
schedule. A native Grove does not run scheduled jobs: the deploy is refused with the
cronfeature named. canopy app-services executions nightly --env <id>lists the runs the schedule started next to the ones you started, each markedscheduled; the API (GET .../executions) gives each atriggerofscheduleormanual. Canopy keeps each scheduled run for 30 days from the moment the Grove first reports it, and a scheduled run has no stored output. Look atcanopy environments logs --env <id> --service nightlywhile it runs.- A job and a
cron:entry of the same name in.canopy.ymlcannot both run: the.canopy.ymlentry wins and the deploy says so.
canopy scale --env <id> --process queue=2 --service worker and canopy environments logs --env <id> --service worker (API: app_service_id in the scale body or the logs query) act on one service; without it they act on
the default service. The log stream also takes app_service_id together with job to tail a run of that service.
An exec session (GET /environments/{id}/exec, a WebSocket upgrade; canopy exec) also takes app_service_id as a
query parameter to open the shell in a specific service’s workload. Without it the session opens in the default service.
The upgrade is refused with a JSON problem body when the id is not a live service of the environment (404,
app_service_not_found), when the service is a job (409, service_not_exec_capable: a job runs on demand and has no
running process, so run it with canopy app-services run), or when the service has no workload yet (409,
service_has_no_workload: deploy it first). The audit record of the session names the service.
GET /environments/{id}/state reports every service under app_services (the top-level fields are still the
default service’s), plus the live release and, when one is in flight or failed, the latest_release.
Setting an environment up from its repository
Section titled “Setting an environment up from its repository”POST /projects/{id}/environment-proposals (or canopy app-services propose --project <slug> --repository <owner/name> --branch <branch>; --team <team_id> in place of --project asks POST /teams/{id}/environment-proposals
before any project exists) reads a repository once and proposes its services: from a root compose.yaml,
compose.yml, docker-compose.yaml or docker-compose.yml when there is one; else from a root Procfile (each
process is a service built from the repository root, web answers requests, every other process is a worker, and a
release process becomes the web service’s migrate command); otherwise from its Dockerfiles and buildpack markers (at
most 10 services). Nothing is created. Each service carries its inferred kind and the evidence for
it, its build, port, variables and volumes, and warnings; a warning marked blocking has to be resolved first. A secret’s
value in the file is never read back: you enter it when you apply.
POST /environments/{id}/app-services/apply (or canopy app-services apply --env <id> --file <proposal.json> [--confirm-kinds] [--set service.NAME=value]) configures an environment that still has only its default service from
the reviewed proposal, all or nothing. The Services tab of the environment does the same in the app.
The environment creation wizard does it before anything is built. It asks POST /teams/{team_id}/environment-proposals,
the same proposal as the project route for a team that has no project yet (it needs host.environment_services for the
team and the environment:create action; a team where staff switched the feature off answers 403 feature_disabled
and the wizard leaves the step out). With host.blueprint it also asks POST /teams/{team_id}/blueprint/proposal for the evidence:
language and framework, the databases a service uses, the file and line behind each fact, and the suggestions that are
never applied. On Deploy the wizard sends POST /environments with defer_first_build: true, then the apply request
with the reviewed, edited services (renamed, left out, kind chosen, values entered), then POST /environments/{id}/builds. A failure of the apply request leaves the environment with only its default service and no
build; the wizard shows the reason and lets the person try again, deploy it as one service, or open it.
defer_first_build is a boolean on POST /environments: the environment is created, and its custom domain attached,
without the first build that creation otherwise starts. The caller starts it with POST /environments/{id}/builds. It
cannot be combined with build_only, image or template_id (400). The CLI has canopy environments create <branch> --project <slug> --repository <owner/repo> --defer-first-build, then canopy app-services apply, then canopy deploys create --env <id>; the SDK has environments.create(projectId, { deferFirstBuild: true }) and the MCP tool
host_create_environment takes defer_first_build.
Language settings per service
Section titled “Language settings per service”Language build settings belong to a service, so a .NET service and a Node service in one environment can each have
their own. GET/PATCH /environments/{id}/app-services/{service_id}/language-settings (and .../analysis) read,
change and analyze one service; the environment’s own language-settings routes act on its first service. A service
you add starts on the same profile as the first one. A build records one snapshot per service it builds.
Every new environment starts on the v1 profile, so a TypeScript service is transpiled while its image is built and javascript.transpile reads true until you turn it off; there is nothing to opt in to. An environment created earlier keeps its previous behaviour until you turn the settings on for it with PATCH .../language-settings. Compiling to a single binary (javascript.compile_to_binary) stays off until you enable it for an environment, and needs transpilation. A TypeScript service that is deployed through a Dockerfile needs the CANOPY_LANG_JS_TRANSPILE build argument to take part; the analysis says when it is missing.
A pull request preview of an environment with several services is one isolated copy of it: every web and worker service
gets its own workload from an image built for that pull request, a Postgres or Redis instance a service is bound to gets
an empty one of its own, and the preview is ready once every service is running. Jobs are not started in a preview, and
a preview runs at most 6 services (preview_too_many_services; the webhook records skipped_preview_too_many_services).
Each web service answers on its own hostname (GET .../previews/{id} lists them under services, and
canopy previews show prints them). A variable that names a sibling by its in-cluster name (http://api:8080,
redis://cache:6379) is rewritten to the preview’s own sibling, so a preview never talks to the source environment’s
services; a hostname built any other way is not rewritten. A preview receives only the variables marked preview_safe (canopy variables set --preview-safe); every other variable of the source environment stays out of it. A pull request event starts a preview only when the repository’s webhook secret verifies, and a preview’s public address is <preview id>.<the Grove's wildcard domain>; on a Grove without a wildcard domain it has none. In an environment with several repositories the preview builds only the services of the pull request’s repository and runs the active release’s images for the rest.
Environments from a native bundle
Section titled “Environments from a native bundle”A third source: an uploaded native bundle on one of your own machines. canopy environments create --native-bundle <artifact_id> --grove <grove_id> creates the environment and deploys the bundle; see Native Groves for the manifest, the limits and the refusals. The environment page shows the bundle (name, platform, digest) in place of a repository.
Environments from an image
Section titled “Environments from an image”An environment can run an existing container image instead of a repository:
canopy environments create budget --project budget --image docker.io/actualbudget/actual-server:25.9.0canopy deploys create --env <environment_id> --image docker.io/actualbudget/actual-server:25.9.1The image is imported into the platform registry by digest, so a deploy always runs exactly the bytes that were
imported and a rollback needs no network access to the source registry. Creating the environment starts its first
deploy. --image cannot be combined with --template, and needs Forest placement.
canopy deploys create without --image redeploys the current reference; a rollback returns to an earlier
import together with the configuration it ran with.
Deploying an image on every push
Section titled “Deploying an image on every push”Add --repository and the positional becomes the branch whose pushes redeploy the image:
canopy environments create main --project budget --name budget \ --image docker.io/actualbudget/actual-server:25.9.0 --repository giovanni/budgetThe repository holds the environment’s .canopy.yml and nothing to build. Each push to that branch reads the file
at the pushed commit, applies it (volumes, variables, health) and records it as the environment’s configuration,
then deploys. An image: line in the file moves the environment to that image, so bumping the version is a commit.
A push whose file is invalid deploys nothing and shows as “configuration rejected” in the environment’s webhook
deliveries. A repository without the file redeploys the current image and configuration. Pushes follow the same
path filter (build_path) and deploy_trigger setting as any other environment.
An image that runs as root is refused with an explanation: set run_as_user in the environment’s configuration to
a numeric user the image supports.
A private image is pulled with the credentials your team stored for its registry. Store them from a file (never on
the command line): a line username:password, or a JSON object with username and password:
canopy registries add --team <team_id> --host ghcr.io --credential-file ./ghcr-credentialThey are used only by Host while it resolves and copies the image; they are not handed to a Grove and never shown
back. An image that needs credentials and has none fails with registry_auth_required and this command as the fix.
Every image is also queued for a vulnerability scan, and the summary appears on the health card once one has run.
Scans run from a build host, so on a Grove with none the scan job fails and no summary appears yet.
Check before you deploy
Section titled “Check before you deploy”canopy check --env <environment_id>Looks at everything that can be known without deploying and changes nothing: the image resolves and runs as a
non-root user, it serves the port the configuration declares, a path the image stores data in has a volume, a
process that mounts a volume is not scaled past one replica, required variables are set, a domain exists, and the
health mode suits the app. Each check is ok, warn, FAIL or skip, with a fix where one applies; the command
exits non-zero when any check fails.
Application configuration
Section titled “Application configuration”The configuration an environment deploys with (ports, health, processes, volumes, run_as_user) is a .canopy.yml
document. For a repository environment each build records the file at its commit; an environment with no
repository is configured directly:
canopy config apply -f canopy.yml --env <environment_id>canopy config get --env <environment_id>canopy config revisions --env <environment_id>Every change is an immutable revision (an identical document reuses its revision), validated exactly like a
repository file and redeployed unless --no-apply is given. A build or deploy always runs the revision that was
current when it started, so a later edit never changes a deploy that is already running. Do not put secrets in it:
reference environment variable names only.
The document can declare what the app needs, and applying it creates the parts that do not exist yet:
version: 1image: docker.io/actualbudget/actual-server:25.9.0health: { mode: tcp }volumes: data: { mount: /data, size: 10 }env: required: [ACTUAL_PASSWORD] defaults: { ACTUAL_PORT: "5006" }processes: web: { command: "node app.js --port 5006", expose: true, port: 5006 } worker: { command: ["node", "worker.js"] }cron: - { name: nightly, schedule: "0 3 * * *", command: "node cleanup.js" }command is a string (split like a shell, quotes respected) or an argument list; args are appended after the
image’s entrypoint. A declared volume is created if missing and never resized by a later document (a different
size is refused with the reason); env.defaults are set only when the variable does not exist yet.
processes.<name>.expose: true routes the environment’s domains to that process instead of web. A conflict
between the document and what already exists is refused with 409 rather than half-applied.
Running on a specific Mac
Section titled “Running on a specific Mac”runtime.native pins the whole environment to one native machine instead of a Kubernetes Grove. Both fields are
required:
version: 1runtime: native: { platform: darwin/arm64, grove: gio-macbook }processes: web: { args: ["--verbose"] }The environment deploys the native bundle its build produced, and its processes and their entrypoints come from the
bundle’s manifest, so a native process takes args, replicas (exactly 1), expose, probes, cpu and memory.
A deploy is refused with the reason when platform is not the bundle’s platform, when grove is not the Grove the
environment runs on, or when the document declares something a native machine cannot run: a process command
or fixed port, volumes, cron, release tasks, an egress allowlist, image, or managed service bindings.
Scheduled commands show their next run and last outcome:
canopy jobs list --env <environment_id> # cron entriescanopy jobs list --env <environment_id> --kind run # recorded one-off runsBuild-only environments
Section titled “Build-only environments”A build-only environment builds and stops. Each build runs your pipeline and image build on the build Grove and registers the artifact in the registry, then finishes successful with a skipped Deploy skipped - build-only environment job. It is never placed on a Grove and has no domain or health check, so use it for something you build but run elsewhere, such as a controller image pinned by digest.
canopy environments create main --project <slug> --repository <owner/repo> --build-onlycanopy environments update <environment_id> --build-only truebuild_only is also a boolean on POST /environments and PUT /environments/{environment_id}, and canopy environments show prints it. Creating one starts no build: the first comes from a push to the branch or canopy deploys create. Creation refuses --host, --image, --template and a domain, and turning the setting on is refused with 409 while the environment is placed on a Grove. Turning it off makes the environment deployable again, but it still needs a placement before it can deploy.
Package build environments
Section titled “Package build environments”A package build environment builds, tests and publishes a package to the Canopy registry, and deploys nothing. It is a build-only environment that also builds no image: the pipeline in your repository’s canopy.pipeline.ts defines every step, and a build finishes successful with a skipped Deploy skipped - build-only environment job. It has no Grove, domain or health check.
canopy environments create main --project <slug> --repository <owner/repo> --build-path library --packagecanopy environments update <environment_id> --package truewatch_paths on an environment lists the paths besides build_path that rebuild it, as declared by watch in its canopy.pipeline.ts (see Canopy Pipelines). It is read only: Host writes it each time a build generates the pipeline, it is empty when the pipeline declares none, and canopy environments show prints it when it is not.
package_build is a boolean on POST /environments and PUT /environments/{environment_id}, and canopy environments show prints it when it is set. It implies build_only, so creating one starts no build: the first comes from a push to the branch that changes the build path, or canopy deploys create. Creation refuses build_only: false, a domain, an image and a template (400). Turning it on is refused with 409 while the environment is placed on a Grove, and build_only: false is refused with 409 while it is a package build. A package build with no canopy.pipeline.ts fails at the pipeline stage with a user_config failure.
A build’s kind (in GET /environments/{environment_id}/builds/{build_id}) is package for a package build environment, build_only for a build-only one and deploy otherwise. The steps that publish a package and the release record are separate platform work and are not part of this section yet.
Set up a project in one operation
Section titled “Set up a project in one operation”POST /teams/{team_id}/setups creates a project (or adds environments to one you name with project.project_id) and each
environment’s services, domain and first deploy as one server-side operation. It answers 202 at once; a worker does the
work and the operation survives a restart. GET /teams/{team_id}/setups/{setup_id} shows the steps (each pending,
running, done or failed, with error.code and error.message when it failed) and created, the ids made so far.
{ "project": { "name": "Shop" }, "environments": [ { "name": "production", "repository": "acme/shop", "branch": "main", "services": [ { "name": "web" }, { "name": "api" } ], "domain": "shop.example.com" }, { "name": "staging", "repository": "acme/shop", "branch": "develop", "deploy": false } ]}A failed step stops the setup (status: failed). Fix the cause and POST .../retry: steps that are done are not run
again. POST .../abandon removes what the setup created (its environments, and the project when the setup made it).
Send an Idempotency-Key header so a retried request creates one setup. A service variable with is_secret: true is
never stored in the request. Send its value in the environment’s secrets ([{ service, name, value }]) and it is sealed
apart from the request, written as a secret variable in its own set_variables step once the services exist, and removed
from the setup; the answer never contains it. A secret you do not send is listed in variables_needed to set afterwards.
repositories ([{ repository, branch? }], at most 9, needs repository and host.multi_repository) attaches secondary
repositories in an attach_repositories step before the services; an already attached repository is skipped, so a retry is safe.
Each repository is attached with the provider that owns it, found from the linked git accounts, so a GitLab repository can sit beside a GitHub primary. A service that sets repository to one of the environment’s repositories (owner/name) is built from it; a name that is not attached stops the set up services step with repository_not_attached.
blueprint_patch (a list of Blueprint operations, as POST .../blueprint/plan takes) is planned and applied after the
services, which is how the databases and links of a reviewed proposal are created; build_steps is the list of commands
run before the build. Images work as image instead of repository; templates are not part of a setup yet. For an existing project, an
environment can take from_revision (a Blueprint revision number) instead of services: the revision, with its
overlay for the new environment, is planned and applied after the environment is created, so a staging environment
comes from the project’s architecture.
Config files in the repository
Section titled “Config files in the repository”A service’s .canopy.yml and canopy.pipeline.ts live in its repository, in the service’s folder (the repository root
for a service without one). GET /environments/{id}/config-files?kind=canopy_yml|pipeline[&service_id=] finds the file
on the environment’s branch and says where it is (resolution: build_path, root or missing, with the path a
missing file would be created at), its sha, and whether the connection may write it:
{ "path": "apps/api/canopy.pipeline.ts", "resolution": "build_path", "exists": true, "sha": "...", "write": { "can_write": true, "reason": null, "protected_branch": false }, "pull_request": true }can_write is null when the Git provider cannot say; it is then the write that decides. /config-files/content adds
the file’s content. PUT /config-files with { kind, content, base_sha, message?, mode?, branch? } needs
environment:deploy and saves the file: mode: "commit" (the default) commits to the environment’s branch,
mode: "pull_request" answers 202 with an action and an operation: the worker, with your own provider credential,
writes the file to a new branch (branch, or a generated canopy/... name) in one commit and opens a pull request into
the branch, recorded as a pull request of origin configuration. GET /config-files/actions/{action_id}
shows how it ended: the pull request and the file’s new sha, or config_file_conflict (the file changed since
base_sha), no_change, or the provider’s refusal; a repository Canopy has not identified yet answers 409 source_repository_pending. base_sha is the sha you read; a stale one answers 409 config_file_conflict and nothing is written. A write the
provider refuses (a protected branch, a rule, a missing permission) answers 422 git_write_refused with the provider’s
words, and a provider that cannot open a pull request answers 422 pull_request_unsupported; Canopy does not retry
another way. A .canopy.yml that does not parse is refused with 422 invalid_canopy_yml. Every write is audited as
repository_file.written (or repository_file.pull_request_requested for a pull request). The SDK has configFiles.get|getContent|save|getWriteAction; canopy config-files show --env <id> reads
the same.
GET /repositories/branches?repository=owner/name lists a repository’s branches (up to 300, with protected and
default) for a branch picker; SDK repositories.branches().
Build settings
Section titled “Build settings”Anyone who can update an environment sets these. canopy environments show prints them.
incremental_execution(onby default): a pipeline node may reuse the result of an identical earlier execution.offruns every node; a single run can opt out with--no-reuse.build_groups(onby default): consecutive pipeline steps that could share one pod run in one pod when the target Grove supports it and every step of the group is an exec step; any other step runs in its own pod.offruns every step in its own pod. A group pod that reports corruption sets the environment tooff.source_scope: the directory of the primary repository that Source shows for this environment, and the only one it can browse, compare or read history for. It starts as the directory the services build from. Set it with--source-scope <dir>, show the whole repository with--source-scope all, or follow the services’ build directory again with--source-scope none. The Source folder field on the environment’s Settings page does the same.
canopy environments update <environment_id> --build-groups offcanopy environments update <environment_id> --source-scope host/apiA newer push-triggered build always cancels the older push-triggered builds of an image environment that have not started deploying. A pipeline step receives the files changed since the last comparable successful run (.canopy/changes.json) when it declares changes: true.
Health checks
Section titled “Health checks”An app that declares no probes is health-checked according to its health mode:
| Mode | Meaning |
|---|---|
auto (image environments) / tcp |
The port must accept connections; any HTTP answer below 500 counts as serving. An image with no health endpoint deploys. |
http |
The verification path (/ by default) must answer 2xx or 3xx. |
legacy_root_2xx (repository environments) |
Same as http, kept as the default so existing apps behave as before. |
canopy environments update <environment_id> --health-mode tcpA probe declared in .canopy.yml always wins over the mode.
Persistent volumes
Section titled “Persistent volumes”An environment running on Forest keeps data across deploys and restarts in a volume: named storage mounted at a path inside one of its processes.
canopy volumes create data --mount /data --size-gb 10 --env <environment_id>canopy volumes list --env <environment_id>Creating a volume restarts the app once with the volume mounted (--no-apply records it for the next deploy).
Sizes are 10 to 10240 GB. A volume cannot be resized after creation: back up and restore into a larger one.
Removing a volume never deletes its data:
canopy volumes detach <volume> --env <id>stops mounting it and keeps the data for the volume’s retention period (7 days unless--retention-dayswas set at creation).canopy volumes attach <volume> --env <id>mounts a detached volume again while it is still kept.canopy volumes purge <volume> --env <id> --confirm <volume name>permanently deletes a detached volume. This cannot be undone, and it is refused for a volume that is still mounted.
Destroying an environment keeps its volumes for their retention period too (see below), and a kept volume can be mounted by another environment of the same project:
canopy volumes retained --env <environment_id>canopy volumes adopt <volume_id> --mount /data --env <environment_id>The volume keeps its data and its size; --name and --process choose what it is called and which process mounts
it. Only volumes of the same project on the same Grove are offered, and only until their retention window ends.
A volume is exclusive to one replica of one process: asking for more than one replica of a process that mounts a volume is refused, because two copies of the app cannot safely write the same files.
A pod that mounts a volume gets the volume’s group ownership set, so an app running as a non-root user can write to it on any storage class. Where a Grove reports that volumes live on each node’s own disk, a volume larger than the largest node is refused up front, and one that would leave the disks more than 80% requested is created with a warning.
canopy run can work on the same data:
canopy run --env <environment_id> --with-volumes -- ls -la /dataThe command runs in the app’s image with the volumes of the process mounted, beside the process’s running pods (a volume can only be used from the node it lives on). It is refused with a reason when the process has no volumes, a volume is not attached yet, or the process’s volumes are on different nodes.
Backing up and restoring volumes
Section titled “Backing up and restoring volumes”Backups include volumes; a nightly sweep covers every environment that has a live volume. Each volume’s backup is either stopped (the default: the processes that mount it are scaled to zero while it is archived, then restored, so the copy is consistent) or online (archived while the app runs, and labelled fuzzy):
canopy environments update <environment_id> --backup-consistency onlinecanopy backups create --env <environment_id>canopy backups restore --backup <backup_id> --components volumes,variables --confirm <slug> --env <environment_id>Stopped backups are a deliberate, brief outage. If a run is interrupted the processes are started again automatically within two hours.
To have a backup taken automatically before a deploy that changes the image:
canopy environments update <environment_id> --predeploy-backup trueIt is best effort: a failed backup never blocks the deploy, but is recorded as an event.
A restore first takes a snapshot of the current state, stops the app, verifies the archive’s checksum before touching the volume, extracts into a staging directory and swaps it in, keeps the previous contents aside until the next restore, recreates a volume that no longer exists, starts the app again and waits for it to become healthy. Components that do not apply to the environment (for example a database on a Forest environment) are skipped rather than failing the restore.
Deleting an environment that holds data
Section titled “Deleting an environment that holds data”An environment that holds volumes or databases is not deleted until you confirm and choose what happens to them:
canopy environments rm <environment_id> --plancanopy environments rm <environment_id> --confirm <slug> --volumes retain --databases delete--confirmmust be the environment’s slug.--volumes retain(the default) keeps each volume’s data for its retention period, visible under the project and available to adopt;deleteschedules it for deletion.--databases retain|deletehas no default. A Forest database cannot outlive its environment yet, sodeleteis the only choice for one.
Without them the request is refused and the response lists what would be affected. An environment with no volumes or databases needs none of this.
Importing a Docker Compose file
Section titled “Importing a Docker Compose file”canopy compose import docker-compose.yml --project my-app # print the plancanopy compose import docker-compose.yml --project my-app --apply # create the environmentsEach service that uses an image becomes an image environment named after the service, so services reach each other
by name as they do in Compose. The port it publishes or exposes is routed, named volumes become volumes (a volume
means one replica), and environment variables become configuration defaults, except names that look like secrets
(PASSWORD, TOKEN, KEY, DSN, …), which are set as secret variables and never printed or written to
configuration. Services are created in depends_on order.
Anything with no equivalent is listed rather than dropped silently: build (only images are imported), bind mounts
(host paths do not exist on Forest: use a named volume and copy the data in), networks, healthcheck (the port is
checked instead), entrypoint, env_file and the like. With --apply each service is deployed once when created and
redeployed after its volumes, variables and configuration are recorded, so its first deploy may fail if it needs a
secret; the final one has everything.
Seeing how an app is doing
Section titled “Seeing how an app is doing”canopy state --env <environment_id>One page instead of five commands: the rollout phase, the image and its vulnerability summary, each process’s
ready count and restarts (with why the last one exited, for example OOMKilled), volumes and the node each is on,
routes and certificate state, the last successful backup, failing scheduled commands, and a list of everything that
needs attention. The dashboard shows the same on the environment’s Resources tab, with a button to run the
deployability check.
Why a deploy is slow or stuck
Section titled “Why a deploy is slow or stuck”canopy pods --env <environment_id>Lists every process’s pods: the state, how long it has been in that state, the node, restarts, whether the pod is on the current or the previous revision, and Kubernetes’ own words for why any pod is not ready.
web: 1/1 ready POD STATE FOR NODE RESTARTS REVISION web-new-aaaaa Unschedulable 20m - 0 current Unschedulable: 0/3 nodes are available: 2 Insufficient cpu. web-old-bbbbb Ready 2h 5m worker-3 0 previousA new pod that cannot start does not take your app down: the previous pod keeps serving until the new one is ready.
canopy state reports it under problems once it has waited two minutes (an image that cannot be pulled or a pod
that keeps crashing is reported at once), and the build page shows the same reason on the “Provisioning pod” and
“Waiting for pod readiness” steps. The common causes are no free CPU or memory on the Grove, an image that cannot be
pulled, a volume that cannot be attached, and a readiness probe that never passes.
Watching Forest work on a build
Section titled “Watching Forest work on a build”Under the Forest steps on a build page there is an Activity log: timestamped lines of what Forest and its Groves
are doing for that build, while it happens. It shows a build job handed to a Grove, a scheduler’s reason for not
placing it, a workload moving between phases, how many replicas are ready, each pod changing state with the reason
Kubernetes gives (ImagePullBackOff, CrashLoopBackOff, Insufficient cpu), and the Kubernetes events of those pods
(Pulling, Pulled, Started, back-off warnings). GET /environments/{id}/builds/{build_id}/forest-activity?after=<id>
returns the same lines, oldest first; pass the last next_after to read only what is new.
The log shows what the Grove reports to Canopy, which is not raw Kubernetes output and not your application’s own
log lines (canopy environments logs shows those). Only changes are written, so a settled app adds nothing,
and a build keeps at most 1000 lines. Builds that ran before the log existed have none.
The environment’s services, databases and external hosts are also available as a graph: see Blueprint.
Autoscaling
Section titled “Autoscaling”canopy autoscale list --env <environment_id>canopy autoscale set --env <environment_id> --process web --min 1 --max 6 --cpu 60 [--service api]canopy autoscale rm --env <environment_id> --process web [--service api]list shows every process of the environment with its replicas, the CPU its Grove measures (as a share of the
process’s CPU limit, averaged per pod and smoothed over recent readings), its memory, its policy and the autoscaler’s
last decision, in words. A process is measured whether or not it is autoscaled.
set keeps a process between --min and --max replicas (--min at least 1, --max at most 50) and tries to hold
average CPU near --cpu percent (10 to 95) of its limit. About once a minute the autoscaler works out the count that
would bring CPU back to the target, then limits it:
- it does nothing while CPU is within 10% of the target;
- it never more than doubles the replicas, or halves them, in one step;
- it waits one minute after scaling up and five minutes after scaling down;
- it only acts on a workload that has settled, whose pods were all measured in the last three minutes.
It writes the count the way canopy scale does, so a scale is a normal rollout and shows in the activity feed as
“autoscaled from 2 to 3 replicas”. A manual canopy scale still works, but the autoscaler moves the count back into
the range. A process that mounts a volume stays at one replica, and a stopped process (0 replicas) is left alone.
rm turns it off and the process keeps its current count. API: GET, PUT and DELETE
/environments/{id}/autoscale. It needs a Grove whose controller reports CPU and memory; until it does, list shows
processes as “not measured” and nothing is scaled.
Managed databases
Section titled “Managed databases”canopy services create db --engine postgres --size-gb 20 --env <environment_id>canopy services list --env <environment_id>You choose the engine and size; the operator that runs it, its storage class and its credentials are platform-managed and are not part of the customer API. Backup availability depends on the Grove’s configured backup policy and any database-specific target; Canopy does not promise that every managed Postgres is backed up automatically. Contact Canopy support if you need to confirm backup coverage for a Grove.
A Postgres pod reserves 100m of CPU and 256Mi of memory and may use up to 512Mi before it is restarted; there is no CPU limit, so a busy database is never throttled. Set them per database when you create it, or change them later (the database pod restarts once):
canopy services create db --engine postgres --cpu 250m --memory 512Mi --memory-limit 1Gi --env <environment_id>canopy services update <service_id> --memory-limit 2Gi --env <environment_id>canopy services update <service_id> --memory default --env <environment_id>CPU is 10m to 16 cores (100m, 0.5), memory 64Mi to 64Gi (256Mi, 1Gi; a bare number is MiB), and the limit may
not be below the memory it reserves. PATCH /environments/{id}/services/{service_id} takes cpu, memory and
memory_limit, and null goes back to the default.
Canopy watches managed databases the way it watches services: a failed or degraded database, one that never became
ready, one that keeps restarting or ran out of memory, or one whose Grove stopped reporting opens a problem, which
canopy services status lists with the time it began and which makes the environment read as degraded or unhealthy.
Each problem produces a notification when it opens and when it is gone.
A restore creates a new instance from a backup; to land at an exact moment instead of the end of the backup, add a target time (it must be after the backup finished, not in the future, and the WAL archive must reach it):
canopy services restore <service_id> --backup <backup_id> --name db-restored --env <environment_id> --target-time 2026-09-24T10:30:00ZTemplates on Forest
Section titled “Templates on Forest”A multi-service template whose services are all plain images (no repository builds, databases or readiness
commands) is deployed on Forest, when the team is placed there, as sibling environments under one root, tier by
tier in depends_on order. A service reaches an earlier one by its name, and ${services.<key>.host} and
${services.<key>.env.<VAR>} resolve as before. A service that does not converge is marked failed without
stopping its siblings. Templates that build a repository, provision a database or use a readiness command are not deployable this way.
Domains
Section titled “Domains”canopy domains add myapp.example.com --env <environment_id>canopy domains list --env <environment_id>Each environment (root or service) gets its own domain(s) and its own TLS
certificate, provisioned automatically after the first successful deploy
following DNS resolving to the host - no separate step needed. If a
certificate hasn’t shown up after a deploy (e.g. DNS wasn’t propagated
yet), force a retry with canopy domains ssl-enable --env <environment_id>
rather than waiting for the next deploy.
Who can reach a deployment
Section titled “Who can reach a deployment”Deployment protection decides who may open an environment or one of its previews. An environment without a policy is
public; a preview without one defaults to organization, because a pull request preview is throwaway and should not
be open to the world. Modes: public, authenticated (anyone signed in to Canopy), organization (members of the
team’s organization), shared_link (anyone with a link that carries a secret you set), password and token.
canopy protection get --env <environment_id>canopy protection set --env <environment_id> --mode organizationcanopy protection set --env <environment_id> --preview <preview_id> --mode shared_link --shared-link-secret <secret> --expires-at 2026-12-01T00:00:00ZGET and PUT /environments/{environment_id}/protection-policy (and the same under .../previews/{preview_id}/) take
{ mode, allowed_principals?, shared_link_secret?, expires_at? }. Reading needs environment:read, writing
environment:deploy. The shared link secret is stored and never returned; the policy only says hasSharedLinkSecret.
The SDK has protection.get|set|getPreview|setPreview. Enforcement happens on the Grove for every request, whether or
not anyone ever set a policy.
Protected deployments depend on Canopy being reachable. Every request to an environment or preview with a policy other
than public is checked against Canopy’s API, and the check fails closed: while the API is unreachable, visitors
get an error instead of the site, never the site without the check. Environments with no policy, and public ones, are
not checked and keep serving. If an app must stay up when Canopy is down, leave it public and do the access check
in the app.
Variables
Section titled “Variables”canopy variables set NAME value --env <environment_id>canopy variables list --env <environment_id> --reveal # values hidden by defaultcanopy variables rm NAME --env <environment_id>Values are encrypted at rest. variables set is a real upsert - it
updates an existing name in place rather than erroring on a duplicate.
Build-time vars (like a Next.js app’s NEXT_PUBLIC_* variables) need a
fresh deploy to take effect - setting the variable alone doesn’t
retroactively change an already-built image. Trigger one with
canopy deploys create --env <environment_id>.
Variables in a Dockerfile build
Section titled “Variables in a Dockerfile build”When a service is built from a Dockerfile, ordinary variables reach the build as build arguments: declare ARG NAME and
use it. A variable marked secret (canopy variables set NAME value --env <id> --secret) is not a build argument,
because a build argument is printed in the build log and stored in the image history. It is a build secret instead, and
you read it in a single RUN step:
RUN --mount=type=secret,id=NPM_TOKEN \ NPM_TOKEN="$(cat /run/secrets/NPM_TOKEN)" npm ciThe secret exists only while that step runs, and never in a layer. A secret that an ARG used to receive now arrives
empty, so move it to --mount=type=secret. Buildpack builds are not affected. Secret values are also masked as *** in
the stored build output.
From the dashboard, an environment’s Variables tab also has a Copy from another environment action - it copies every non-system variable from a sibling environment you pick, overwriting any variable that already exists under the same name (safe to run more than once). There’s no CLI equivalent yet; see the Dashboard Guide for the click-by-click version, including storage mounts, which aren’t covered on this page.