Skip to content

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}/blueprint

Anyone who can read the environment can read its Blueprint.

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.

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 gets API_URL (or the name in options.variable) set to http://<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 warns generated_variable_shadowed. GET /environments/{id}/variables lists them under generated (read only, with the link that sets each and unresolved when 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.yml egress: 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 (postureChange on the operation, the impact egress_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.yml also 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.

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.

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.

{
"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": []
}

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, Healthy for a database, and Last run succeeded for a job (a job that is executing reads Running now, one that is waiting Run queued, one that has never run Never 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.

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

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.

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.

A change is made in two steps so that it is always reviewed first. Both need host.blueprint.

POST /environments/{environment_id}/blueprint/plan
GET /environments/{environment_id}/blueprint/plans/{plan_id}
POST /environments/{environment_id}/blueprint/apply
GET /environments/{environment_id}/blueprint/applies
GET /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.

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.

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.

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

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/revisions
GET /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.

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/draft
PUT /projects/{project_id}/blueprint/draft { "document": {...}, "base_revision": 3 }
DELETE /projects/{project_id}/blueprint/draft
POST /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 stands
POST /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/drift
GET /projects/{project_id}/blueprint/layout
PUT /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.

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:blueprint can 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.

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 Blueprint
PUT /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”.

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.