Skip to content
Install

MCP tools

Orchard exposes 214 MCP tools across 13 groups. Point any MCP client at https://mcp.your-orchard-domain and these are the calls it can make. Every tool runs as the user who authorised the connection, so the same permissions apply.

Tools are grouped into toolsets. A connection lists every toolset by default. To list fewer, add ?toolsets=databases,domains to the server URL. core is always included. Tools the connection’s scope cannot run are hidden. See MCP for details, or the compact MCP for the whole API in three tools.

toolset: deployments · read-only · idempotent

Get one compose stack: its repo, branch, compose file path, auto-deploy state and the deployments it manages.

toolset: deployments · read-only · idempotent

List the Docker Compose stacks in a project. A stack owns several deployments created from one compose file in a GitHub repo; each entry carries its services and source.

toolset: deployments · open-world

Re-read the compose file from the repo and redeploy every service in the stack. Services keep their domains and volumes; new services are added and the rest roll to the new build.

toolset: env · idempotent

The default way to change environment variables. Adds or overwrites the keys you pass and leaves every other var on the deployment untouched. The deployment restarts to pick them up.

Fixing one typo’d value, adding a new key, flipping a var to secret: all of them are this tool. You do not need to read the current env first; the merge happens here.

Related: delete_env_vars to remove keys, get_env_vars to read, set_env_vars only when you mean to replace the whole environment.

toolset: domains

Create a public ingress (domain route) for a deployment. This makes the deployment accessible via a domain name with automatic TLS. The user must point their domain’s DNS to the cluster before creating the ingress. Use validate_dns to check.

toolset: domains

Create an internal or external service for a deployment to expose ports. Use update_service to change an existing one; creating a second service for the same port will not replace the first.

toolset: dangerous · destructive · idempotent

Remove a registry credential from a project. Apps and jobs pulling from that registry lose the credential and roll; if their images are private the new pods will fail to pull.

toolset: domains · read-only · idempotent · sensitive

Read the access protection on a domain: which mode is active, the basic-auth username if any, and the bypass secret that lets automated callers through a protected domain. Requires edit access on the project. [sensitive]

toolset: deployments · read-only · idempotent

List the container registries a project can pull private images from. Passwords and tokens are never returned, only the registry host and username.

A deployment or job whose image comes from one of these registries (ghcr.io/org/app, docker.io/user/app, a bare user/app for Docker Hub) gets the credential attached automatically. Use this to work out why an image is stuck in ImagePullBackOff: if the registry is not listed, the pull is anonymous.

toolset: env · destructive · idempotent

Replace the ENTIRE environment of a deployment with the list you pass. Anything you leave out is deleted. Restarts the deployment.

This is almost never the tool you want. Reach for it only when you are deliberately declaring the whole environment, e.g. seeding a brand new deployment.

  • Changing or adding a few vars → add_env_vars (merges, leaves everything else alone).
  • Removing a few vars → delete_env_vars.
  • Seeing what is there now → get_env_vars.

Secrets read back with a null value, so you cannot round-trip them through this tool by hand: pass value: null with secret: true to keep the stored value, or omit the key entirely to delete the secret.

toolset: domains · idempotent

Put a domain behind a login, or take it back off.

Modes:

  • none: public.
  • password: one shared password, no username. Requires password.
  • basic: HTTP basic auth. Requires username and password.
  • orchard: sign in with an Orchard account that has access to the project. No credential to share or leak, so prefer it for internal tools, but the instance can have it disabled, in which case the call fails and says so.

bypassPaths stay reachable without auth, which is how you keep a webhook endpoint or /health working behind protection.

Each path on a domain is protected on its own. The reply lists the other paths on this domain that are still public in openPaths.

Not available on redirect domains. Switching away from password/basic discards the stored credential, so re-enabling means setting a new one.

toolset: deployments · idempotent · open-world

Add or replace the credential a project uses to pull private images from one registry. One credential per registry per project; setting it again overwrites the old one.

The credential is checked against the registry before it is stored, so a wrong token fails here instead of as ImagePullBackOff later. Once saved it is attached to every app and job in the project whose image is hosted on that registry, existing ones included, and those pods roll to pick it up.

What to pass per registry:

  • ghcr.io (GitHub Packages): the GitHub username and a personal access token (classic) with the read:packages scope. Fine-grained tokens cannot read packages.
  • docker.io (Docker Hub): the Docker Hub username and an access token.
  • registry.gitlab.com: a deploy token (username starts with gitlab+deploy-token) or a personal access token with read_registry.
  • quay.io: a robot account name and token.
  • anything else that speaks the Docker registry v2 API with basic or bearer auth.

toolset: domains · idempotent

Flip a service between internal (ClusterIP, reachable only inside the cluster) and external (a NodePort or LoadBalancer on the service). This changes the Service type only. It does not make a domain public: a domain keeps whatever login is on it, so a protected app still answers with a redirect to sign in. To open a domain to everyone use set_ingress_protection with mode none; to add a domain use create_ingress.

toolset: domains · idempotent

Expose or unexpose a single port on a service, for the case where a service carries several ports and only some should be reachable from outside. To expose the whole service use set_service_exposure.

toolset: deployments · idempotent

Change how an existing deployment is built, without recreating it.

Every field is optional and only what you pass is changed, so you can set one thing without restating the rest. Pass null to clear a value.

  • dockerfileTarget: the stage a multi-stage Dockerfile stops at, as docker build --target. Null builds the final stage, which is what a single-stage Dockerfile produces anyway. Use this to run several images out of one repo, such as a web stage and a worker stage, instead of maintaining a Dockerfile per process.
  • startCommand: on a dockerfile build this runs instead of the image’s CMD, like a command passed to docker run, and takes effect on save without a rebuild. On a railpack build it is baked in by the next build instead.
  • dockerfilePath, buildType: as at create time. Switching build type clears the settings that only make sense for the other one.
  • rootDirectory, installCommand, buildCommand, outputDirectory: Railpack-only overrides; null hands the decision back to detection.

Everything except startCommand applies on the next build, so follow up with rebuild_deployment if you want it live now.

toolset: deployments · idempotent

Configure the health probes Kubernetes runs against a deployment.

Every field is optional and merges into what is already stored, so turning a check on is one field. You do not have to restate the timings. Read the current values off get_deployment (the healthCheck*, livenessEnabled, readinessEnabled, startupEnabled fields).

The three probes do different jobs:

  • readiness keeps an unhealthy pod out of the load balancer without killing it. Turn this on first; it is what makes a rolling deploy zero-downtime.
  • liveness restarts a pod that fails. Powerful and dangerous: a liveness probe that is stricter than the app’s real startup time turns a slow boot into a crash loop.
  • startup suspends liveness until the app has come up, which is how you give a slow starter room without loosening liveness forever. startupFailureThreshold × healthCheckInterval is the grace period.

If the image’s Dockerfile declares its own HEALTHCHECK, that wins unless you set healthCheckOverride: true.

Applies immediately and rolls the pods.

toolset: deployments · idempotent

Change the Docker image of an image-source deployment (one created from an image reference, not built from a GitHub repo). Pods will roll to pull the new image. If the image lives in a private registry, add the registry’s credential to the project first with set_registry_credential; the pull secret is attached automatically whenever the image host matches. Only valid for non-GitHub deployments. For GitHub deployments use rebuild_deployment so the image is rebuilt from source. The backend rejects this on a GitHub-built deployment with a clear error.

toolset: deployments · idempotent

Override whether Kubernetes re-pulls the container image every time a pod starts.

You usually do not need this. By default the policy is derived from the tag: a tag that can move (latest, main, stable, a floating major like 17, or no tag at all) gets Always, and a pinned tag or digest gets IfNotPresent. Change the image and it re-derives.

Set it only to override that:

  • Always: re-pull on every pod start, so push-then-restart_deployment picks up a new build.
  • IfNotPresent: reuse the layer cached on the node. On a moving tag this means a restart will NOT show a new push.
  • null: clear the override and go back to deriving it from the tag.

An explicit value here survives an image change, which is the point: it is your call, not a guess.

Changing this rolls the pods on its own; no separate restart is needed.

