Blueprint
A Blueprint describes what an environment is made of: its services, its managed databases and caches, and the external hosts it is allowed to reach, joined by links. It is read from what the environment already runs, so there is nothing to keep in sync and reading it changes nothing. To change the environment you plan a new Blueprint, review the plan, then apply it (see Plan and apply).
Blueprint is generally available: it needs the host.blueprint platform feature, which is on for every team.
GET /environments/{environment_id}/blueprintAnyone who can read the environment can read its Blueprint.
What you get back
Section titled “What you get back”| Field | What it holds |
|---|---|
environment_ref |
The key of this environment inside document.environments. |
document |
The Blueprint: nodes, links and environments. |
mapping.nodes |
For each service or database node, the environment_service or service_instance row behind it. |
sources |
For each node and link, whether it came from a row or from a declaration in .canopy.yml. Links are keyed by their id. |
runtime |
What is observed right now for each node: phase, ready replicas, the live release, a job’s last run. It is never part of the document. |
warnings |
Things the data proves are wrong or worth a look. Each names the node or link and the evidence. |
adopted, applied_revision |
Whether the environment was adopted into the project Blueprint, and the revision it last applied (null until it has one). |
The document and runtime follow the @canopy/blueprint types, so their field names are camelCase (mountPath,
envPrefix), unlike the snake_case of the rest of the API.
type |
Comes from |
|---|---|
service (kind: web, worker, job) |
An app service: its source, build, start command, port, health check, scale and volumes. |
postgres, redis |
A managed database or cache. management is managed, or external when you brought your own. |
datastore |
An external instance whose engine Canopy does not know. |
external |
A host a service may reach: one of its Blueprint links, or an entry under egress: in its .canopy.yml, with its ports. |
grove |
A machine of your team (groveId, and its name as label) that a service is bound to. The Blueprint only refers to it: applying never creates, changes or removes the machine. |
A node’s key is the service’s or instance’s name. If a database and a service share a name, or a name is longer than
32 characters, the database’s key is shortened or numbered; mapping.nodes always says which row a key stands for.
A link says one service requires a capability from another node:
capability |
Meaning | Comes from |
|---|---|---|
postgres, redis, datastore |
The service is bound to the database or cache. options.envPrefix is the binding’s prefix, options.names the variable names mode, options.waitForReady whether the service is held back until the instance has credentials. A binding that does not wait shows waitForReady: false. |
service_bindings on the service, or services: in .canopy.yml when the service has none (the service wins when both exist). |
https-egress, tcp-egress |
The service may reach the external host. options.port narrows it to one port. |
The service’s runtime_egress (links made here), and egress: in .canopy.yml. A host both declare is one link, marked as from the row. |
grove-accelerator, grove-runner, grove-inference |
The service may ask Host for the machine, for GPU jobs, CPU jobs or model serving. options.priority (0 to 9, lowest tried first) orders the machines of one role. At most 8 machine links per service. |
grove_bindings on the service; see machines bound to a service. |
http |
A service calls a web service: the caller gets a variable set to the callee’s address. options.variable is its name, options.port the callee’s port when that is not the one it listens on. |
The caller’s generated_env. |
Domains are in document.environments[environment_ref].domains, per web service.
A database’s credentials are managed by Canopy. The Blueprint never contains a password, a connection string or a variable value, and never says where a credential is stored.
Links that need the compile to know more
Section titled “Links that need the compile to know more”A link to a database or cache becomes a binding. The other two links change what Canopy puts into the workload:
- Service to service (
http). The caller getsAPI_URL(or the name inoptions.variable) set tohttp://<in-cluster name of the callee>:<port>. Canopy works the address out at each deploy, so every environment and every preview points at its own callee, never at another environment’s. A variable of the same name that you set yourself wins, and the plan warnsgenerated_variable_shadowed.GET /environments/{id}/variableslists them undergenerated(read only, with the link that sets each andunresolvedwhen the target is gone), and a backup carries them with the name of the service they point at, so a restore points them at the service of the same name. The callee must be a web service with a port. A service link does not delay a rollout and may form a cycle. - External host (
https-egress,tcp-egress). The host joins the service’s.canopy.ymlegress:list at compile time (once each). The first hostname a service may reach is a change of posture: from then on it can reach only its declared hosts on the declared ports, DNS, the other services of its project and Canopy’s platform relays; every other address is blocked. Removing the last hostname lifts that. Plain IPv4 targets only add reachability. The plan shows this as its own line (postureChangeon the operation, the impactegress_posture_changed). An IPv4 address the Grove does not allow in its egress IP allowlist is refused at plan time (egress_ip_not_allowed) and again at deploy. A host that a service’s.canopy.ymlalso declares stays reachable if you remove only the link here (egress_still_declared_in_file).
A link to a service in the same project opens no network path: services of a project can already reach each other.
Every service’s .canopy.yml is read
Section titled “Every service’s .canopy.yml is read”Canopy keeps a record of the .canopy.yml each service deployed with, at the commit of the build. A binding or egress:
entry declared in a service’s file is listed from the first build that deploys the service after it was added; a file
that disappears is recorded as no configuration, so what it declared stops being listed.
Warnings
Section titled “Warnings”Every warning has a code, a severity (info or warning), a message and evidence.
| Code | When |
|---|---|
data_node_unused |
A database or cache no service is bound to. |
binding_instance_missing |
A service is bound to a database that does not exist. |
domain_target_missing |
A domain points at a service that no longer exists. |
web_service_without_domain |
(info) A web service of an environment with several services has no domain. |
canopy_yml_binding_only_in_file |
(info) A service reaches a database through a binding declared only in .canopy.yml. |
egress_not_enforceable |
An egress: entry the environment’s Grove cannot enforce: it predates per-host egress, port-scoped egress or IP targets, or the IP is not in the Grove’s allowlist. |
production_branch_not_default |
An environment named production deploys a branch other than the project’s default branch (from its active CI connection) while another environment of the project deploys the default one. |
oom_without_memory_limit |
A service with no memory limit has a process that was killed for running out of memory. |
Nothing else is guessed: a warning appears only when the rows and the Grove’s report prove it.
Example
Section titled “Example”{ "environment_ref": "5b3d0f0e-6a54-4d8c-9f5b-0a7e4c2b9d11", "document": { "version": 1, "nodes": { "web": { "key": "web", "type": "service", "kind": "web", "source": { "kind": "repository", "repository": { "provider": "github", "path": "acme/shop" }, "branch": "main", "path": "services/web" }, "run": { "port": 8080 } }, "main-db": { "key": "main-db", "type": "postgres", "management": "managed", "size": { "storageGb": 20 } }, "ext-api-stripe-com": { "key": "ext-api-stripe-com", "type": "external", "protocol": "https", "host": "api.stripe.com", "ports": [443, 80] } }, "links": [ { "id": "web->ext-api-stripe-com:https-egress", "from": "web", "to": "ext-api-stripe-com", "capability": "https-egress" }, { "id": "web->main-db:postgres", "from": "web", "to": "main-db", "capability": "postgres", "options": { "envPrefix": "MAIN_DB_" } } ], "environments": { "5b3d0f0e-6a54-4d8c-9f5b-0a7e4c2b9d11": { "domains": { "web": ["shop.example.com"] } } } }, "mapping": { "nodes": { "web": { "kind": "environment_service", "id": "…" }, "main-db": { "kind": "service_instance", "id": "…" } } }, "sources": { "web": "row", "main-db": "row", "web->main-db:postgres": "row", "ext-api-stripe-com": "canopy_yml", "web->ext-api-stripe-com:https-egress": "canopy_yml" }, "adopted": false, "applied_revision": null, "runtime": { "environmentId": "5b3d0f0e-6a54-4d8c-9f5b-0a7e4c2b9d11", "fetchedAt": "2026-10-07T12:00:00.000Z", "nodes": { "web": { "phase": "running", "ready": { "ready": 2, "desired": 2 }, "problems": [] }, "main-db": { "phase": "running", "instance": { "phase": "Cluster in healthy state", "status": "active" }, "problems": [] } } }, "warnings": []}The Blueprint tab
Section titled “The Blueprint tab”When host.blueprint is on, an environment gets a Blueprint tab next to Topology, under Observe. It draws the
response above. Until you choose Edit Blueprint (see Editing in the tab) it changes
nothing: nodes cannot be moved, connected or deleted, and positions are computed again on every load.
What it shows:
- Services (a globe for web, a cog for worker, a clock for job), databases and caches, and external hosts
(dashed outline), left to right. A link runs from the service that needs something to what it needs. The label
says what and where:
PostgreSQL :5432,Redis :6379,HTTPS :443. - Line style tells links apart without colour: solid for a database or cache binding, dashed for a service calling another, dotted for a service allowed to reach an external host.
- Status on each service and database is an icon and words, never colour alone:
Running 2/2(ready out of wanted),Deploying,Degraded 0/1,Failed,Not deployed,Provisioning,Healthyfor a database, andLast run succeededfor a job (a job that is executing readsRunning now, one that is waitingRun queued, one that has never runNever run). It is read again every 30 seconds while the tab is visible, and when you come back to it. - Declared in .canopy.yml (a file icon) marks a node or link that comes from the file rather than from the environment’s own settings. Change those in the file.
- Warnings appear on the node they name and in a panel below the diagram, with the evidence behind each one.
Select a node or link to open its details on the right: source, build, runtime settings, domains, volumes, the variable names that come from links (never values; they read “managed secret”), links in and out, and live state. Each section links to the page where that setting is changed.
Keyboard use:
| Key | Does |
|---|---|
| Tab | Moves into the diagram, onto one node. A second Tab leaves the diagram. |
| Arrow keys | Move to the neighbouring node in that direction. |
| Enter or Space | Opens the details of the focused node. |
| Escape | Closes the details and keeps focus on the node. |
Links are reached from the details of either end, under Connections. On a screen narrower than 768 px there is no diagram: the same facts are a list of services, databases and caches, external hosts, links and warnings, and the details open full screen. Screen readers get that list beside the diagram as well.
While Blueprint is switched off platform-wide, the page shows a short explanation instead of the diagram. If the status cannot be refreshed, the last data stays on screen and says so.
Editing in the tab
Section titled “Editing in the tab”Edit Blueprint switches the tab to editing. It is shown to anyone who might be allowed to plan a change; when the
permissions route says the caller lacks project:blueprint, or a plan answers 403, the tab stays read only and says
so. A change is never sent until you choose Review changes, and nothing is applied until you choose Apply.
A change is made in a draft kept in the page. The Blueprint document stays the source of truth: the draft is that
document with your edits, and what is sent for review is the list of patch operations that turn the environment’s
current document into it. The server plans from the patch and checks it again, so a check in the page is a courtesy,
never the rule. Discard changes throws the draft away (after asking), and so does leaving edit mode.
What you can do:
| Gesture | Does |
|---|---|
| Add web service, worker, job, PostgreSQL, Redis | Adds a node to the draft with sensible defaults. A new service takes its repository and branch from a service that already exists. |
| Drag from a service’s right handle | Highlights what it can connect to (outlined, with Connect here) and dims what it cannot. Dropping on a valid target adds a link to the draft. Dropping on an invalid one is refused with the reason. |
| Drag an Add … button onto the canvas | Adds that node where you drop it. The button also adds it without dragging, for keyboard use. |
| Drag an applied node | Moves it and saves the position for everyone who opens this project’s Blueprint (needs the Blueprint permission). Reset layout in the header brings back the automatic arrangement. |
| Drop on empty canvas | Opens Connect service to…: a new PostgreSQL, a new Redis, an existing database or cache, another service, or an outside host. A new database or outside host comes with its link as one change. Another service and an outside host are offered when the server reports those link kinds as supported (GET .../blueprint/capabilities); otherwise they are listed with the reason. |
| Drop on empty canvas, A machine of your team… | Choose one of your team’s machines (listed by GET .../blueprint/capabilities), what the service uses it for (GPU jobs, CPU jobs or model serving) and a priority. The machine appears as a dashed node; a machine link has a Priority field. Offered when the server reports the machine link kinds as supported. |
| Select a link, then its fields | A service link has an Address variable (the variable the consumer reads the address from; empty means the default), a Port (empty means the service’s own) and Wait for the service. A database link has the Variable prefix. An outside host is a node with a protocol (HTTPS or TCP), a host and up to 8 ports; a wildcard such as *.example.com is allowed over HTTPS only. |
| Select a service, Connect to… (or Shift and C on a focused node) | The same, from the keyboard: choose from a list. Targets that cannot be used are listed with the reason. |
| Select a node or link, Delete (or Remove in the details) | Marks it for removal. It stays drawn, dashed and labelled Removed, until you apply. |
The details of a selected node become a form for what a plan can change today: kind, source path or image, build type,
Dockerfile path and command, start and migrate commands, port, health check, replicas, CPU and memory limits and
domains of a service, the storage size of a database that is not applied yet, the variable prefix of a link. The
fields the server cannot apply yet are shown disabled with its reason: the branch, outbound hosts, resizing
a database, a database’s engine, volumes. The Repository of a service is a list of the repositories attached to the
environment when the team has host.multi_repository and at least two are attached; choosing one moves the service
(the first service stays on the primary repository, and services of one repository share a branch, which the plan
checks). With the feature off, or with only one repository attached, the field is shown disabled and says why; attach
another repository on the Repositories page first. A node or link declared in .canopy.yml cannot be
removed here.
Changes are drawn on the diagram with an icon and a word as well as colour: New (plus), Changed (pencil) and
Removed (minus), on nodes and on links. Selecting a changed node or link explains the exact change, field by
field (scale.replicas: 2 → 4), and, once there is a plan, what the plan does for it.
Review and apply
Section titled “Review and apply”Review changes asks the server for a plan and opens it beside the diagram:
- Each operation is listed with Add, Change or Remove (icon and word) and a chip saying whether it applies now (a database is created or deleted, a domain row is added or removed) or on the next deploy.
- What Canopy will configure summarises workloads, databases, bindings (with the variable names that arrive from a managed secret), domains, volumes and credentials.
- Problems the server found are listed with how to fix them, and apply stays off. A problem says whether it is not supported here yet, refused by a safety check, in conflict with something that exists, or invalid.
- A plan that deletes a database or a service opens the impact dialog: the consumers that lose access, the bindings and
generated variables removed, the capabilities lost and the last backup. A deleted database needs its name typed, and
every plan with a destructive impact needs the acknowledgement, which is what sends
acknowledge_impacts. - The plan counts down to its expiry (30 minutes). An expired plan, or one the server calls stale
(
blueprint_state_changed), offers Plan again, which plans the same draft against the current state.
Apply changes configuration only. Apply and deploy is a separate button and also queues a deploy after a fully applied plan. The answer is shown as a result, whatever its status: what was done, what failed with the server’s message and what was skipped, so a partial failure is an explanation and a Plan again, not an error. After an apply the tab reads the Blueprint again; a fully applied plan clears the draft. Apply history lists the latest applies.
Keyboard use while editing: every control of the toolbar is a button in tab order, the menu and the Connect to… list work with the arrow keys, Enter and Escape, and Delete removes the selection unless focus is in a field, a button, a menu or a dialog. On a screen narrower than 768 px editing works through the list, the details sheet and the Connect to… list.
From the CLI, the SDK and MCP
Section titled “From the CLI, the SDK and MCP”All three read the same route and need the same feature.
canopy blueprint show --env <environment_id> [--json]canopy blueprint export --env <environment_id>show prints the nodes grouped as web services, workers, jobs, databases and caches, and external hosts, each with
its runtime state, then the links with their capability and port and the warnings with their evidence. export
prints only document, with keys sorted, so it is the same text every time for an unchanged environment.
const blueprint = await sdk.blueprint.get(environmentId);The MCP tool is host_get_blueprint with an environment_id.
Runtime of a job
Section titled “Runtime of a job”A job has no standing replicas, so its runtime has no ready count and its phase follows its last run: running
while a run is executing, deploying while one is waiting to start, failed when the last run failed or timed out,
and not_deployed otherwise (it succeeded, or it never ran). lastExecution says which.
Plan and apply
Section titled “Plan and apply”A change is made in two steps so that it is always reviewed first. Both need host.blueprint.
POST /environments/{environment_id}/blueprint/planGET /environments/{environment_id}/blueprint/plans/{plan_id}POST /environments/{environment_id}/blueprint/applyGET /environments/{environment_id}/blueprint/appliesGET /environments/{environment_id}/blueprint/applies/{apply_id}Planning and applying need the project:blueprint action, which owners and admins have by default and developers and
viewers do not; a custom role can grant it. Reading a plan or the applies needs only environment:read. Applying
also needs, for every operation in the plan, the action the equivalent direct route needs (today environment:deploy
for every operation), and environment:approve_deploy for operations that take effect immediately on an environment
that requires deploy approval.
Send the Blueprint you want, as document (the whole document, in the shape GET returns), or as a patch of
operations applied to the environment’s current document:
op |
Fields |
|---|---|
node.upsert |
node: the whole node, replacing the node with that key |
node.remove |
key: removes the node, the links that touch it and its domains |
link.add |
link |
link.remove |
id |
domain.add, domain.remove |
node (a web service) and hostname |
Exactly one of document and patch. The server validates the document itself, whatever a client checked first. A
document that is not valid answers 422 with error_code: blueprint_invalid and violations, each with a code, a
path and a message, and nothing is stored. A secret value in a document is refused. A service may declare variables: { "value": "..." } for a plain value, or { "secret": true } for a name whose value you set on the Variables tab, where secrets are entered. The plan adds or changes the plain ones (variable.set), warns secret_variable_missing for a declared secret that does not exist yet, and removes (variable.unset, destructive) a variable the environment’s applied revision declared and this document drops. A variable the Blueprint never declared is left alone. A single-service environment keeps its variables environment-wide; with several services each variable belongs to its own service.
Nothing is changed by planning. The plan is stored, bound to a hash of the environment’s current state
(base_state_hash), and expires 30 minutes later (expires_at). It holds:
| Field | What it holds |
|---|---|
status |
ready, blocked (it has errors), applied (see apply_id) or expired. |
operations |
Ordered operations on the rows that already exist, each with a timing. |
impacts |
What a destructive change touches: the consumers of a database, the bindings and credential variables removed, the capabilities lost, the last backup. |
errors |
Blocking problems. They mirror the checks the direct routes make, so a refusal the apply would hit shows up here first. |
warnings |
Things worth knowing that do not block. |
requires_acknowledgement |
true when an impact is destructive: the apply must say acknowledge_impacts: true. |
summary |
Counts of operations, by timing and kind. |
The operations, in the order they run:
op |
Does | timing |
|---|---|---|
instance.create |
Creates a managed PostgreSQL or Redis (or an external datastore from a secret reference). | immediate |
service.create |
Adds a web, worker or job service. | next_deploy |
domain.detach, volume.detach |
Detaches a domain (its row is deleted) or a volume (its data is kept for its retention window). | immediate, next_deploy |
service.update |
Changes a service’s kind, source, build, start command, port, health check, scale or limits. | next_deploy |
binding.add, binding.update |
Links a service to a database (service_bindings), with names and waitForReady when the link sets them. |
next_deploy |
generated_variable.set |
Sets the variable (variable) that holds the address of a service the caller is linked to. |
next_deploy |
egress.add |
Lets the service reach entry (host or host:port). postureChange: becomes_restricted on the first hostname. |
next_deploy |
domain.attach, volume.create |
Attaches a domain or a volume. | immediate, next_deploy |
egress.remove |
Stops letting the service reach entry. postureChange: becomes_unrestricted on the last hostname. |
next_deploy |
generated_variable.remove |
Stops setting the variable. | next_deploy |
variable.set |
Adds or changes a declared variable (variable, input.value), or turns an existing one into a secret without touching its value. Needs variables:write. |
next_deploy |
variable.unset |
Removes a variable the applied revision declared. Destructive. Needs variables:write. |
next_deploy |
binding.remove |
Unlinks a service from a database. | next_deploy |
grove_binding.set |
Replaces the machines the service is bound to with groveBindings (grove_id, role, priority); one operation per service. A machine the team may not bind is a grove_not_available plan error. |
immediate |
service.delete |
Removes a service. | next_deploy |
instance.delete |
Deletes a database and its data. There is no retention window. | immediate |
immediate means it takes effect when the plan is applied: a database is created or deleted, a domain row is added or
removed. Everything else only changes configuration; the workloads pick it up on the next deploy, including the
routes of a domain.
What a plan cannot do yet is reported as an error with source: unsupported: an external host or a service-to-service
link (outbound hosts are declared in .canopy.yml for now), a branch other than the one of the service’s repository,
resizing a database or a volume, moving a volume to another service, changing a database’s engine, removing the default service,
and variables. A binding or host declared in .canopy.yml can be listed but not removed here.
What a plan cannot do yet is reported as an error with source: unsupported: another repository (without
host.multi_repository) or another branch than its repository’s for a service, resizing a database or a volume, moving a volume to another service, changing a database’s engine, removing
the default service, and variables. A binding or host declared only in .canopy.yml can be listed but not removed here
(declared_in_file). Link errors: generated_variable_conflict (two links set one variable), reserved_variable_name,
egress_port_not_declared, egress_wildcard_ports (a wildcard host only supports ports 443 and 80 together),
too_many_egress_targets (more than 16 port-scoped hosts), egress_ip_not_allowed.
A service may build from another repository of the environment when the team has host.multi_repository: the node’s
source.repository (provider and path) names a repository attached to the environment, and derive reports the
repository of each service’s own row. A repository that is not attached is the plan error repository_not_attached
(attach it first, see Multi-repository environments); without the feature it stays
multi_repository_unsupported. canopy blueprint plan and apply print the services that change repository under
Repositories, and add attach it: canopy repositories attach <owner/name> --env <id> --provider <provider> to a
repository_not_attached error; canopy blueprint plan --service <node> --repository <owner/name> moves a service to an
attached repository without writing the node by hand.
{ "plan_id": "…", "base_state_hash": "…", "deploy": false, "acknowledge_impacts": false }plan_id and base_state_hash (the plan’s own) are required, so review cannot be skipped. Apply changes
configuration only. It runs the operations in order through the same service functions the direct routes use, so
every guard applies again, stops at the first failure and records the result of each operation, with the ids of the
rows it produced. It is not one transaction; the status says what happened:
status |
Meaning |
|---|---|
applied |
Every operation is done. |
partially_applied |
Some operations are done, one is failed and the rest are skipped. Resume it, or plan again. |
failed |
The first operation failed. |
It answers 200 with the apply record whatever the status. Nothing is deployed unless deploy is true, and then
only after a plan that fully applied: a build is queued (build_id), or deploy_error says why it could not be. A
deploy that cannot be made at all (no repository, build minutes used up) is refused before anything changes.
A plan applies once, and only against the state it was made for:
| Status | error_code |
When |
|---|---|---|
| 409 | blueprint_state_changed |
The environment changed after the plan was made. Plan again. |
| 409 | blueprint_plan_already_applied |
The plan was applied; apply_id says which apply. |
| 409 | blueprint_apply_in_progress |
Another apply is running for this environment. |
| 410 | blueprint_plan_expired |
The plan is older than 30 minutes. |
| 422 | blueprint_plan_has_errors |
The plan has errors; they are in errors. |
| 422 | blueprint_impacts_unacknowledged |
The plan deletes data or a service and acknowledge_impacts was not sent. |
| 422 | deploy_not_possible |
deploy was asked for and cannot be done. |
| 403 | forbidden |
An action the plan needs is missing; action names it. |
Each apply records one blueprint.applied audit event, and every service, volume and domain it touches records the
same events as the direct routes, tagged with the apply id. GET .../applies lists applies, newest first, and pages
with before.
Resume an apply
Section titled “Resume an apply”POST /environments/{id}/blueprint/applies/{apply_id}/resume (canopy blueprint resume --env <id> --apply <apply_id>,
blueprint.resumeApply() in the SDK, host_resume_blueprint_apply in MCP) finishes the newest apply of an environment
when it is partially_applied or failed. It plans the same desired Blueprint again against the environment as it is
now, so what already took effect is not planned twice, runs what is left in order, and appends the results, each marked
resumed, to the same apply record. The same guards apply as for an apply (errors in what is left, unacknowledged
destructive impacts, the actions every remaining operation needs, another apply running). Only the newest apply can be
resumed: 409 blueprint_apply_not_resumable for an apply that is not partially_applied or failed, 409
blueprint_apply_superseded when a newer apply exists. The audit event is blueprint.apply_resumed. Nothing deploys
unless deploy is true.
What a plan can express
Section titled “What a plan can express”GET /environments/{id}/blueprint/capabilities (needs environment:read; SDK blueprint.capabilities(environmentId))
tells an editor what it may offer, so it carries no tables of its own. link_capabilities lists every kind of link
(http, postgres, redis, datastore, https-egress, tcp-egress) with its category, the service kinds that can
consume it, the effects it has on the consumer, the credential_keys it provides, the names a conventional naming
mode adds (default_prefix, suffixes, example_names) and whether this server can plan and apply it (supported).
fields answers, for variables, branch, repository, egress, volumes, domains, resize and engine,
whether a plan can change the property and, when it cannot, a reason and a fix. The repository field is supported
only for a team with host.multi_repository.
Propose a Blueprint from a repository
Section titled “Propose a Blueprint from a repository”A new project has no environment to read a Blueprint from. This endpoint reads a repository and proposes one. Nothing is created or stored.
POST /projects/{project_id}/blueprint/proposal{ "repository": "acme/shop", "branch": "main", "provider": "github" }It needs host.blueprint and the same permission as POST /projects/{project_id}/environment-proposals
(environment:create), reads the repository through your connected git provider in the same way (a root compose file,
else a root Procfile, else Dockerfiles and buildpack markers; at most 30 Dockerfiles and project files, plus the
package.json, requirements.txt and pyproject.toml of each service’s folder), and turns the result into a proposed
document. provider is optional (github, gitlab, bitbucket, canopy; default unknown). path is not
supported: the repository root is always read, and a sub-folder answers 400 path_unsupported.
The answer is an envelope, because the evidence does not belong in the document:
| Field | What it holds |
|---|---|
document |
A @canopy/blueprint document with only what the repository states or implies: services, managed postgres and redis nodes, and links between them. It has no domains, no external hosts and no variables. |
valid, violations |
The result of validateDocument on document. |
evidence.nodes, evidence.links |
For each node and link: proposed: true, confidence, and entries saying where each fact came from (file, line and the YAML key when known). A node also has kind_confidence, requires_confirmation and attributes.language and attributes.framework. |
suggestions |
Things the repository points at that are not in the document: a public domain for a published port, an outbound host named in a variable, a host-path volume, a database the code looks like it uses. Each has an id, a code, a message, a detail and its own evidence. |
unsupported |
What a Blueprint plan cannot apply yet, with the reason: variables (by name, with whether each is secret and must be entered), service-to-service links, an engine Canopy does not manage, a healthcheck command. |
warnings |
The warnings of the environment proposal, each with the node it concerns. |
plan |
A dry run of the planner on an empty environment of this repository: operations, errors, warnings, summary and assumptions. Nothing is stored. |
A node or link is explicit when the repository states it: a compose service, a depends_on or links entry, a
connection URL such as postgres://...@db whose host is a compose service, a Procfile process. It is inferred when
it is a heuristic: a bare REDIS_HOST=cache, an image that is PostgreSQL or Redis compatible but not the plain engine,
or a service found only from a folder layout. A link proposal is never silent: its evidence lists the line that named
it, and a proposal is reviewed before anything is applied.
Compose images of PostgreSQL and Redis (postgres, redis, valkey and the Bitnami builds) become managed data
nodes instead of the blocking image_service_in_build_environment warning, linked to each service that names them
with the default binding prefix (DB_ for a node called db). Their credentials, volume and published port are not
imported; each is listed as a suggestion. Other image-only services become image services. MySQL, MongoDB, RabbitMQ and
similar engines are listed as unsupported with a suggestion to add an external datastore.
Secret values are never returned. A variable whose name looks like a secret, or whose value is a URL with a password,
is listed by name as secret: true and has to be entered after the plan is applied.
plan.assumptions says what the dry run took for granted: an empty Forest environment, the host.environment_services
result for your team, and that the first service takes over the environment’s default service. It also lists what it
did not check (grove_capacity_for_volumes, instance_name_conflicts, domain_conflicts); those run when the plan is
made for the real environment.
| Status | When |
|---|---|
| 400 | No connected git provider, a bad repository, branch or provider, an unsupported path, or a compose file that cannot be read (error_code compose_invalid_yaml, compose_too_large or compose_no_services). |
| 403 | The environment:create action is missing, or host.blueprint is switched off (error: feature_disabled). |
| 404 | No such project. |
| 502 | The repository could not be read from the provider. |
The same proposal can be asked of a team that has no project yet, as POST /teams/{team_id}/blueprint/proposal, which
the environment creation wizard uses for its evidence view. It needs host.blueprint for that team and the
environment:create action on it, and answers 403 feature_disabled otherwise.
In the creation wizard. With host.blueprint on, the services step lists the managed databases the repository
implies (PostgreSQL and Redis) with a tick box each, and the links to them with a tick box each: a link the file states
is ticked, a link Canopy only inferred (a bare REDIS_HOST=cache) is not. When you deploy, the services are created as
before, then the ticked databases and links are planned and applied as one Blueprint patch, then the first deploy is
queued. If that second step fails the page says so and offers to try only it again, to deploy without them, or to open
the environment; a plan that would need an impact acknowledgement is not applied for you. A service named like a ticked
database blocks the deploy until one of them is renamed. Values for secrets are entered in the same step, before
anything is created.
From the command line, canopy blueprint propose (--project <slug> | --team <team_id>) --repository <owner/name> --branch <branch> [--provider ...] [--json] calls either route and prints the nodes, links, evidence, suggestions, unsupported
items, warnings and the dry run (see the CLI reference). The SDK has
projects.proposeBlueprint(projectId, { repository, branch, provider }) and teams.proposeBlueprint(teamId, input), and
the MCP server has host_propose_blueprint (a project or a team, one of the two).
Revision history of a project
Section titled “Revision history of a project”A project’s Blueprint is stored as numbered revisions: 1, 2, 3 and so on, per project, each a complete document
(nodes, links and every environment’s overlay) that never changes once stored. A revision is added by publishing a
draft or by reverting to an earlier one (see below); adoption and write-through will add more. The three read routes
here need host.blueprint and environment:read on the project’s team.
GET /projects/{project_id}/blueprint/revisionsGET /projects/{project_id}/blueprint/revisions/{number}GET /projects/{project_id}/blueprint/revisions/{from}/diff/{to}project_id is the id or the slug. The list is newest first, without documents, and each entry has number,
parent_number (the revision it followed, null for revision 1), hash (SHA-256 of the canonical JSON of the
document, so equal documents have equal hashes however their keys are ordered), source, message, created_by,
created_by_name and created_at. Page with limit (1 to 100, default 50) and cursor: pass next_cursor back as
cursor to get the revisions older than the last one you have; it is null on the last page. A project without
revisions returns an empty list.
source says where the revision came from:
| Source | Meaning |
|---|---|
manual |
Someone edited and published it. |
write_through |
An existing route (for example app-services update) changed a field the Blueprint models. |
import |
Derived from the rows of one or more environments. |
revert |
A copy of an older revision, made as a new revision. History is never rewritten. |
The single-revision route adds document, in the @canopy/blueprint shape (camelCase). The diff route compares two
revisions of the same project, in either order, and returns from and to (the same entries as the list),
identical, and diff with nodes, links, groups and environments. Each is { added, removed, changed }: keys
that only exist in to, keys that only exist in from, and for keys in both the dotted path of every field that
differs with its before and after value (absent when the field did not exist on that side). A list that is keyed by
name, such as a service’s volumes, is compared by name and addressed as volumes[uploads].
| Status | When |
|---|---|
| 400 | A bad limit or cursor, or a number that is not a whole number from 1 up. |
| 403 | The environment:read action is missing, or host.blueprint is switched off (error: feature_disabled). |
| 404 | No such project (also for a project you are not a member of), or no such revision. |
From the CLI, the SDK and MCP:
canopy blueprint revisions --project <project_id|slug> [--limit <1-100>] [--cursor <cursor>] [--json]canopy blueprint show --project <project_id|slug> --revision <number> [--json]canopy blueprint diff --project <project_id|slug> --from <number> --to <number> [--json]revisions prints one line per revision (number, time, source, author, message) and the command for the next page.
show --project --revision prints the metadata of one revision with its nodes, links and environment overlays; with
--env instead, show still prints the Blueprint derived from an environment. diff prints what was added (+),
removed (-) and changed (~, with each field’s old and new value) per section, or No differences..
const page = await sdk.blueprint.listRevisions(projectId, { limit: 20 });const revision = await sdk.blueprint.getRevision(projectId, 3);const changes = await sdk.blueprint.diffRevisions(projectId, 2, 3);The MCP tools are host_list_blueprint_revisions (project_id, optional revision, limit, cursor) and
host_diff_blueprint_revisions (project_id, from_revision, to_revision). MCP takes the project id, not the slug.
Drafts, publishing and reverting
Section titled “Drafts, publishing and reverting”You change a project’s Blueprint through a personal draft, then publish it as the next revision. A draft is private to
its author, there is one per person and project, and saving it changes nothing else: no environment, no revision. All
of these routes need host.blueprint and the project:blueprint action (admin and owner) on the project’s team.
GET /projects/{project_id}/blueprint/draftPUT /projects/{project_id}/blueprint/draft { "document": {...}, "base_revision": 3 }DELETE /projects/{project_id}/blueprint/draftPOST /projects/{project_id}/blueprint/draft/publish { "message": "add the worker" }POST /projects/{project_id}/blueprint/revert { "to_revision": 2, "base_revision": 3, "message": "..." }PUT replaces your draft with document, which must be a valid Blueprint (422 blueprint_invalid with the
violations, or blueprint_too_large over 512 KiB). base_revision is the revision you edited from, null for a
project with no revisions, and it must be the newest one: if someone published since, nothing is saved and the answer is
409 blueprint_revision_conflict with base_revision and latest_revision. The draft you read back has
base_revision, latest_revision, stale (a newer revision exists, so publishing is refused), unchanged (it equals
its base), hash, document and the two timestamps. GET answers 404 draft_not_found when you have none, and
DELETE answers 204 whether or not you did.
publish stores the draft as the next revision (source manual, 201) and removes the draft. A stale draft is
refused with the same 409 and kept, so its edits are not lost: save the document again against the newer revision.
POST /projects/{project_id}/blueprint/draft/rebase (SDK blueprint.rebaseDraft) does that for you. It replays what
you changed since the draft’s base on the newest revision, by node, link, group and environment overlay and, inside
one, by field, so edits to different things merge. A field you and the newer revision changed differently is a
conflict: nothing is saved, rebased is false and conflicts lists each with an id (for example
nodes.web.scale.replicas), its section, key and path, and the base, draft and newest values. Send
{ "choices": { "<id>": "draft" | "newest" } } to settle them; the draft is saved on the newest revision once none is
left. A draft already on the newest revision comes back unchanged. The merged document must still be valid (422 blueprint_invalid with violations, for example a link to a node the newer revision removed).
A draft equal to the newest revision adds nothing (200, created: false) and is still removed. message is at most
500 characters. Two people publishing on the same base cannot both win: the second gets the 409.
revert adds a revision whose document equals revision to_revision (source revert, message “Revert to revision N”
by default). History is never rewritten and no environment changes: plan and apply the new revision as usual. Send
base_revision to refuse the revert unless it is still the newest revision. Reverting to the newest revision adds
nothing (200, created: false); a revision that does not exist is 404 revision_not_found. Your draft is left as it
was, so it may become stale.
Publishing and reverting are audited (blueprint.revision_published, blueprint.reverted) when a revision is added.
canopy blueprint draft start --project <project_id|slug> [--revision <number>] [--json]canopy blueprint draft show --project <project_id|slug> [--document] [--json]canopy blueprint draft save --project <project_id|slug> -f <document.json> --base <revision|none> [--json]canopy blueprint draft publish --project <project_id|slug> [--message <text>] [--json]canopy blueprint draft discard --project <project_id|slug> [--json]canopy blueprint revert --project <project_id|slug> --to <number> [--base <revision|none>] [--message <text>] [--json]start saves a draft equal to a revision (the newest by default) as the starting point. show --document prints only
the document, ready to edit; save -f takes a document or the output of show --json. A project with no revisions
starts from an empty document (--base none).
await sdk.blueprint.saveDraft(projectId, { document, base_revision: 3 });const draft = await sdk.blueprint.getDraft(projectId);const { revision, created } = await sdk.blueprint.publishDraft(projectId, { message: "add the worker" });await sdk.blueprint.revert(projectId, { to_revision: 2 });The MCP tools are host_get_blueprint_draft, host_save_blueprint_draft, host_publish_blueprint_draft,
host_discard_blueprint_draft and host_revert_blueprint, all taking the project id.
Adopting environments, drift and the shared layout
Section titled “Adopting environments, drift and the shared layout”A project’s Blueprint is the document in its revisions; an environment is adopted when it follows that document. All
of these routes need host.blueprint. Reading needs environment:read; changing anything needs project:blueprint.
GET /projects/{project_id}/blueprint where every environment standsPOST /projects/{project_id}/blueprint/adopt { "environment_ids": [...], "confirm": true, "message": "..." }POST /projects/{project_id}/blueprint/draft/from-environment { "environment_id": "..." }GET /environments/{environment_id}/blueprint/driftGET /projects/{project_id}/blueprint/layoutPUT /projects/{project_id}/blueprint/layout { "positions": {...}, "groups_collapsed": {...}, "mode": "manual" }POST /environments/{environment_id}/blueprint/plan { "revision": 3 }Status. GET /projects/{id}/blueprint answers the newest revision, your own draft (base, stale, unchanged) and,
per environment, adopted, adopted_at, applied_revision, revisions_behind (newest minus applied) and the
last_apply. GET /environments/{id}/blueprint now reports the same adopted and applied_revision.
Adopt. Without confirm the project’s document is derived from the listed environments and saved as your draft,
for review. With confirm it is published as revision 1 (source import) and the environments are marked adopted.
Environments must share one shape (the same services, databases and links); they may differ in branch, image, scale,
size, variables and domains, which become the per-environment overlay. Otherwise the answer is
409 environments_structurally_different with the differences. When the project already has revisions, an environment
is adopted into the newest one only if applying it would change nothing; if it would, the answer is
409 environment_differs_from_revision with the operations, and confirm adopts nothing. Adoption is audited as
blueprint.adopted.
Write-through. From then on, an edit to an adopted environment through the app-services, services, domains,
database, scale, autoscale, storage, volume or environment-update routes, or through a Blueprint
apply, records a new revision (source write_through) once the request succeeds, and the environment’s applied revision
moves to it. With several adopted environments, the fields an environment may override go to its overlay and the rest to
the shared document; removing a node that another adopted environment still has is recorded as an exclusion for this
one. An environment that is behind the newest revision, or whose change the document cannot express, records nothing and
shows up as drift instead. The environment’s own change is never blocked by this.
Drift. GET /environments/{id}/blueprint/drift plans the revision the environment last applied against what it runs
now: state is not_applied, in_sync or drifted, and operations are the changes that would restore the revision.
To keep what the environment does instead, draft/from-environment replaces your draft with the environment’s current
state; review it and publish. To restore the revision, plan it with { "revision": N } and apply the plan. A plan made
from a revision remembers it (revision), and applying it records that revision as the environment’s applied one.
Layout. One layout per project, shared by everyone who can read it: positions (node key to x and y),
groups_collapsed and mode (manual, architecture, dependency or repository). PUT replaces it
(422 invalid_layout); GET answers defaults before one is saved.
canopy blueprint status --project <project_id|slug> [--json]canopy blueprint adopt --project <project_id|slug> --envs <id,id> [--yes] [--message <text>] [--json]canopy blueprint drift --env <environment_id> [--json]canopy blueprint draft from-env --project <project_id|slug> --env <environment_id> [--json]canopy blueprint layout [save -f <layout.json>] --project <project_id|slug> [--json]canopy blueprint plan --env <environment_id> --revision <number>const status = await sdk.blueprint.status(projectId);await sdk.blueprint.adopt(projectId, { environment_ids: [prodId, stagingId], confirm: true });const drift = await sdk.blueprint.drift(prodId);await sdk.blueprint.draftFromEnvironment(projectId, prodId);const plan = await sdk.blueprint.plan(stagingId, { revision: 4 });The MCP tools are host_get_blueprint_status, host_adopt_blueprint, host_draft_blueprint_from_environment and
host_get_blueprint_drift; host_plan_blueprint also takes a revision.
The project Blueprint page
Section titled “The project Blueprint page”With host.blueprint on, a project has a Blueprint page at /projects/{project}/blueprint (a button on the project
page, and “Go to Blueprint” in the command palette). It shows, top to bottom:
-
The diagram of the newest revision, read-only. The environment picker lists the environments that have an overlay in the document; choosing one draws that environment’s resolved Blueprint (what it leaves out, and its branch, image, scale, size and variable overrides), and Show differences lists how it differs from the shared document. Selecting a node or link opens the same inspector as the environment’s Blueprint tab.
-
Your draft, when you have one: whether it is out of date, what it changes compared with the newest revision, a message field and Publish, Discard, and View draft above to draw it instead of the newest revision.
-
Environments: each with its adoption state (not adopted, adopted at revision N, N behind) and last apply. Tick environments and Preview adoption (saves a draft) or Adopt selected (publishes revision 1, or adopts into the newest revision when they match it). Check for drift compares an adopted environment with its revision; when it differs you can Keep what is running (a draft from the environment) or Re-apply revision N (a plan to review, then Apply; destructive changes need an acknowledgement).
-
History: every revision with its source, author and message; View draws it above, Changes shows what it changed against its parent, Revert to this adds a revision equal to it.
-
Editing. Edit the Blueprint (or Edit your draft) opens the same canvas editor as an environment’s Blueprint tab, on the shared document: add a web service, worker, job, PostgreSQL or Redis node by button or by dragging it onto the canvas, connect nodes by dragging (a service to a database, another service or an outside host, when the server supports that link kind), edit a node’s source, build, run, scale and volumes and a link’s options in the details panel, rename, remove, undo and redo. Removing a node also takes it out of every environment’s overrides. Domains are not edited here; they belong to each environment. Save draft stores the document as your draft (publish it from the draft panel). Environment overrides opens the list editor with two tabs: Environment overrides picks an environment and, per node, leaves it out of that environment, overrides its branch, image, replicas or storage, and sets its domains; Document (JSON) edits the whole document, for groups and variables. Both show validation problems before saving. An out-of-date draft cannot be edited: discard it first.
-
Layout. People with
project:blueprintcan drag nodes; the positions are saved as the project’s shared layout (/blueprint/layout) and everyone sees them. Links to a moved node are redrawn as straight lines. Reset layout goes back to the automatic arrangement.
People without project:blueprint see all of it but none of the buttons that change something.
Templates as Blueprints
Section titled “Templates as Blueprints”A template is its service rows (or, for a single-service template, its own repository and database). The Blueprint view
reads those rows at read time, so every existing template renders without a migration, and saving writes the document
back to the same rows, so the older deploy paths see the same template. All of these routes need host.blueprint.
GET /templates/{template_id}/blueprint the template as a BlueprintPUT /templates/{template_id}/blueprint { "document": {...} }POST /environments/{environment_id}/blueprint/from-template { "template_id": "..." }POST /environments/{environment_id}/blueprint/from-template/finish { "template_id": "...", "values": {...} }POST /projects/{project_id}/blueprint/template { "name": "...", "slug": "...", "visibility": "team", "revision": 3 }Reading. A service built from a repository becomes a web service node (its repository, branch, folder and build
command), an image service an image node, a PostgreSQL or Redis database a managed data node, a dependency on a
database a link with the default variable prefix, and a volume a named volume. What does not fit is reported in notes
instead of being dropped silently: a dependency between two app services (a link needs a capability), a database that
is not PostgreSQL or Redis, a pinned database image, build steps, a readiness command, a public service, a key that is
not a valid node key. A literal environment variable is a variable of the node; a secret-looking one is a secret marker
and its value is never returned. The required variables come back as parameters (prompt or random).
Saving. The document replaces the template’s service rows. A template keeps services, managed PostgreSQL and Redis
and the links between them; it does not keep per-environment overrides, groups, external hosts, datastores or custom
link options (422 template_unrepresentable, with the reasons in errors), and it drops scale, run settings, a
non-automatic build and a database size (listed in ignored). A secret variable becomes a required variable the
deployer is asked for, never a stored value. A document that does not validate answers 422 blueprint_invalid.
Deploying through plan and apply. from-template plans the template into an environment that already exists and has
the template’s repositories attached, and returns the plan like any other (POST .../blueprint/apply applies it). The
first service takes over the environment’s default service and builds from the environment’s branch. A Blueprint plan
does not carry variables or build steps, so they come back in variables and build_steps and are added by finish
once the plan is applied: each service’s variables (a ${services.<key>.host} token becomes the sibling’s internal
host), its build steps, and the template’s required variables (generated, or taken from values). finish is safe to
repeat, answers 409 template_not_applied while a service or database is missing and 422 parameters_missing with the
names that need a value, and does not deploy. Creating the environment and linking its repository is still done as
before; the older deploy-template route is unchanged.
Saving a project as a template. POST /projects/{id}/blueprint/template takes a published revision (the newest by
default), uses its shared document, and creates a template from every service, not only the primary one. At least one
service must be built from a repository (422 template_needs_repository).
canopy blueprint template show --template <id> [--document] [--json]canopy blueprint template save --template <id> -f <document.json> [--json]canopy blueprint template create --project <id|slug> --name <name> --slug <slug> [--visibility private|team|global] [--revision <n>]canopy blueprint from-template --env <environment_id> --template <template_id> [--json]canopy blueprint from-template finish --env <environment_id> --template <template_id> [--set NAME=VALUE ...]const read = await sdk.blueprint.getTemplate(templateId);await sdk.blueprint.saveTemplate(templateId, document);const { plan } = await sdk.blueprint.planTemplate(environmentId, templateId);await sdk.blueprint.finishTemplate(environmentId, { template_id: templateId, values: { SITE_NAME: "Shop" } });await sdk.blueprint.saveAsTemplate(projectId, { name: "Stack", slug: "stack", visibility: "team" });The MCP tools are host_get_template_blueprint, host_save_template_blueprint, host_plan_template_blueprint,
host_finish_template_blueprint and host_save_blueprint_as_template. In the app, the template library has an “Open as a
Blueprint” button: the page draws the template, edits it (services and links, or JSON), and plans it into an
environment, applies the plan and adds the variables. The project Blueprint page has “Save as a template”.
Errors
Section titled “Errors”| Status | When |
|---|---|
| 403 | You cannot read the environment, or host.blueprint is switched off (error: feature_disabled), or the action is missing. |
| 404 | No such environment, plan or apply. |