Skip to content
Install

Docs for agents

Every page of this documentation is also available as plain Markdown, so an agent can read it without parsing HTML or running a browser. This page lists those Markdown sources, and the separate entry points an agent uses to operate an Orchard instance through MCP or the API.

Add .md to a documentation URL:

https://docs.orchard.hackclub.com/start/install/ the page
https://docs.orchard.hackclub.com/start/install.md its Markdown source

The home page is at /index.md.

Each page has these actions under its title:

Action Result
Copy as Markdown Copies the page as Markdown.
View as Markdown Opens the Markdown source.
Agent setup Opens the agent setup page.

The menu next to them has Open in Claude, Open in ChatGPT, and Connect to MCP.

Two files follow the llms.txt convention.

File Contents
/llms.txt An index of every page, grouped by section, with Markdown links.
/llms-full.txt The entire documentation set as one document.

Use llms.txt to decide what to read. Use llms-full.txt to load everything in one request.

This documentation has no MCP server. The Orchard MCP server runs at mcp.<your domain> and operates your instance instead of serving these pages. To set it up, refer to Connect an MCP client.

An agent can also use the following entry points, which code mode for agents describes in detail.

Entry point Purpose
GET /apiv1/agent-spec.json A trimmed spec of the operations that an agent can call.
GET /apiv1/openapi.json The complete OpenAPI document.
orchard api search and describe The same spec from a shell, with calls by operationId.
https://mcp.<domain>/compact The whole API through three MCP tools.

Send the following request:

GET /apiv1/deployments/:id/rollout?wait=1

The response has the phase and, when the deploy is live, the URL. When the deploy fails, it has the build error or the crashing pod with a log tail.

To roll back to the previous image, send POST /apiv1/deployments/:id/rollback with no history ID.

To retry a request without doing the work twice, send an Idempotency-Key header. Orchard supports this header on requests that create a project, app, or database, rebuild, restart, or roll back an app, run a job, restart a database, and upgrade, fork, checkpoint, or restore a database.

A retry with the same key and body replays the first response for 24 hours. The same key with a different body returns a 422 status. A key that is still in progress returns a 409 status.

  • Use the CLI - Install the orchard CLI and script it with JSON output and stable exit codes.
  • MCP tools - Every tool that the Orchard MCP server exposes.