toolset: deployments · idempotent

Set the Kubernetes update strategy for a deployment.

  • rollingUpdate: bring up new pods before draining old ones, with zero downtime.
  • recreate: tear down all pods first, then start new ones, with brief downtime. Required for ReadWriteOnce PVCs.
  • blueGreen: the new image runs beside the old one and takes traffic only once every pod is ready; if it never is, nothing moves.

A deployment with a PVC attached only accepts recreate. Every strategy waits for the new pods to be ready and rolls back if they never are.

toolset: deployments · destructive · idempotent

Update the volumes for a deployment. This replaces all existing volumes with the provided list. Supported volume types:

  • pvc: Persistent Volume Claim - persistent storage that survives pod restarts. Requires pvcName and optional storageSize (default: 1Gi). The PVC is automatically created in Kubernetes with the longhorn storage class.
  • hostPath: Mount a file or directory from the host node’s filesystem. Requires hostPath.
  • emptyDir: Temporary storage that is created when a pod is assigned to a node and deleted when the pod is removed.

To remove all volumes, pass an empty array.

toolset: domains · idempotent

Update an existing ingress configuration

toolset: domains · destructive · idempotent

Change the ports a service exposes, or the internal domain it answers on.

ports is a full replace of that service’s port list. A port you leave out is removed, so restate the ones you want to keep (read them off list_services). Pass domain: null to clear the internal domain. At least one of ports / domain is required.

To change whether a service is external use set_service_exposure, not this.

toolset: dangerous · destructive · idempotent

DANGEROUS: Delete a Postgres database. Apps using it lose it immediately. The database goes to a 30-day trash: list it with list_deleted_databases and bring it back with undelete_database, as long as it had a completed backup (recoverableUntil in the response says how long). The server refuses the call while deletion protection is on.

toolset: dangerous · destructive · idempotent

Revoke a deploy webhook token. Whatever CI is using it starts failing on its next run, so check lastUsedAt on list_deploy_webhook_tokens before revoking one you did not create.

toolset: dangerous · destructive · idempotent

DANGEROUS: Delete a deployment and all associated resources.

toolset: env · destructive · idempotent

Remove specific environment variables from a deployment by key name, leaving every other var alone. The deployment restarts.

Only the keys you name are touched, so this is safe to use for a targeted removal. It is filed here because deleting a var an app reads will break it. To change a value instead of removing it, use add_env_vars.

toolset: dangerous · destructive · idempotent

DANGEROUS: Delete an environment. This deletes its whole Kubernetes namespace, so every deployment, database, ingress and shared variable inside it goes with it. Databases in that environment are destroyed with their data.

List what is in it with list_deployments / list_databases and confirm with the user before calling, then pass the environment’s exact name as confirmName; the server refuses the call otherwise. This is permanent. The default production environment cannot be deleted, and neither can the last environment in a project.

toolset: dangerous · destructive · idempotent

DANGEROUS: Delete an ingress (remove public access via a domain). Provide either deploymentId or projectId.

toolset: dangerous · destructive · idempotent

DANGEROUS: Permanently delete a notification channel, along with every rule that routes to it. Alerts stop immediately and a webhook channel’s signing secret is lost. Requires admin on the scope that owns the channel: org admin for org-wide destinations, project admin for one an app owns.

toolset: dangerous · destructive · idempotent

DANGEROUS and PERMANENT: Delete a project and ALL its deployments, databases (with their data and backups), ingresses, jobs and environments. Nothing is recoverable afterwards.

Confirm with the user first, then pass the project’s exact name as confirmName; the server refuses the call otherwise.

toolset: dangerous · destructive · idempotent

DANGEROUS: Delete a service from a deployment.

toolset: dangerous · destructive · idempotent

DANGEROUS: Delete a template instance and ALL its associated resources (deployments, databases, ingresses).

toolset: dangerous · destructive · idempotent

DANGEROUS: Turn off deletion protection on a database so delete_database is allowed. Confirm with the user first. Turn it back on with set_database_protection.

toolset: dangerous · destructive

DANGEROUS: Restore to a checkpoint. Pass checkpointId for one database, or groupId to restore every database pinned together by a bulk create_checkpoint call.

mode “in_place” (the default) replaces the current data. Orchard checkpoints first and keeps the previous copy for 24h, so undo_database_restore can swap it back. mode “fork” restores into a new database and leaves the original untouched; name and environmentId only apply to a single checkpoint.

Only checkpoints with status “durable” can be restored. Returns the operation (an array of them for a group); poll each with get_database_operation.

toolset: dangerous · destructive

DANGEROUS: Restore a database to an earlier state. Pick at most one target: backupId (from list_database_backups), checkpointId (from list_checkpoints), or at (an ISO time inside the recovery window, or “latest”). With no target it restores the latest recoverable point.

mode “in_place” (the default) replaces the current data. Orchard takes a checkpoint first and keeps the previous copy stopped for 24h, so undo_database_restore can swap it back. mode “fork” restores into a new database and leaves the original untouched; pass name and environmentId to place it.

Check the window with get_database_recovery_window first. Returns the operation; poll it with get_database_operation (wait: true) until it succeeds or fails.

toolset: dangerous · destructive

DANGEROUS: Undo an in-place restore by swapping the database back to the copy Orchard kept from just before it. Works within 24h of the restore. Anything written since the restore is lost. Pass the restore operation id; returns the new operation, poll it with get_database_operation.

toolset: dangerous · destructive · idempotent

DANGEROUS: Upgrade a database to a newer Postgres major version (choices from list_postgres_versions). By default Orchard first rehearses the upgrade on a live copy; if that fails the database is left alone. Then it takes a checkpoint and upgrades in place with CNPG: Postgres is OFFLINE while pg_upgrade runs (the rehearsal reports roughly how long), and a failed upgrade is put back on the old version. Returns an operation; follow it with get_database_operation.

toolset: databases · destructive · idempotent

Cancel a database operation that is still pending or running. Any half-made copy is cleaned up and the original database is not touched. Once it reaches the cutting_over or finalizing phase it can no longer be cancelled.

toolset: databases

Take an instant named restore point. Take one before a migration, a bulk update or anything you might want to undo.

Pass databaseId for one database, or pin many at once with projectId, environmentId or databaseIds; a bulk call returns a groupId that restore_checkpoint can restore together. A checkpoint becomes restorable once its status is “durable”, usually within seconds. Checkpoints are kept for 30 days.

toolset: databases · sensitive

Create an extra login user on a database. access read can read every table (good for BI tools and analytics); write can also insert, update and delete, but cannot change the schema. Returns the password and a connection string once; it is not shown again. [sensitive]

toolset: databases · destructive · idempotent

Remove an extra login user from a database. Its open connections stop working.

toolset: core · read-only · idempotent

The one call to understand a database. Returns a health verdict (healthy, degraded, unprotected, down, hibernated or unknown) with the reasons behind it, instance readiness, the last restart and why, storage fill and WAL backlog, backups and the recovery window, the last restore test, checkpoints, protection settings, the connection pooler, recent operations and a tail of the Postgres log.

Start here for any database question before reaching for the narrower tools. Find a databaseId with find (kinds: [“database”]).

toolset: databases

Copy a database into a new one and leave the original untouched. This is the safe way to try a migration or a risky query on real data first: fork, point a test at the fork, and delete it when done.

at “now” (the default) copies the live database, “latest” uses the newest archived point, or pass an ISO time inside the recovery window. Pass checkpointId or backupId instead to fork from one of those. The new database shows status “restoring” and then “ready”. Returns the operation; poll it with get_database_operation (wait: true).

toolset: databases · read-only · idempotent

What a database is doing right now: every session with its user, application, client, state, wait event, transaction and query age and the query text, plus which sessions are blocked and by whom, and max_connections.

Use it for “the database is stuck”, lock waits, or running out of connections. It shows live query text, so it needs edit access.

toolset: databases · read-only · idempotent

Read a database operation (restore, fork, undelete or restore test): status (pending, running, succeeded, failed), phase, target, result and error.

Pass wait: true to long-poll for up to 25s while it is still running instead of polling in a tight loop.

toolset: databases · read-only · idempotent

