Skip to content
Install

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.

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-destructive marks deletes, whole-list replacements, and other operations that remove or overwrite state.
  • x-orchard-sensitive marks responses that contain a secret.

Both spec files are public and served with an ETag:

GET https://orchard.example.com/apiv1/agent-spec.json
GET https://orchard.example.com/apiv1/openapi.json

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

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_get
orchard api deployments_rollout_get -p id=$DEPLOYMENT -q wait=1 -q timeout=120
orchard 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.

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}'
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}]}'
done

Set 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 - --yes
done
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.

Point the client at /compact on the MCP host:

claude mcp add --transport http orchard-compact https://mcp.example.com/compact

Authentication 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 confirm is set to the operationId.
  • 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.