Code mode for agents
Code mode lets an agent reach every Orchard API operation without loading a tool definition for each one. Instead, the agent searches a spec, reads the contract for the operation it needs, and calls it by ID, either through the CLI or through the compact MCP server. Use code mode when a task needs an operation that the full MCP server does not cover, or when describing every operation to a model would use more context than the task has.
| Your agent has | Use |
|---|---|
| A shell, such as Claude Code, Codex, Cursor, or CI | The CLI: orchard api search, describe, and calls by operationId. |
| No shell, such as claude.ai or another chat app | The compact MCP server at /compact. |
Neither option runs model-written code on Orchard.
The agent spec
Section titled “The agent spec”Both options read the agent spec, a trimmed copy of the OpenAPI contract. For each operation, the spec has the operationId, parameters, request and response schemas, required scope, and two flags:
x-orchard-destructivemarks deletes, whole-list replacements, and other operations that remove or overwrite state.x-orchard-sensitivemarks responses that contain a secret.
Both spec files are public and served with an ETag:
GET https://orchard.example.com/apiv1/agent-spec.jsonGET https://orchard.example.com/apiv1/openapi.jsonagent-spec.json leaves out admin, setup, SCIM, SSO, and sign-in routes. openapi.json is the complete document.
Operation IDs come from the route: the path words, then a verb.
| Route | operationId |
|---|---|
GET /deployments |
deployments_list |
GET /deployments/:id |
deployments_get |
GET /deployments/:id/rollout |
deployments_rollout_get |
POST /deployments/:id/restart |
deployments_restart |
PUT /deployments/:id/env |
deployments_env_set |
GET /databases/:id/connection |
databases_connection_get |
Call the API from a shell
Section titled “Call the API from a shell”The CLI caches the spec for each instance in ~/.orchard/agent-spec.<host>.json and revalidates it at most once an hour. To cache it somewhere else, set ORCHARD_SPEC_CACHE_DIR. Search works offline after the first fetch.
orchard api search "deployment logs"orchard api describe deployments_rollout_getorchard api deployments_rollout_get -p id=$DEPLOYMENT -q wait=1 -q timeout=120orchard api deployments_env_set -p id=$DEPLOYMENT -d @env.json --yes| Flag | Purpose |
|---|---|
-p |
Fills a path parameter. |
-q |
Adds a query parameter. |
-d |
Sends a JSON body, a @file, or - for stdin. |
--yes |
Confirms a destructive operation without a terminal. |
orchard api GET /path also works, and does not use the spec. Output is JSON when stdout is not a terminal.
Deploy and wait until the app is live
Section titled “Deploy and wait until the app is live”since=$(orchard api deployments_rebuild -p id=$APP | jq -r .rolloutSince)orchard api deployments_rollout_get -p id=$APP -q wait=1 -q timeout=120 -q since=$since \ | jq '{phase, url, hint, error: .build.error}'Find crashing apps in a project
Section titled “Find crashing apps in a project”orchard api projects_deployments_list -p id=$PROJECT | jq -r '.[].id' |while read -r id; do orchard api deployments_rollout_get -p id=$id | jq -c --arg id "$id" 'select(.phase == "crashing" or .phase == "unhealthy" or .phase == "build_failed") | {id: $id, phase, hint, failing: [.pods.failing[]? | {pod, reason, exitCode}]}'doneSet one variable on every app in a project
Section titled “Set one variable on every app in a project”Secret values read back as null. Sending null keeps the stored value, so this script does not need to know any secret.
for id in $(orchard api projects_deployments_list -p id=$PROJECT | jq -r '.[].id'); do orchard api deployments_get -p id=$id | jq '{env: ([.envVars[] | {key, value, secret}] | map(select(.key != "LOG_LEVEL")) + [{key: "LOG_LEVEL", value: "info"}])}' | orchard api deployments_env_set -p id=$id -d - --yesdoneCall the API from Node.js
Section titled “Call the API from Node.js”const base = process.env.ORCHARD_API_URL;const headers = { Authorization: `Bearer ${process.env.ORCHARD_API_TOKEN}` };const api = (path) => fetch(`${base}/apiv1${path}`, { headers }).then((r) => r.json());
const deployments = await api(`/projects/${process.env.PROJECT}/deployments`);for (const d of deployments) { const rollout = await api(`/deployments/${d.id}/rollout`); if (!['live', 'stopped'].includes(rollout.phase)) console.log(d.name, rollout.phase, rollout.hint);}The API allows 600 requests a minute for each token. Use wait=1 on the rollout endpoint instead of polling.
Connect the compact MCP server
Section titled “Connect the compact MCP server”Point the client at /compact on the MCP host:
claude mcp add --transport http orchard-compact https://mcp.example.com/compactAuthentication works the same as on the full server. Use OAuth with mcp:read, mcp:deploy, or mcp:exec, or an orch_ token, as described in Connect an MCP client.
The server has three tools:
| Tool | Purpose |
|---|---|
search_api |
Finds operations by keyword. Returns IDs, paths, and flags, best match first. |
describe_operation |
Returns the full contract for one operationId or "METHOD /path". |
call_api |
Runs one operation as you, with pathParams, query, body, and fields. |
call_api has the following limits:
- Destructive operations: The call fails unless
confirmis set to theoperationId. fields: The response keeps only the dotted paths that you list, such as["items.id","items.status"].- Output size: Orchard cuts output over 24,000 characters and adds a note to narrow the request.
- Scope: Orchard refuses operations that need a higher scope than the connection has. The error names the required scope.
Results from operations flagged x-orchard-sensitive carry _meta: { "orchard/sensitive": true }.
Each call is one turn for the model. Scripts in a shell need fewer turns for work that chains several calls.
Related resources
Section titled “Related resources”- Use the CLI - Install the CLI, sign in, and set the defaults that
orchard apiuses. - Docs for agents - Give an agent this documentation as Markdown or
llms.txt. orchard apireference - Every flag oforchard api,search, anddescribe.