Read a database’s PgBouncer connection pooler: whether it is enabled, its config (instances, poolMode, defaultPoolSize, maxClientConn), the host and port apps should connect to, and whether it is ready.

toolset: databases · read-only · idempotent

How far back a database can be restored: the earliest and latest recoverable times, whether WAL archiving is healthy, the backups and checkpoints inside the window, recent restore tests, operations in flight, and its protection settings.

Read this before restore_database or fork_database with an at time, so the time you pick is actually recoverable.

toolset: databases · read-only · idempotent

Read a database’s replication mode. async: standbys follow the primary and a failover can lose the last moments of writes. preferred: each commit waits for a standby while one is healthy, and keeps going without it. required: each commit waits for a standby, so no acknowledged write is ever lost, but writes stop if no standby is reachable.

toolset: databases · read-only · idempotent

Show which known Postgres vulnerabilities (CVEs from postgresql.org) affect a database’s running version, with CVSS score, component and the version that fixes each, plus end of life status. action says what to do: none, minor_update (use update_database_minor; minorUpdate.automatic says whether Orchard rolls it on its own, which only happens when an org admin opted the organization in, and minorUpdate.blocked explains why it can’t be applied in place), or major_upgrade (the major is unsupported or a fix only exists on a newer major; use upgrade_database).

toolset: databases · read-only · idempotent

Summarise Postgres security for every dedicated database in a project: running version, action (none, minor_update, major_upgrade, unknown), vulnerability count, highest CVSS score, end of life and the available minor update. autoUpdate says whether the organization opted in to automatic minor updates.

toolset: databases · read-only · idempotent

List restore points for a database, newest first. Each has an id, groupId, label, kind (manual, pre_deploy, pre_op, or ddl for ones taken automatically before a DROP), status (only “durable” can be restored), and for ddl checkpoints a detail of what was dropped and by whom.

toolset: databases · read-only · idempotent

List restores, forks, undeletes and restore tests that involved a database, newest first.

toolset: databases · read-only · idempotent

List past restore tests for a database, newest first, each with its verdict (passed, missing tables, row drift, reasons) and how long recovery took.

toolset: databases · read-only · idempotent

List the extra login users created on a database through Orchard (name and read or write access). The owner user is not listed.

toolset: databases · read-only · idempotent

List a project’s deleted databases still in the 30-day trash. recoverableUntil is null when the database never had a completed backup, which means it cannot be brought back. Restore one with undelete_database.

toolset: databases · read-only · idempotent

List the Postgres major versions new databases and upgrades can use, straight from the CNPG image catalog (so new majors appear without an Orchard release), with the minor each one rolls to, whether the Postgres project still supports it, its end of life date, and the default for new databases.

toolset: databases · idempotent

Turn a database’s PgBouncer connection pooler on or off, or change its config. Only the fields you pass change.

Apps only go through the pooler if they connect to its host and port (see get_database_pooler); the direct endpoint keeps working. Transaction mode packs the most clients into the fewest connections but breaks session state such as prepared statements, advisory locks and SET; use session mode if the app relies on those.

toolset: databases · idempotent

Change a database’s safety settings. Only the fields you pass change.

  • deletionProtection: true makes delete_database refuse. Turning it off is a separate tool, disable_database_deletion_protection.
  • ddlCheckpoints: take a checkpoint automatically before any DROP TABLE, DROP SCHEMA, DROP COLUMN and similar.
  • restoreTests: run scheduled restore tests against the latest backup.

toolset: databases · idempotent

Set the replication mode to async, preferred or required (see get_database_replication). preferred and required need at least 2 instances; scale_database first.

toolset: databases

Prove a database can actually be restored: restores its latest backup into a throwaway cluster, checks the tables and row counts against the live database, then deletes the copy. Returns the operation; poll it with get_database_operation and read result.verdict and result.recoveryMs.

toolset: databases

Bring a deleted database back from the trash, restored from its backups up to the moment it was deleted. It keeps its id and password but runs on a new cluster, so read get_database_connection afterwards and update DATABASE_URL on the apps that used it. Returns the operation; poll it with get_database_operation.

toolset: databases · idempotent

Move a database to the newest minor release of its Postgres major (the minorUpdate.to from get_database_security). CNPG restarts the instances one at a time, replicas first, so a database with replicas stays available and a single instance restarts once. Refused when the update also changes the OS image and a database uses a non-C collation.

toolset: deployments · destructive · idempotent

Cancel an in-progress build for a deployment

toolset: deployments · sensitive

Mint a token that lets an outside system trigger a deploy over HTTP, for CI that builds elsewhere and pushes to Orchard.

The holder POSTs to /apiv1/webhooks/deploy with Authorization: Bearer <token>. On an image-source deployment they may send { "image": "...", "tag": "..." } to roll a new image; on a GitHub-built deployment that is rejected. Without those fields the POST restarts the deployment and does not rebuild it.

The plaintext token is in this response and nowhere else. It is stored hashed, so hand it to the user now or it is gone. It inherits the creator’s project access and is revoked automatically if they lose it. [sensitive]

toolset: deployments

Create a new deployment from a Docker image in a project. This also creates an internal ClusterIP service targeting the specified port. If no port is specified, it defaults to 80. Make sure the port matches the port your container listens on.

toolset: deployments · open-world

Deploy an application from a GitHub repository using owner/repo shorthand. This will build the Docker image from the repo and deploy it. Before using this tool:

  • Call list_github_deploy_targets to confirm the caller’s GitHub account is linked AND that the owner you are about to deploy is one of the installed accounts/orgs
  • If not linked or the owner has no Orchard GitHub App installation, tell the user to fix that via the Orchard UI (/user/settings) before retrying
  • Ask the user about environment variables their app needs
  • Ask if the app needs a database (use create_database tool)
  • Ask if the app needs a public domain (use create_ingress tool after deployment)
  • If the repo needs additional services like Redis, inform the user
  • IMPORTANT: If no port is specified, the server will try to auto-detect the port from the Dockerfile’s EXPOSE directive. If the Dockerfile has no EXPOSE directive, it defaults to port 80. If you are unsure about the port, check the Dockerfile first using get_repo_contents or ask the user what port their app listens on.
  • If the Dockerfile copies files from the repo root (e.g. pnpm-workspace.yaml, package.json), set buildFromRoot to true
  • If the repo has no Dockerfile, call detect_repo_config first: it reports every deployable app in the repo and the framework, commands and output directory detected for each. Pass buildType “railpack” plus the rootDirectory of the app the user wants, and leave the command fields unset unless detection got them wrong.

toolset: deployments · open-world

Deploy an application by pasting a full GitHub repository URL. Use this when the user gives you a link (e.g. https://github.com/owner/repo or https://github.com/owner/repo/tree/branch) rather than an owner/repo pair. Accepted URL shapes:

  • https://github.com/<owner>/<repo>
  • https://github.com/<owner>/<repo>.git
  • https://github.com/<owner>/<repo>/tree/<branch>
  • https://github.com/<owner>/<repo>/blob/<branch>/<path>
  • [email protected]:<owner>/<repo>.git The branch is auto-derived from /tree/<branch> or /blob/<branch> segments when present; otherwise it falls back to the branch parameter (default: main). Before calling, you should still confirm with list_github_deploy_targets that the caller’s account is linked and the repo owner has the Orchard GitHub App installed. The other guidance from deploy_from_github (env vars, databases, ingress, port detection, buildFromRoot) applies here too.

toolset: deployments · idempotent

Disable auto-deploy for a deployment

toolset: deployments · idempotent · open-world

Enable auto-deploy for a deployment. When enabled, pushes to the configured branch automatically trigger a rebuild.

The GitHub App has to be installed on the repository first. Without it this call fails with a message naming the fix, because pushes never reach Orchard otherwise. Note that an App installed with “only select repositories” does not pick up a repository created after the install: it has to be added to the selection by hand.

Check with get_auto_deploy_status afterwards. If it reports deliverable: false, pushes will not build anything no matter what enabled says.

toolset: deployments · read-only · idempotent · open-world

Whether pushes to this deployment’s branch actually build anything.

enabled is what the user asked for. deliverable is what will happen: it is only true when the GitHub App is installed on the repo and this deployment is bound to that installation. When it is false, message says why and what to do.

Use this whenever auto-deploy looks like it is on but pushes are not producing builds. The usual cause is the App not being installed on that specific repository.

toolset: core · read-only · idempotent

Ask Orchard what this deployment has not been set up with yet: auto-deploy, a custom domain, explicit resource requests, notifications, a health check.

Returns a steps array of &#123; id, applicable, done &#125;. Act on the ones that are applicable and not done. Cheap, and the right follow-up after creating a deployment or when a user asks “what else do I need to do”. applicable: false means the step cannot apply here (no repo linked, no public port, compose-managed), not that it passed.

toolset: deployments · read-only · idempotent

List the deploy webhook tokens on a deployment: label, when it was created, when it was last used. The token values themselves are hashed and never readable after creation, so a lost one has to be replaced.

toolset: deployments · read-only · idempotent · open-world

List the GitHub accounts/orgs available for deploy_from_github. ALWAYS call this before deploy_from_github so the user can pick a target. Returns:

  • linked: whether the caller’s GitHub account is linked to Orchard (required for deploy_from_github)
  • username: the linked GitHub username (null if not linked)
  • installations: GitHub accounts/orgs where the Orchard GitHub App is installed AND the caller has access (personal account + orgs) If linked is false, tell the user to link their GitHub account at /user/settings in the Orchard UI. If installations is empty, tell the user to install the Orchard GitHub App on their personal account or org. The install URL can be fetched server-side; ask the user to visit /user/settings.

toolset: deployments · open-world

Rebuild a deployment from source (triggers a new build from the GitHub repo).

Read the build field on the response before doing anything else:

  • &#123; started: true, status: "building" &#125; means a build is running now.
  • &#123; started: false, status: "queued" &#125; means it was accepted but every build slot is busy, or this deployment is already building. It starts on its own. Do not call this again: a second call supersedes the first and gets you no closer to the front. Poll get_deployment for the build status instead.

Everything else on the response is the deployment as it stands right now, so when a build is queued the build fields still describe the previous build. That is expected, not a failed call.

toolset: deployments · idempotent

Rename a deployment.

Only the display name changes. The Kubernetes workload name, service DNS, generated .orchard URL and any ingress hosts keep pointing where they did, so nothing that talks to this app has to be updated.

toolset: deployments

Restart a deployment (rolling restart of all pods). Whether this re-pulls the image depends on the deployment’s pull policy. That policy is derived from the tag by default, so an app on a moving tag like :latest re-pulls and push-then-restart works. If someone pinned the policy to IfNotPresent, the node reuses its cached layer and a restart will not pick up a new push.

toolset: deployments

Requeue the Kubernetes applies that failed for this deployment, so a config change that saved but never reached the cluster gets another attempt.

Use it when get_deployment reports applyStatus: "failed" / a non-null applyError. It only touches work already marked failed, so the response’s retried: 0 means there was nothing stuck and the problem is elsewhere. It does not rebuild the image (rebuild_deployment) or bounce healthy pods (restart_deployment).

toolset: deployments

Rollback a deployment to a previous image version. Use get_image_history to see available versions.

toolset: deployments · idempotent

Set how many replicas a deployment runs.

replicas: 0 is the same thing as stop_deployment. It marks the deployment stopped and remembers the old count, so the next rebuild will not bring it back. Scaling to any positive number un-stops it. Prefer stop_deployment / start_deployment when the intent is “turn it off / back on”; they read clearly in the audit log and do not make you guess a count to restore.

toolset: deployments · idempotent

Bring a stopped deployment back online at its previous replica count (at least 1). The inverse of stop_deployment; a no-op on one that is already running.

Coming back re-checks quota, so a start can fail if the org filled up while the app was parked. Scale it down first in that case.

toolset: deployments · destructive · idempotent

Take a deployment offline. Pods are drained and it stays down until start_deployment. A rebuild deploys it at zero replicas.

The “turn it off” verb: it sets the deployment’s stopped flag and leaves the replica count alone, so start_deployment brings it back at the size it was. Nothing is destroyed: build, env vars, domains, volumes and data all stay. (scale_deployment(0) reaches the same state; this is the clearer way to ask for it.)

toolset: deployments · idempotent

Set how many replicas must stay available while Kubernetes drains a node.

Only meaningful above one replica: a budget equal to the replica count blocks voluntary evictions entirely and can wedge a node drain, so keep it below replicas.

toolset: deployments · idempotent · open-world

Point a deployment at a different GitHub repository or branch without recreating it.

Takes effect on the next build, so follow with rebuild_deployment to make it live. Auto-deploy survives only if the GitHub App is installed on the new repo. Otherwise it is switched off, silently, because pushes could never reach Orchard. Check get_auto_deploy_status afterwards.

toolset: deployments · idempotent

Pin a deployment to a node pool, or clear the pin so it schedules anywhere.

Pools carry taints, so an app that needs particular hardware has to be placed into the matching pool to land there at all. Pass nodePoolId: null to unpin. Changing this rolls the pods.

toolset: deployments · idempotent

Update CPU and memory requests for an existing deployment. The deployment will roll its pods to apply the new resources. The API enforces project, organization, and per-member resource quotas. If the new values exceed your remaining allowance the call returns an error and nothing changes. Pass null for either field to clear it and fall back to the project / org default.

toolset: env · idempotent

The default way to change shared variables. Adds or overwrites the keys you pass and leaves the rest of the environment’s shared set alone.

Deployments that reference a changed key via $&#123;&#123;shared.KEY&#125;&#125; are restarted; the rest are left running. Defining a var here does nothing on its own. Point a deployment at it with add_env_vars and the value $&#123;&#123;shared.KEY&#125;&#125;.

Related: delete_shared_env_vars to remove keys, set_shared_env_vars only when you mean to replace the whole set.

toolset: env

Create a new environment in a project, e.g. staging or preview.

Provisions a fresh namespace. Nothing is copied from production: the new environment starts with no deployments, no databases and no shared variables.

toolset: env · destructive · idempotent

Remove specific shared variables from an environment by key name, leaving the rest alone. Any deployment whose env references a removed key via $&#123;&#123;shared.KEY&#125;&#125; resolves it to an empty string and restarts, so check get_deployment.envVars for references before removing one.

toolset: env · read-only · idempotent

Read an environment’s shared variables: a pool of values that every deployment in the environment can reference, so something like an API key lives in one place instead of being pasted onto each app.

They are not injected automatically. A deployment opts in by setting one of its own env vars to $&#123;&#123;shared.KEY&#125;&#125; (via add_env_vars); the reference is expanded when the pod spec and build args are built. Referencing a secret shared var makes the referencing var secret too, so it still routes through the Kubernetes Secret.

Secrets come back here with a null value. They are write-only.

toolset: core · read-only · idempotent

List a project’s environments: production, staging, preview and whatever else it has.

Each environment is its own Kubernetes namespace with its own deployments, databases, ingresses and shared variables, so an environment id is what you pass to create_deployment / deploy_from_github to land an app somewhere other than production. Every project has at least one, marked isDefault.

toolset: env · idempotent

Rename an environment. The slug and namespace are frozen, so nothing that resolves by slug moves.

toolset: env · idempotent

Make an environment the project default: the one resources land in when a create call omits environmentId. Does not move anything that already exists.

toolset: env · destructive · idempotent

Replace an environment’s ENTIRE shared variable set with the list you pass. Anything you leave out is deleted, and any deployment referencing it via $&#123;&#123;shared.KEY&#125;&#125; resolves it to an empty string.

Use add_shared_env_vars to change a few, delete_shared_env_vars to remove a few. Secrets read back valueless, so pass value: null with secret: true to keep one through a replace.

Start a new agent session on a running Greenhouse machine: creates a git worktree for repo on a fresh branch and an agent chat in it. Pass agent to pick the coding agent: “opencode” (the default), or “acp:claude”, “acp:opencode”, “acp:fx”, “acp:codex” for agents driven over the Agent Client Protocol. When prompt is given it is sent as your first prompt (attributed to you, like prompt_sandbox_session) and the agent starts working right away. Requires guest access or higher.

Open a GitHub pull request for a session’s branch, using the caller’s own linked GitHub account (host or guest). Pushes the branch first, as the caller, when it has no upstream on origin or has unpushed commits. Fails with github_not_linked if the caller hasn’t linked GitHub. Commit the work first (the agent can when asked); uncommitted changes aren’t included.

read-only · idempotent

Get one Greenhouse machine: status, desired state, whether a change is still applying, runner, image, owner and your role on it. Org admins can read this for any machine in their org; everything inside the machine needs an invite.

read-only · idempotent

Read what a session changed: the list of changed files with line counts, and the unified diff of uncommitted work in its worktree (capped at 200KB, truncated says when). Pass file to diff a single file. The machine must be running.

read-only · idempotent

Read the latest messages of a session’s agent chat as plain text: your and your teammates’ prompts (with who sent them) and the agent’s replies. Tool calls and reasoning are left out.

read-only · idempotent

List the agent sessions on a Greenhouse machine. Each session is a git worktree on its own branch (orchard/<slug>) with an agent chat (opencode, Claude Code, fx or Codex), plus its agent, diffstat, ahead/behind, activity (idle, working, needs_input, done) and pull request.

read-only · idempotent

List the Greenhouse machines (sandboxes) you own or that were shared with you, with their status, runner and your role on each (owner = host, collaborator = guest, viewer = read-only guest, admin = org admin with lifecycle only). Pass organizationId to also see every machine in an org you administer; on machines where your role is admin you can start, stop and delete them, but sessions, files, transcripts, terminals and previews stay closed to you unless the host invites you. The result also says how many machines you may own and which runners are available.

Send a prompt to the agent in a session. The prompt is recorded as yours (it shows your avatar in the shared transcript) and the agent runs with the host’s credentials, so this needs guest access or higher. Returns as soon as the agent accepts it; read progress with get_sandbox_session_transcript and list_sandbox_sessions (activity).

idempotent

Start a stopped Greenhouse machine. Guests, the host and org admins can start it. Returns immediately with status “starting”; poll get_sandbox until it is “running” before creating sessions or prompting.

destructive · idempotent

Stop a Greenhouse machine. Its disk is kept and sessions resume on the next start, but running agents, terminals and dev servers are killed. Host or org admin only.

toolset: jobs · destructive · idempotent

Cancel an in-progress job run: the active step’s Kubernetes Job is deleted and remaining steps are skipped.

toolset: jobs

Create a job in a project: an ordered pipeline of steps that runs on a cron schedule and/or on demand. Steps run in the project’s namespace and count toward its quota. A failing step stops the pipeline. Cron is 5-field, interpreted in UTC.

toolset: dangerous · destructive · idempotent

Delete a job, its schedule, and its entire run history. Any active run is stopped. This cannot be undone.

toolset: jobs · read-only · idempotent

Get a job’s full definition including its ordered steps.

toolset: jobs · read-only · idempotent

Get a run’s detail: status, trigger, timing, and each step’s status, exit code, and failure reason.

toolset: jobs · read-only · idempotent

Get the logs of one step of a job run. Historical steps return captured logs; a currently running step returns a live tail. Capped at the last 20,000 characters.

toolset: jobs · read-only · idempotent

List a job’s run history, newest first, with per-run status and step summaries. Paginate with the returned nextCursor.

toolset: jobs · read-only · idempotent

List all jobs (scheduled/on-demand multi-step pipelines running as Kubernetes Jobs) in an organization, with schedule, last run status, and next run time.

toolset: jobs · destructive · idempotent

Replace a job’s entire ordered step list. Running runs keep their snapshot; future runs use the new steps.

toolset: jobs

Trigger a job run now. Fails with a conflict if a run is already active and the job’s concurrency policy is forbid (pass allowConcurrent to override). Returns the new run.

toolset: jobs · idempotent

Update a job’s name, description, schedule, concurrency policy, or enabled state (enabled=false pauses the schedule). To change steps, use replace_job_steps. Only provided fields change.

toolset: notifications · sensitive

Create a notification destination. This only says where messages go; create a notification rule afterwards to say what it should receive, otherwise the channel stays silent. For discord/slack/webhook, pass the webhook URL in “url”. For email, pass “recipients” (org members for an org-wide destination, the project’s own people for a scoped one). For webhook channels the response includes a one-time signing secret. Surface it to the user. It cannot be retrieved again. A destination belongs to a scope: org-wide (the default) needs org admin, and a project or resource scope needs admin on the owning project, which is how one app gets its own webhook without an org admin. Only rules at or below the owning scope can route to it. [sensitive]

toolset: notifications

Route events to a channel at a given scope. Rules add up as you go outwards, so a deployment rule fires alongside the project and org rules that also match. Use mode=“mute” to silence a specific channel for this scope: a mute at a narrower scope beats a deliver at a broader one, which is how you quieten one noisy deployment without touching the org-wide rule. Events must be possible at the scope (a database cannot emit deploy events). Org-scope rules need org admin; narrower scopes need admin on the owning project.

toolset: dangerous · destructive · idempotent

Delete a notification rule. The channel it pointed at is left alone.

toolset: notifications · read-only · idempotent

List notification destinations (Discord, Slack, email, or generic webhook). A channel is only a destination: what it receives is set by notification rules. Without a scope this is every destination in the org, with health, rule count and last delivery status, and needs org admin. With a scope it is what that project or resource may route to (its own destinations plus the ones it inherits), and needs only org membership.

toolset: notifications · read-only · idempotent

List recent delivery attempts for a notification channel, including attempt count, HTTP status, errors, when the next retry is due, and whether messages were coalesced into a digest. This is the place to look when a channel isn’t receiving alerts. Requires admin on the scope that owns the channel: org admin for org-wide destinations, project admin for one an app owns.

toolset: notifications · read-only · idempotent

List the notification rules that route events to channels. Pass a scope to see everything that applies there, including rules inherited from the project and the organization (each is flagged with “inherited”). Omit the scope to list every rule in the org.

toolset: notifications · open-world

Re-send everything a channel’s rules would have matched over the last N hours. Use this after fixing a webhook that was down: the events were stored even though delivery failed. Only events the channel’s own rules match are replayed. Requires admin on the scope that owns the channel: org admin for org-wide destinations, project admin for one an app owns.

toolset: notifications · open-world

Send a test notification through a channel to check that it works. Requires admin on the scope that owns the channel: org admin for org-wide destinations, project admin for one an app owns.

toolset: notifications · idempotent

Update a notification destination’s name, webhook URL, email recipients, or enabled state. Re-enabling a channel also clears its failure counter, so use this after fixing a broken webhook. Only provided fields change; the channel type cannot be changed. Requires admin on the scope that owns the channel: org admin for org-wide destinations, project admin for one an app owns.

toolset: notifications · idempotent

Change a rule’s events, mode, or enabled state. The scope and channel are fixed at creation; delete and recreate to move a rule.

toolset: core · read-only · idempotent

Call this first for any “what is wrong with this app” or “is it healthy” question. One compact answer that composes everything Orchard knows about a deployment:

  • health: what is wrong right now (crash loops, out of memory, stuck rollouts, failed builds), each with a title and a hint
  • rollout and the latest deploy verdict (“v7: responses 38% slower (p95 180 → 248 ms)”)
  • findings: plain sentences that tie a symptom to its cause (“Errors went from 0.2% to 4.1% at 14:02, two minutes after v7 went live.”), each with a link to that moment
  • changes in the last 24h (deploys, config, evictions, node events)
  • resources: usage against limits, CPU throttling, a memory leak forecast and a right-sizing suggestion
  • http: request rate, error %, p95 and the worst routes
  • security: worst CVE and attack attempts; topErrors: the most frequent error groups
  • links: where to send a human

Parts that could not be measured are listed in unavailable instead of failing the call. Follow up with search_logs, get_request_stats or get_changes for detail.

toolset: deployments · read-only · idempotent

The metric alert rules that apply to an app and whether each is ok, pending, firing or recovering, with its current value.

toolset: deployments · read-only · idempotent

What looks wrong with the app right now, ranked: out-of-memory kills, crash loops, failed rollouts, failed builds, firing alerts and error spikes.

toolset: deployments · read-only · idempotent

Attack attempts against an app over a window, from its access logs: scanners, injection payloads, password guessing and floods, counted over time, with the top sources and sample requests. IPs are masked to /24 for viewers who cannot edit the project.

toolset: deployments · read-only · idempotent

Recent builds with queue wait, duration and where the time went (clone, build, push, apply).

toolset: deployments · read-only · idempotent

Everything that changed around a deployment in a window, oldest first: deploys and rollbacks with their version, config, env and resource edits with who made them, failed builds, evictions, failed scheduling, failing probes and node cordons or pressure. The same markers the dashboard draws on every chart.

toolset: deployments · read-only · idempotent

How one release changed the app: the 15 minutes after it settled against the 15 minutes before it went live (p95, errors, restarts, memory, new error groups), with a one-line summary. Only calls a change a regression when it beats both a relative and an absolute floor. pending until 15 minutes after the rollout settles.

toolset: logs · read-only · idempotent

The app’s log lines around one moment: what happened just before and after a log line or a request. Oldest first. Leave pod out to read every replica.

toolset: core · read-only · idempotent

A link a human can open to see the exact moment you are talking about: the Observe dashboard with a 30 minute window around at, the crosshair on it and the panel scrolled into view and highlighted. Hand this to the user alongside any finding.

toolset: deployments · read-only · idempotent

Restarts by reason, waiting containers by reason and pods not ready, over time, from kube-state-metrics.

toolset: logs · read-only · idempotent

Request data from the ingress access logs: routes (per host and route with ids collapsed: rate, error %, p50/p95/p99), slowest (the slowest individual requests), recent (the newest requests) or clients (top client IPs and user agents). Needs the log store; answers 503 without one.

toolset: deployments · read-only · idempotent

A CPU and memory suggestion from up to 14 days of real usage: memory from the daily peaks plus 15%, the CPU limit from p95 and p99, raised when the app is throttled, never lowered right after a crash. Values are Orchard’s own numbers (the CPU limit and the memory limit). To apply one, call update_deployment_resources with both cpuRequestMilli and memoryRequestBytes; leaving one out resets it to the organization default.

toolset: deployments · read-only · idempotent

The app’s activity feed, newest first: audit events, builds, releases, pod transitions and new errors. Pass nextCursor back as cursor for older entries.

toolset: deployments · read-only · idempotent

How full each of the app’s persistent volumes is right now.

toolset: logs · read-only · idempotent

Search an app’s stored logs (every replica, past pods included, up to the retention window) with typed filters. Returns plain text lines, newest first: time pod LEVEL message. source says whether the answer came from the log store or a live read of the running pods.

Pass the returned cursor to get the next older page. Output is capped near 40 KB; truncated: true means there is more.

toolset: logs · read-only · idempotent

Snapshot the deployment’s current resource pressure. Combines live aggregate CPU/memory usage with the configured per-pod requests and replica count to compute a usage ratio for each axis. Returns a per-deployment summary: cpu/memory current usage, request × replicas capacity, ratio, and a “near limit” flag (≥85%). Use this before suggesting scale-ups, or to confirm an unhealthy / OOM-looking deployment is actually starved.

toolset: deployments · read-only · idempotent · open-world

Work out how a GitHub repository should be built, before deploying it.

Returns the build type Orchard would pick, plus, for repos with no Dockerfile, an “apps” array describing every deployable app found: its directory, framework, install/build/start commands and output directory. An app with an outputDirectory is a static site. “workspace” reports whether the repo is a pnpm/npm/yarn workspace.

Use this to answer “can I deploy this repo” and “which app in this monorepo did the user mean” before calling deploy_from_github. Everything it returns is a suggestion the deploy call can override.

toolset: logs · destructive · sensitive

Run a one-shot command inside a running pod’s container and return stdout/stderr. Equivalent to kubectl exec. Use this to:

  • Inspect files on disk (e.g. ls /data, cat /app/config.json)
  • Run health checks or quick diagnostics (e.g. curl -sv localhost:3000/health)
  • Check installed binaries or env (env, which node, node -v)
  • Tail a single file (tail -n 50 /var/log/app.log)

The command arg can be a string (executed via /bin/sh -c) or a string array (exec’d directly with no shell, preferred when arguments contain special chars). Pass deploymentId and the newest ready pod of that deployment is picked for you, which survives pod names changing on every restart. Pass podName and namespace (from list_pods) to target one pod exactly. If container is omitted, the first container in the pod spec is used. Not for long-running interactive sessions. The call times out (default 60s, max 5min). stdout and stderr are capped at the last 20,000 characters each.

Needs an exec-scoped session: connect with the mcp:exec scope or an orch_ token with exec scope. [sensitive]

toolset: core · read-only · idempotent

Turn a name into a UUID. Start here whenever the user names something (“restart hackatime”, “the leaf db”) instead of walking list_organizations → list_projects → list_deployments.

Searches organizations, projects, deployments and databases at once and returns compact matches with the ids every other tool wants. Matching is case-insensitive substring over names, slugs, GitHub repos and ingress hosts. Call it with no query to get an inventory of everything the user can see.

toolset: core · read-only · idempotent

Who changed what, and when. Pass a deploymentId for one app’s history, or an organizationId for everything in the org (org admins only).

This is how you answer “when did this break” and “who turned that off”. Each entry records the actor, a timestamp, the action (deployment.env.updated, deployment.scaled, deployment.stopped, environment.sharedvars.updated, …) and a metadata object that usually carries the [before, after] of whatever moved. Paginated: feed nextCursor back as cursor for the next page.

toolset: logs · read-only · idempotent

BuildKit output from the deployment’s most recent build, plus buildStatus and the buildError summary if it failed.

Returns the last tailLines lines by default, because a build that failed failed at the end and the transcript of a large repo runs to hundreds of KB. Read buildError first. It is usually the whole answer. Raise tailLines, or pass full: true, only when you actually need earlier stages.

For the running app’s output use get_deployment_logs.

toolset: core · read-only · idempotent

Get the currently authenticated user’s profile information

toolset: databases · read-only · idempotent

Get database details AND live cluster health. The password is never included: connection strings come back with it masked as ****. Call get_database_connection when you actually need credentials.

Returns host, port, user and database name plus a liveStatus object with real-time health from Kubernetes:

  • ready: whether enough instances report ready
  • phase: CNPG cluster phase
  • replicas / readyReplicas: instance counts
  • restartCount: total postgres container restarts across pods (HIGH NUMBERS = INSTABILITY)
  • message: current problem reason if any (e.g. “OOMKilled”, “CrashLoopBackOff”)
  • lastTerminationReason: last termination reason of the postgres container (e.g. “OOMKilled”, “Error”). Present even when the container is currently running. This is how you detect intermittent crashes.
  • lastTerminationExitCode: exit code from the last termination (137 = OOMKill, 139 = segfault, etc.)
  • lastTerminationAt: timestamp of last termination
  • size, connections: only present when reachable

To diagnose an unhealthy database, check liveStatus.message, liveStatus.lastTerminationReason, and liveStatus.restartCount together. status: "ready" at the top level reflects only the provisioning state. It can say “ready” while the pod is actively OOM-cycling.

toolset: databases · read-only · idempotent

Fetch a time-series of CPU and memory usage for a database pod from the metrics backend. Useful for confirming OOM/restart suspicions (memory climbing to the limit before a kill), sizing memory/CPU requests, and answering “is this near its limit?”.

The result includes datapoints sampled at step ms intervals between start and end (both unix-ms). Defaults to the last hour at 30s resolution.

To diagnose an OOMKill, look for memory rising to the request/limit ceiling right before liveStatus.lastTerminationAt (from get_database). If memory plateaus near the limit, raise it with update_database_resources.

toolset: core · read-only · idempotent

Get deployment details: status, image, replicas, env var names, services, ingresses, volumes, health check, build config, placement and recent image history.

The build log is omitted here because it is often megabytes. Read it with get_build_logs. Env var values are omitted too; read them with get_env_vars. Runtime logs are get_deployment_logs.

toolset: logs · read-only · idempotent

Request rate, average and max latency, and 5xx rate for a deployment, as served through its ingress. Latency is the load balancer’s average and max, not a percentile.

Answers “is it actually serving traffic”, “did latency regress after that deploy”, “how many 5xx”. Defaults to the last hour at 30s resolution. Returns empty series when nothing fronts the deployment. Check get_deployment.ingresses first if that surprises you.

toolset: logs · read-only · idempotent

Read an app’s recent runtime logs as plain text lines, newest first, across every replica (the last 24 hours from the log store when there is one, otherwise a live read of the running pods). Start with diagnose_deployment; for a time window, more filters or paging use search_logs, which this calls with simpler inputs.

level keeps only that level and search keeps lines containing every word. Output is capped near 40 KB; pass the returned cursor to search_logs for older lines.

toolset: logs · read-only · idempotent

Fetch a time-series of CPU and memory usage for a deployment from the metrics backend. Useful for diagnosing performance issues, sizing resource requests, and answering “is this near its limits?”.

The result includes datapoints sampled at step ms intervals between start and end (both unix-ms). Defaults to the last hour at 30s resolution.

Each series datapoint includes pod-level CPU (millicores) and memory (bytes). To get aggregate “is it near its limit” pressure, compare get_deployment.totalCpuUsage / (cpuRequestMilli × replicas) and the memory equivalent.

toolset: deployments · read-only · idempotent

Get all volumes attached to a deployment, plus the deploy strategy that volumes drive. Volumes are returned with their full record (id, name, type, mountPath, pvcName, storageSize, hostPath, readOnly). The response also surfaces deployStrategy and a pvcCount so callers can sanity-check that PVCs they expected are actually attached. A 0 PVC count on what should be a stateful deployment usually means the last volumes update silently dropped a row (e.g. type=pvc without pvcName).

toolset: env · read-only · idempotent

Get the current environment variables for a deployment.

Secret vars come back with secret: true and a null value. The value is write-only and never readable. To change one, use add_env_vars; you do not need to read it first.

toolset: core · read-only · idempotent · open-world

Check if the user’s GitHub account is linked to Orchard. Required before deploying from GitHub repos.

toolset: deployments · read-only · idempotent

Get the image version history for a deployment (for rollback purposes)

toolset: domains · read-only · idempotent

Get ingress details

toolset: logs · read-only · idempotent

Get the captured logs a killed container printed before it died (last ~500 lines, retained 24h). Works even after the pod was deleted. Use list_killed_containers first to get the entryId.

toolset: logs · read-only · idempotent

Get detailed information about a specific pod including status, IP, node, and restart count

toolset: logs · read-only · idempotent

Get runtime logs from a specific pod. Use list_pods first to get pod names. Pass previous=true to read the logs of the prior (terminated) container instance after a crash/OOM restart.

toolset: core · read-only · idempotent

Get project details including deployments, databases, and ingresses

toolset: deployments · read-only · idempotent · open-world

Get branches for a GitHub repository

toolset: deployments · read-only · idempotent · open-world

Get the file/directory listing of a GitHub repository. Useful to analyze what the app needs.

toolset: deployments · read-only · idempotent · open-world

Find Dockerfiles in a GitHub repository. Useful to determine if a repo can be deployed and which Dockerfile to use.

toolset: core · read-only · idempotent

How much CPU and memory the caller can still hand out in an organization.

Check this before sizing anything. create_deployment, update_deployment_resources, scale_deployment, scale_database and start_deployment are all quota-checked server-side and simply fail when the numbers do not fit; this is the only way to know the ceiling in advance instead of guessing and retrying.

effectiveLimit is the number you want: the most that can go on a single deployment right now, already reduced to min(what this member has left, what the org has left). A null means unlimited on that axis. allowance / usage / orgCap show the working.

Units match the resource tools: cpuMilli in millicores, memoryBytes in bytes.

toolset: templates · read-only · idempotent

Get a template by ID, including its full YAML definition and parameter schema

toolset: templates · read-only · idempotent

Get details of a deployed template instance, including all created resources

toolset: templates · read-only · idempotent

Get the full YAML format guide for creating Leaf templates, including all resource types, parameter types, interpolation syntax, and a complete example. Also published as the orchard://docs/template-yaml-guide resource.

toolset: databases · read-only · idempotent

List Postgres databases. Pass a projectId for one project’s databases, or nothing at all to get every database the user can see (optionally narrowed to one organization). Passwords are never included; use get_database_connection for credentials.

toolset: logs · read-only · idempotent

List grouped application errors for a deployment, parsed from its logs and persisted across redeploys. Each group carries a stable fingerprint, occurrence count, triage status (unresolved/resolved/ignored), assignee, and deploy provenance: the commit it was first seen after, that commit message, the branch, and who deployed it. Use this to find what is broken, whether it is already triaged, and which release introduced it.

toolset: core · read-only · idempotent

List deployments. Pass a projectId for one project’s deployments, or nothing at all to get every deployment the user can see (optionally narrowed to one organization).

Use find instead when you know the app by name and want its UUID.

toolset: deployments · read-only · idempotent · open-world

Autocomplete source for deploy_from_github. Lists repos that are BOTH (a) covered by an Orchard GitHub App installation the user has access to AND (b) accessible to the user’s own GitHub account, which is the intersection. These are safe to suggest because the deploy will succeed for them. The user should never be shown repos they cannot access on GitHub.

toolset: domains · read-only · idempotent

List all ingresses (public domains/routes) for a deployment

toolset: logs · read-only · idempotent

List recently killed containers for a deployment (last 24h): pod, container, termination reason (e.g. OOMKilled), exit code, and when it died. Their pre-death logs are captured even if the pod no longer exists. Pass an entryId to get_killed_container_logs to read them. Use this first when diagnosing crashes, OOMs, or restart loops.

toolset: core · read-only · idempotent

List the node pools a deployment can be pinned to, for update_deployment_placement or create_deployment’s nodePoolId.

Only pools an administrator marked user-selectable show up. On an instance that has not enabled userspace scheduling the call 404s, which just means placement is not a knob here. Schedule anywhere and move on.

toolset: core · read-only · idempotent

List all organizations the authenticated user belongs to

toolset: logs · read-only · idempotent

List all running pods for a deployment. The response includes the namespace which you should pass to get_pod_logs.

toolset: core · read-only · idempotent

List projects. With no arguments this returns every project the user can see across all their organizations, so you do not need to walk list_organizations first. Pass an organizationId only to narrow it.

toolset: domains · read-only · idempotent

List services for a deployment (internal networking, load balancers, etc.)

toolset: templates · read-only · idempotent

List all template instances (deployed templates) in a project

toolset: templates · read-only · idempotent

List all available templates (both built-in and custom)

toolset: logs · idempotent

Set the triage status of an error group, or assign it to a user. Status must be unresolved, resolved, or ignored. Resolving records who resolved it; if the error fires again after being resolved it automatically reopens. Get the fingerprint from list_deployment_errors.

toolset: domains · read-only · idempotent · open-world

Validate that a domain’s DNS is correctly pointed to the Orchard cluster. Run this before creating an ingress.

toolset: databases · destructive · idempotent

Turn off automated backups for a database. This also stops WAL archiving, so point-in-time recovery ends at this moment until a schedule is set again. Backups already taken are kept.

toolset: databases

Create a new Postgres database in a project. Returns the database record with the password masked. To wire it into an app, call get_database_connection and pass its connectionString to add_env_vars as DATABASE_URL with secret: true, so the credential never sits in a readable env var.

Optionally, pass restoreFromUrl to seed the new database from an existing one. The cluster will run pg_dump/pg_restore from the source URL during initdb. The URL must be reachable from the cluster and use the postgres:// or postgresql:// scheme.

Pass environmentId to put the database in that environment, which gives it that environment’s own namespace. Without it the database goes into the project’s default environment.

toolset: databases · open-world

Trigger a new backup of a database. Runs asynchronously. Poll list_database_backups to check status. Requires the database to be on a CNPG cluster with backups configured.

toolset: core

Create a new project in an organization. A project groups deployments, databases, and networking.

toolset: templates

Deploy a template to a project. This creates all the resources defined in the template (databases, deployments, ingresses) with the provided parameter values.

Before using this tool:

  1. Use list_templates to find available templates
  2. Use get_template to see the required parameters
  3. Provide all required parameters as a JSON object

The template engine will validate parameters and create resources in order, wiring them together automatically (e.g. DATABASE_URL is set on the deployment from the created database).

toolset: databases · idempotent

Stop exposing a database publicly. Clients connected via the public endpoint will be disconnected. The internal cluster connection still works.

toolset: databases · idempotent

Expose a database publicly on a shared organization IP with a unique port and TLS via Let’s Encrypt. Returns the public host, port, and connection string.

toolset: databases · idempotent

Expand the storage volume of a CNPG database. Storage can ONLY grow, never shrink. Requests smaller than the current size are rejected. Expansion happens online: the cluster spec and every data volume are resized directly, so it works even while the database is crashlooping on a full disk or stopped; the filesystem grows within a couple of minutes and CNPG boots the instance once headroom exists. Re-requesting the current size is allowed and re-syncs any volume that lags behind the cluster spec. Maximum size is 200Gi. IMPORTANT: if the disk filled because WAL archiving is failing, expansion only buys time. Postgres cannot recycle WAL while archiving fails, so the volume WILL fill again. The response includes a “warning” field when the cluster’s ContinuousArchiving condition is failing; if present, surface it to the user and treat fixing the archiving config as the real remediation.

toolset: databases · read-only · idempotent

Read the current automated backup schedule (cron expression) for a database, or null if none is configured.

toolset: databases · read-only · idempotent · sensitive

Reveal a database’s credentials: host, port, user, password, database name, the in-cluster connectionString and, when public access is on, publicConnectionString.

This is the only tool that returns the password, and every call is recorded in the audit log as database.credentials.revealed. Prefer piping connectionString straight into add_env_vars (secret: true) over echoing it back to the user. Requires edit access on the project. [sensitive]

toolset: databases · read-only · idempotent

Instance-wide limits for managed databases, currently just maxReplicas: the largest number of Postgres instances a single cluster may run on this Orchard instance. Self-hosters can change it, so read it rather than assuming the default of 5.

toolset: databases · read-only · idempotent

The slowest queries on a database, from pg_stat_statements: normalised query text, call count, total and mean execution time, rows.

The first stop for “the database is slow”. It tells you which statement is actually spending the time. Requires the pg_stat_statements extension; install it with install_database_extension (addToPreload: true, which needs a restart) if the call comes back empty. Cached for 15s server-side, so polling it in a tight loop tells you nothing new.

toolset: databases · read-only · idempotent

Read the configured Postgres parameters for a database (max_connections, shared_buffers, work_mem, statement_timeout, synchronous_commit, etc.).

parameters contains ONLY what the user has explicitly set. A key that is absent is sized automatically from the database’s memory limit, so an absent shared_buffers is not “unset”, it is managed. advisories lists settings that were accepted but look dangerous at the current memory limit; check it when diagnosing an OOMKilled database.

toolset: databases · idempotent

Install a Postgres extension on a CNPG database. Some extensions (like pg_stat_statements) require addToPreload=true, which adds them to shared_preload_libraries and triggers a database restart.

toolset: databases · read-only · idempotent

List all backups for a database. Each backup has an id, label, type, status, sizeBytes, and timestamps.

toolset: databases · read-only · idempotent

List Postgres extensions available on the database and which are currently installed. Also returns the current shared_preload_libraries.

toolset: databases · idempotent

Rename a database. This is the Orchard display name only. The Postgres database name, cluster name, credentials and connection endpoints are unchanged, so nothing connected to it needs updating.

toolset: databases · destructive · idempotent

Zero the pg_stat_statements counters so the next get_database_query_stats measures only what happens from now on. Use it to isolate the cost of one workload instead of reading lifetime totals.

toolset: databases

Restart a database cluster. Drops every open connection, so apps talking to it see errors until they reconnect. Use it to apply a setting that needs a restart, or to clear a wedged instance.

toolset: databases · idempotent

Change how many Postgres instances a database cluster runs: 1 primary plus (replicas - 1) read replicas. The replicas are streaming hot standbys: they serve reads a few milliseconds behind the primary AND act as failover targets, so this buys read scaling and high availability at once. It does not buy write throughput, which is still one primary. Each instance is a full pod with its own volume, so scaling from 1 to 3 triples the cluster’s CPU and memory usage; the API charges the difference against the organization cap and the project owner’s member allowance and returns an error if it does not fit. Scaling down is always permitted. Scaling up is not instant. A new replica has to clone the primary before it reports ready. Reads that must never hit stale data should keep using the “rw” endpoint. See get_database for the rw/ro/r endpoints.

toolset: databases · idempotent

Set or replace the automated backup schedule for a database, using a standard 5-field cron expression in UTC. Common values:

  • “0 * * * *” hourly
  • “0 */6 * * *” every 6 hours
  • “0 2 * * *” daily at 02:00 UTC
  • “0 2 * * 0” weekly Sunday 02:00 UTC

toolset: databases · idempotent

Bring a stopped database back up on its existing volume. It is not immediately connectable. Postgres has to recover and report ready, so poll get_database and watch liveStatus.ready.

toolset: databases · destructive · idempotent

Hibernate a database: the Postgres instances shut down, the volume and all its data stay. Anything connected to it starts failing immediately.

Use it to park a database you are not using without losing it. delete_database is the one that destroys data. CNPG-backed databases only. Bring it back with start_database.

toolset: databases · destructive · idempotent

DROP a Postgres extension from a database. Objects that depend on it will also be dropped. Optionally remove it from shared_preload_libraries.

toolset: databases · idempotent

Update CPU and memory requests for an existing database. The database pod will restart briefly to apply the new resources. The API enforces project, organization, and per-member resource quotas. If the new values exceed your remaining allowance the call returns an error and nothing changes. Pass null for either field to clear it and fall back to the default.

toolset: databases · destructive · idempotent

Update Postgres parameters on a database. Some parameters (max_connections, shared_buffers) require a brief database restart to take effect. The API applies them and rolls the pod automatically. Pass values as strings (e.g. “256MB”, “200”, “off”). Use get_database_settings first to see current values and supported keys.

The map REPLACES the set of user-set parameters, so omitting a key hands it back to automatic sizing rather than leaving it alone. Send the full map you want.

Values are applied exactly as given and are never clamped, but a dangerous one comes back in advisories. In particular, do not set shared_buffers anywhere near the memory limit: Postgres reserves it up front, and a base backup then has nowhere to run and OOMKills the database. Leaving shared_buffers out is usually the right answer.

toolset: core · idempotent

Update mutable fields on an existing project. Use this to rename a project, change its description, or update its repository URL / icon / background image. Only the fields you pass are changed. Leave the rest undefined to keep them as-is. The project’s slug (URL path) is not affected by a rename.

toolset: deployments · read-only · idempotent

Is the deployment live, and if not, why? One call that answers the question every deploy ends with.

Returns phase (queued, building, deploying, live, build_failed, crashing, unhealthy, stopped), terminal, releaseId, url, a build block (status, step, error, logTail) and a pods block (desired, ready, failing pods with reason, exit code and log tail), plus a plain-language hint.

Pass wait: true to long-poll until the rollout reaches a terminal phase or timeout seconds pass (max 120). Pass the releaseId returned by restart/rebuild/rollback as release so the wait cannot be satisfied by the old pods. Prefer this over polling get_deployment.

toolset: deployments · read-only · idempotent

Build history for a deployment, newest first: one entry per build with status, trigger, commit, timings and the failure summary. Use it to answer “when did the build start failing” or to pick a run for build logs.

toolset: deployments · read-only · idempotent

Release history for a deployment, newest first: what image each release ran, when it went out and who or what triggered it. A release id from here can be passed to get_deployment_rollout as release.

toolset: deployments

Roll a deployment back to the release before the current one, without having to look up an image history id. Returns the new releaseId; follow with get_deployment_rollout (wait: true, release: <releaseId>) to confirm it came up. Use rollback_deployment to pick a specific older version.