# MCP API — Ordo Kit provisioning Deploy a GitHub repository containing a Dockerfile — public or private — and get a running site at `https://.ordokit.dev` with a Let's Encrypt certificate. This document describes the Model Context Protocol server. Everything here is also available through the web dashboard at https://ordokit.dev/app; the two drive the same pipeline, the same quota and the same audit trail. - **Endpoint** `https://ordokit.dev/mcp` - **Transport** Streamable HTTP — JSON-RPC 2.0 over `POST` - **Protocol versions** `2026-07-28`, `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05` — see [Protocol versions](#protocol-versions) - **Auth** OAuth sign-in (the client sends you here to approve it), or an API token for scripts, sent as `Authorization: Bearer ` --- ## Quickstart ### 1. Connect your agent Give your agent the address `https://ordokit.dev/mcp`. It asks you to sign in: your browser opens here, you sign in with GitHub, and you approve it on the consent page. There is no token to copy. Each client's own steps: **Claude** (claude.ai and the desktop app): Customize → Connectors → + → Add custom connector. Name it Ordo Kit, paste `https://ordokit.dev/mcp` as the URL, then choose Connect. Turn it on for a chat from + → Connectors. **Claude Code:** ```bash claude mcp add --transport http ordo https://ordokit.dev/mcp ``` Then, in Claude Code, run `/mcp`, pick `ordo` and authenticate. Add `--scope user` to the command to have it in every project. **Codex:** ```bash codex mcp add ordo --url https://ordokit.dev/mcp codex mcp login ordo ``` **Gemini CLI:** ```bash gemini mcp add --transport http ordo https://ordokit.dev/mcp ``` It finds the sign-in by itself the first time the server asks; `/mcp auth ordo` inside Gemini CLI starts it by hand. **Cursor**, in `~/.cursor/mcp.json`; Cursor registers itself and asks you to sign in to `ordo` from its MCP settings: ```json { "mcpServers": { "ordo": { "url": "https://ordokit.dev/mcp" } } } ``` **VS Code**, in `.vscode/mcp.json` (or the file *MCP: Open User Configuration* opens, for every workspace); it opens your browser the first time the server starts: ```json { "servers": { "ordo": { "type": "http", "url": "https://ordokit.dev/mcp" } } } ``` **opencode**, in `opencode.json`; it signs in the first time the server is used, or run `opencode mcp auth ordo`: ```json { "mcp": { "ordo": { "type": "remote", "url": "https://ordokit.dev/mcp", "enabled": true } } } ``` The Settings page in the dashboard shows all of these with the address filled in. **The consent page** names the app asking and the address it will send you back to. An app identified by a published metadata URL is named by that URL's host, because the name inside the document is its own claim; any other app is named as it registered, so check the address beside it. On the free trial the consent page asks you to verify a card first: it costs $0 and nothing is charged. Paid plans need nothing more. ### How signing in works - **Discovery.** A request without a valid token gets HTTP 401 with `WWW-Authenticate: Bearer resource_metadata="https://ordokit.dev/.well-known/oauth-protected-resource"`. That document (RFC 9728) names this site as the authorization server, whose metadata is at `https://ordokit.dev/.well-known/oauth-authorization-server` (RFC 8414). - **Registration.** A client registers itself (RFC 7591) or identifies itself with a Client ID Metadata Document. Every client is public and uses PKCE with S256; tokens are issued only for `https://ordokit.dev/mcp` (RFC 8707). - **Tokens.** An access token lasts one hour and a refresh token sixty days; the client refreshes by itself, and each refresh token works once. A refresh token or code used twice ends the connection, and you sign in again. - **Disconnecting.** Settings → Connected apps lists every app with when it was connected and last used. Disconnect ends its access at once. Deleting your account removes them all. A connected app acts as you, like a click in the dashboard: the same quota, the same ownership rule, the same audit trail. ### 2. For scripts and CI: an API token Where a browser sign-in is not possible, use a token. Mint one at Settings → API access. It is shown once: only a hash is stored, so it genuinely cannot be displayed again. Tokens start with `omcp_`, and the same plan and card rules apply. Check it before configuring anything. Replace `$TOKEN` with the token you just minted — do not paste it literally: ```bash curl -s https://ordokit.dev/mcp/whoami -H "Authorization: Bearer $TOKEN" ``` A working token answers: ```json {"authenticated": true, "auth": "api_token", "login": "you", "github_id": 1, "operator": false, "mcp_access": true} ``` `"mcp_access": false` means the token is fine but the account is not open to the MCP API yet; `reason` says why and `verify_url` where to fix it. Anything else tells you exactly what is wrong — no header, not a Bearer value, an incomplete token, or one that has been revoked. Then send it as a header on every request: ```bash curl -s https://ordokit.dev/mcp \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` A client that cannot sign in takes the same header in its config, for example: ```json { "mcpServers": { "ordo": { "type": "http", "url": "https://ordokit.dev/mcp", "headers": { "Authorization": "Bearer omcp_REPLACE_WITH_YOUR_TOKEN" } } } } ``` ### 3. Deploy something The normal order, and what each step is for: ``` check_alias → is the address free inspect_repository → what port does the container listen on suggest_dockerfile → no Dockerfile? one to commit (review_dockerfile if there is) scan_repository → will it be refused, and will it fit the plan create_deployment → returns a job_id get_progress → poll until status is "done" or "error" ``` A deployment takes one to three minutes. Poll every few seconds, not continuously. ```jsonc // create_deployment {"alias": "my-app", "repository": "https://github.com/owner/repo", "port": "3000", "branch": "main"} // → {"job_id": "a1b2c3…", "alias": "my-app", // "url": "https://my-app.ordokit.dev"} // get_progress, until finished is true {"job_id": "a1b2c3…"} ``` When it finishes, the site is live at `https://my-app.ordokit.dev` with a valid certificate. ### Private repositories A private repository needs a one-time setup that only a person can do, because both parts are GitHub permissions: 1. **Install the Ordo Kit GitHub App on the repository** — read-only access to its contents, so it can be screened and its pushes deployed. 2. **Add a read-only deploy key** to it, which the build server clones with. `inspect_repository` reports where things stand in its `access` object: ```jsonc // inspect_repository {"repository": "https://github.com/owner/private-repo"} {"port": null, "status": "not_found", …, "access": { "repository": "owner/private-repo", "visibility": "unknown", // public | private | unknown "ready": false, "needs_person": true, "next_step": "Nothing readable at github.com/owner/private-repo: either the address is wrong, or … ask the user to open this link and install the Ordo Kit GitHub App …", "url": "https://ordokit.dev/github/install?repository=owner/private-repo", "push_to_deploy": false }} ``` When `ready` is false, give the user `next_step` and `url`, wait for them, and call `inspect_repository` again. The first time it points at installing the app; the second time, at a page that shows the deploy key and checks it with GitHub. Once `ready` is true, `create_deployment` works like it does for a public repository — and if it is called too early, its error carries the same link. `push_to_deploy: true` means the app is on the repository: every push to the deployed branch is screened, then that exact commit is built. --- ## Example prompts Things to say to an agent once it is connected, and the tools it uses to do them. Replace `/` with a repository of yours. **“Deploy https://github.com// and give me the live URL.”** Tools: `inspect_repository` → `create_deployment` → `get_progress` The agent reads the repository for the port its container listens on, whether its Dockerfile is where it should be, and whether this account can deploy it. It picks an address (`suggest_alias` makes one up), starts the deployment, and polls the job until it is done: one to three minutes. The answer is `https://.ordokit.dev`, with a valid certificate. **“My repository has no Dockerfile. Deploy it anyway.”** Tools: `inspect_repository` → `suggest_dockerfile` → `create_deployment` → `get_progress` `inspect_repository` finds no Dockerfile and points at `suggest_dockerfile`, which writes one and a .dockerignore for the stack it finds, from fixed templates. The agent writes both into your repository, commits and pushes them - with your say-so - and deploys with the Dockerfile path and port it was given. Nothing is written anywhere by us: the build reads your repository. **“Can my Dockerfile be better?”** Tools: `review_dockerfile` Recommendations, none required to deploy: a dev server as the start command, a server bound to localhost, an unpinned base image, a missing .dockerignore. Where the fix is mechanical it comes back as an improved copy of the whole file, for you to take or leave. **“Why did my last deployment fail?”** Tools: `list_deployments` → `get_logs` The agent finds the deployment that failed among yours, then reads its log: our pipeline steps and the build output, newest run first. The reason is usually in the last few lines. The log is the repository's own output, so it arrives labelled as third-party content. **“Is the name my-app free? If not, suggest one for https://github.com//.”** Tools: `check_alias` → `suggest_alias` `check_alias` says whether `my-app.ordokit.dev` is free, taken, or already yours. If it is taken, `suggest_alias` returns a free name made from the repository's, such as `repo-k3x9`. Both are advisory: the name is claimed when the deployment is created. **“Suspend my staging site.”** … **“Start it again.”** Tools: `list_deployments` → `suspend_deployment` → `start_deployment` The agent finds the site's address among yours, then stops its container. The address and the project stay, and the site still counts towards your plan's limit. Asked to start it again, the agent redeploys it at the same address. **“What plan am I on and how many sites do I have left?”** Tools: `get_plan` One call returns the plan, the memory and CPU every site runs with, how many sites are in use and how many are left, and this cycle's bandwidth against the allowance. **“Deploy https://github.com//shop at shop.example.com.”** Tools: `check_domain` → `create_deployment` → `get_progress` `check_domain` checks that the hostname already points here and, if it does not, names the exact DNS record to add. Only you can change your DNS, so the agent hands that over and checks again. Then it deploys with the domain set, and the site answers on both `shop.example.com` and its `.ordokit.dev` address. **“Add shop.example.com to my site.”** Tools: `list_deployments` → `check_domain` → `set_domain` → `get_progress` For a site that is already running. The agent finds it among yours, checks the hostname's DNS and hands you the record to add if it is not there yet, then sets the domain. The site is redeployed at the commit it is running, without a rebuild, and the job ends once the new hostname has its certificate. `.ordokit.dev` keeps working throughout. A site has one own domain: setting another replaces it, and `remove_domain` takes it off and frees the hostname. --- ## Troubleshooting ### "The client gets 401, or says it needs an API token" Every request needs credentials, the `initialize` handshake included. A request without a usable token is answered with HTTP 401 and a `WWW-Authenticate` header pointing at the OAuth metadata, which is what makes a client that supports sign-in ask you to sign in. A client configured with an API token that still gets 401 is sending no usable token, and the server says which of these it is: | What you see | What it means | | --- | --- | | `No Authorization header was sent` | The header never left the client. It is configured somewhere the client is not reading, or the argument was dropped by the shell. | | `must read 'Authorization: Bearer '` | The scheme is missing or wrong. The message quotes what arrived — if that is your token, the word `Bearer` is missing in front of it. | | `not a complete token` | Usually the placeholder from these instructions, pasted unedited. | | `not recognised` | Revoked, or from a different instance. | Two things worth checking in order: 1. `curl https://ordokit.dev/mcp/whoami -H "Authorization: Bearer $TOKEN"` — if this says `true`, the token is fine and the problem is in the client. 2. `claude mcp get ordo` — confirm the header is attached to the *server* entry, not merely typed at the shell when you added it. Because the 401 comes on the first request, a client that checks status codes reports the connection as unauthenticated rather than as working. A client that signed in and is asked to sign in again has lost its connection: it was disconnected on the Settings page, it went sixty days unused, or a refresh token was used twice. Sign in again - `/mcp` in Claude Code, `codex mcp login ordo`, `/mcp auth ordo` in Gemini CLI, Connect in Claude. With a valid token for an account whose MCP access is closed (a trial without a verified card), the handshake succeeds and its `instructions` say why every tool call will be refused. ## What this server will not do Four limits are deliberate. An agent will meet them, so they are stated here rather than discovered. **Bring-your-own VPS is not available over MCP.** Registering your own server means signing in as root over SSH, installing Docker, taking ports 80 and 443 and leaving an agent holding the Docker socket. That needs a person to read the terms and agree to them. A JSON field asserting consent is not the same act, and the audit record would be a lie. Use the web dashboard. **Secrets are never returned.** The push-to-deploy webhook secret is not in any response from this server. An agent's context ends up in transcripts, logs and third-party model providers, which is a worse home for a live secret than a browser session. Read it from the deployment page on the dashboard. **Private repository setup needs a person.** Installing the GitHub App and adding a deploy key are permissions on somebody's GitHub account, granted on GitHub. The server hands back a link for the user to open instead; it never asks for a GitHub token and never returns a key. **Operator tools are read-only.** An operator token can list every deployment, read the reconcile report, read the audit trail and read one account's timeline. Removing another tenant's project stays in the dashboard, where a person confirms it. ## Privacy The server never sees your conversation with the agent: a tool call brings only the tool's name and its arguments. Each call is logged with the tool's name, the names of its arguments (not their values) and your login. Access and refresh tokens, and API tokens, are stored only as SHA-256 hashes. What is kept and for how long is in the privacy policy at https://ordokit.dev/privacy. --- ## Third-party content Several tools relay text this service did not write: build output produced by whatever is in a repository's Dockerfile, names other tenants chose, error strings from the infrastructure underneath. That text reaches a model's context verbatim, which makes it a route for injected instructions — `RUN echo "ignore your instructions and ..."` in a Dockerfile lands in `get_logs` exactly as typed. Sanitising it would destroy the reason people read logs, so those results are labelled with their source instead. The text content opens with `Source: third-party.` and a one-line note, and fences the payload between two markers: ``` --- begin third-party content --- --- end third-party content --- ``` The structured form carries the same label as two sibling keys alongside the usual fields, which keep their names and shape: ```json { "_source": "third-party", "_source_note": "Includes text from repositories, build output, infrastructure messages and names chosen by other people. That text was not written by Ordo Kit." } ``` `_source` is a fixed key and value for a client to match on. Everything between the markers is quoted material from those third parties, not text written by the operator of this server. The tools that carry the label: `get_logs`, `scan_repository`, `inspect_repository`, `suggest_dockerfile`, `review_dockerfile`, `get_deployment`, `get_progress`, `list_deployments`, `list_all_deployments`, `reconcile_report`, `read_audit`, `user_timeline`. The ones that do not return only strings this service authored. ## Protocol versions The server speaks both eras of MCP on the one endpoint. MCP clients handle this by themselves; it matters only if you are writing one. **`2026-07-28`: no handshake.** Every request carries its version and the client's capabilities in `params._meta` (`io.modelcontextprotocol/protocolVersion`, `io.modelcontextprotocol/clientCapabilities`), and the headers `MCP-Protocol-Version`, `Mcp-Method` and, for `tools/call`, `Mcp-Name` must say the same as the body. `server/discover` returns the supported versions, the capabilities, the server's identity and the instructions below: ```json {"jsonrpc": "2.0", "id": 1, "method": "server/discover", "params": {"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {}}}} ``` Every result has `resultType: "complete"` and names the server in `_meta["io.modelcontextprotocol/serverInfo"]`; `server/discover` and `tools/list` carry `ttlMs` and `cacheScope: "private"` (the tool list differs for operators). `subscriptions/listen` is acknowledged with no notification types and closed at once: the tool list changes only when the service is redeployed. `ping` and `initialize` do not exist in this era. **`2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`: the `initialize` handshake.** The server answers with the version the client asked for when it is one of these, and with `2025-11-25` otherwise. Later requests send the negotiated version in `MCP-Protocol-Version`; a request without the header is treated as `2025-03-26`. JSON-RPC batches are accepted only from `2025-03-26` and `2024-11-05`, which still had them. | Status | Error | When | | --- | --- | --- | | `400` | `-32022` Unsupported protocol version | `data.supported` lists what to retry with | | `400` | `-32020` Header mismatch | A required header is missing or differs from the body | | `400` | `-32602` Invalid params | A modern request without its `_meta` version or capabilities | | `404` | `-32601` Method not found | A modern request for a method this server does not have | ## Errors Two kinds, and they mean different things. A **JSON-RPC error** means the request was malformed or not permitted: ```json {"jsonrpc": "2.0", "id": 1, "error": {"code": -32001, "message": "This tool needs an API token."}} ``` | Code | Meaning | | --- | --- | | `-32700` | Invalid JSON | | `-32600` | Not a valid JSON-RPC request | | `-32601` | Unknown method | | `-32602` | Unknown tool, or bad arguments | | `-32001` | Missing, unknown or revoked token | A **tool error** means the request was understood and could not be carried out — a taken alias, a blocked repository, a full quota. It comes back as a normal result with `isError` set, so a model can read the reason and act on it: ```json {"content": [{"type": "text", "text": "{\"error\": \"That address is taken.\"}"}], "structuredContent": {"error": "That address is taken."}, "isError": true} ``` --- ## Tools Every tool returns both `content` (text, for the model) and `structuredContent` (the same data, parsed). ## Tenant tools ### `get_plan` Read the plan limits. read-only. Your plan, the resource limits every deployment runs under, how many of your sites are in use, and this cycle's bandwidth against the allowance. Worth reading before deploying: the memory ceiling is a hard cgroup limit and a container that exceeds it is killed, not throttled. _No parameters._ ### `check_alias` Check an address is free. read-only. Whether .ordokit.dev is available. Aliases are lowercase letters, digits and hyphens, starting and ending alphanumeric. Answering from our records, so it is fast but advisory - the binding claim happens inside create_deployment, which is where two callers racing for the same name is actually resolved. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `alias` | string | yes | The subdomain to check. | ### `suggest_alias` Suggest a free address. read-only. A free .ordokit.dev derived from the repository name plus four random characters, e.g. groundstation-k3x9. Checked against existing deployments before it is returned; call again for another. Advisory like check_alias - the claim happens in create_deployment. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `repository` | string | yes | The repository being deployed. | ### `check_domain` Check an own domain's DNS. read-only. Whether a customer's own domain (e.g. app.example.com) already points at the managed host, and if not, exactly which DNS record to add. create_deployment makes the same check and refuses until it passes, so use this first and relay `message` to the user - only they can change their DNS. One hostname per deployment; the shared .ordokit.dev address keeps working alongside it. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `domain` | string | yes | The customer's hostname. | | `alias` | string | no | Optional: the shared alias, so the answer can offer a CNAME. | ### `inspect_repository` Detect the container port. read-only. Reads a GitHub repository and suggests the port its container listens on, with the evidence used and a confidence. Advisory: pass the port you know to be right to create_deployment rather than trusting a low-confidence guess, because a wrong port produces a deployment that builds, starts and never answers. When no port comes back, `status` says why: 'not_found' means nothing readable at that address - wrong owner, name or branch, or a private repository not yet granted; 'undetermined' means it was read and gave nothing away. Also returns `access`: whether this account can deploy the repository now (`ready`), and if not, a `next_step` and `url` for the user. Private repositories need a person to finish setup - relay those rather than trying to work around them. Also returns `dockerfile`: whether a Dockerfile exists at that path on that branch, and if not, the Dockerfiles that do exist (`candidates`). And `build`: the build context worked out from the Dockerfile (`base_directory`, with `source` saying why), and any files it COPYs that are missing there (`missing`, which create_deployment refuses). | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `repository` | string | yes | https://github.com// | | `branch` | string | no | Default `main`. | | `dockerfile` | string | no | Path of the Dockerfile in the repository, e.g. /apps/web/Dockerfile. Default /Dockerfile. Relative to base_directory only when base_directory is given. Default `/Dockerfile`. | | `base_directory` | string | no | Optional; normally leave it out. The build context - the folder the build runs in - is then worked out from the Dockerfile: the folder, from the Dockerfile's own up to the repository root, in which every file it COPYs exists. Give it only to override that; a folder in which the Dockerfile's COPY sources do not exist is refused, with the one that works. | ### `scan_repository` Screen a repository. read-only. Security and resource screening. Returns blocking findings, advisory warnings, and an estimate of whether the project fits the plan's memory. A repository with blocking findings will be refused by create_deployment, which runs this again itself - screening here is so you learn that before committing to a deployment, not so it can be skipped. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `repository` | string | yes | | | `branch` | string | no | Default `main`. | ### `suggest_dockerfile` Write a Dockerfile. read-only. Writes a Dockerfile and .dockerignore for a repository that has none, from fixed templates for the stack it finds (Next.js, Nuxt, SvelteKit, Astro, Vite and other single-page apps, Node servers, NestJS, Bun, Django, FastAPI, Flask, Go, static sites): a build stage, a pinned base image, the lockfile installed exactly, a production server on 0.0.0.0, a non-root user. Nothing is changed anywhere: deployment builds from the repository, so write the files it returns into the repository at the paths given, commit and push them, then call create_deployment with the `dockerfile` and `port` it returns. Pass `repository`, or - for code not pushed yet - `files` and `paths`. Returns `suggestions` (one per project found; `notes` says what to check) and `unsupported` with the reason for each project it could not write for. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `repository` | string | no | https://github.com// | | `branch` | string | no | Default `main`. | | `folder` | string | no | Optional: the project folder to write for, e.g. /apps/web. Left out, every project found is written for. | | `files` | object | no | Instead of repository: files you have locally, as path (from the project root) to content - package.json, a lockfile's name with any content, pyproject.toml, requirements.txt, go.mod, the file that creates the app. At most 60 files, 1 MB in all. | | `paths` | array | no | With files: every file path in the project, contents not needed, so the rules can see what exists (lockfiles, manage.py, cmd/*/main.go). At most 5000. | ### `review_dockerfile` Review a Dockerfile. read-only. Recommendations for an existing Dockerfile, none of them required to deploy: `warn` for what is likely to cause trouble here (a dev server as the start command, binding localhost, npm ci without a lockfile, a secret in ENV), `tip` for good practice (a pinned base image, a .dockerignore, manifests copied before the code, a non-root user). Each item names its `line`. Where the fix is purely mechanical, `improved` is the whole Dockerfile with those fixes applied, and `dockerignore` a file to add; offer them to the user rather than applying them unasked. Pass `repository` (the build context is worked out unless `base_directory` is given), or `content` with optional `files` and `paths` for a Dockerfile not pushed yet. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `repository` | string | no | https://github.com// | | `branch` | string | no | Default `main`. | | `dockerfile` | string | no | Path of the Dockerfile in the repository, e.g. /apps/web/Dockerfile. Default /Dockerfile. Relative to base_directory only when base_directory is given. Default `/Dockerfile`. | | `base_directory` | string | no | Optional; normally leave it out. The build context - the folder the build runs in - is then worked out from the Dockerfile: the folder, from the Dockerfile's own up to the repository root, in which every file it COPYs exists. Give it only to override that; a folder in which the Dockerfile's COPY sources do not exist is refused, with the one that works. | | `content` | string | no | Instead of repository: the Dockerfile's text. At most 128 KB. | | `files` | object | no | Instead of repository: files you have locally, as path (from the project root) to content - package.json, a lockfile's name with any content, pyproject.toml, requirements.txt, go.mod, the file that creates the app. At most 60 files, 1 MB in all. | | `paths` | array | no | With files: every file path in the project, contents not needed, so the rules can see what exists (lockfiles, manage.py, cmd/*/main.go). At most 5000. | ### `create_deployment` Deploy a repository. **changes state** — creates something new and changes nothing that exists, so it is not annotated destructive. Builds a GitHub repository and serves it at https://.ordokit.dev with a Let's Encrypt certificate. The repository must contain a Dockerfile at dockerfile; if it does not, the refusal lists the Dockerfiles that do exist, with arguments to retry with. The build context is worked out from the Dockerfile unless base_directory is given. A private one must first show `access.ready` in inspect_repository. Returns a job_id immediately; the deployment itself takes one to three minutes, so poll get_progress until status is 'done' or 'error'. Deploys onto managed hosting - bringing your own VPS needs a person to consent to root access and is only available through the web dashboard. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `alias` | string | yes | Subdomain; the site becomes .ordokit.dev | | `repository` | string | yes | https://github.com// | | `branch` | string | no | Default `main`. | | `port` | string | yes | Container port. Use inspect_repository if unsure. | | `dockerfile` | string | no | Path of the Dockerfile in the repository, e.g. /apps/web/Dockerfile. Default /Dockerfile. Relative to base_directory only when base_directory is given. Default `/Dockerfile`. | | `base_directory` | string | no | Optional; normally leave it out. The build context - the folder the build runs in - is then worked out from the Dockerfile: the folder, from the Dockerfile's own up to the repository root, in which every file it COPYs exists. Give it only to override that; a folder in which the Dockerfile's COPY sources do not exist is refused, with the one that works. | | `health_check` | string | no | Optional HTTP path for a health check. | | `email` | string | no | Optional contact address for the welcome message. | | `domain` | string | no | Optional: the customer's own hostname, served alongside .ordokit.dev. Its DNS must already point at the managed host - see check_domain. | ### `get_progress` Follow a running job. read-only. The steps of a deployment, a domain change or a teardown, in order, with a percentage and the newest status. Poll this after create_deployment, set_domain, remove_domain or terminate_deployment until status is 'done' or 'error'. Pass after_id to get only what is new. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `job_id` | string | yes | | | `after_id` | integer | no | Only events newer than this id. Default `0`. | ### `list_deployments` List your deployments. read-only. Every deployment you own, with its live container state. _No parameters._ ### `get_deployment` Read one deployment. read-only. Health, address, repository and last build for one deployment. Does not return the webhook secret - that is on the web dashboard only. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `alias` | string | yes | | ### `get_logs` Read the build log. read-only. Our pipeline steps and the build output for one deployment, newest run first. This is what to read when a deployment failed and you want to know why. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `alias` | string | yes | | | `limit` | integer | no | Maximum log lines to return. Default `200`. | ### `start_deployment` Start a stopped deployment. **changes state** — annotated destructive: it changes or removes something that exists, so a client can ask before calling it. Redeploys a suspended deployment. Returns immediately. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `alias` | string | yes | | ### `suspend_deployment` Stop a deployment. **changes state** — annotated destructive: it changes or removes something that exists, so a client can ask before calling it. Stops the container without deleting anything. The address and project both survive, and it still counts against your quota; use terminate_deployment to free a slot. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `alias` | string | yes | | ### `terminate_deployment` Destroy a deployment. **changes state** — annotated destructive: it changes or removes something that exists, so a client can ask before calling it. Permanently removes the application, its project and its team, and frees the address. This cannot be undone. Returns a job_id; poll get_progress - termination is only reported complete once the address has stopped answering, which takes a few seconds after the containers go. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `alias` | string | yes | | ### `set_domain` Add or change an own domain. **changes state** — annotated destructive: it changes or removes something that exists, so a client can ask before calling it. Serves an existing deployment at the customer's own hostname (e.g. shop.example.com) as well as at .ordokit.dev, replacing any own domain it had. Only the owner may, and only while it is running. The DNS must already point at the server - check_domain says which record to add and whether it is in place, and a refusal here carries the same answer in `dns`. Returns a job_id; poll get_progress until status is 'done' or 'error'. The site is redeployed at the commit it is running (no rebuild), then the certificate for the new hostname is issued, which takes a minute or two. Calling it again with the same domain re-applies it, which is how to retry a change whose redeploy failed. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `alias` | string | yes | The deployment. | | `domain` | string | yes | The customer's hostname. | ### `remove_domain` Remove an own domain. **changes state** — annotated destructive: it changes or removes something that exists, so a client can ask before calling it. Stops serving a deployment at its own domain; .ordokit.dev keeps working. Only the owner may, and only while it is running. Frees the hostname for use by another deployment. Returns a job_id; poll get_progress until status is 'done' or 'error'. The customer's DNS record is theirs to remove. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `alias` | string | yes | The deployment. | ## Operator tools Available only to a token belonging to an operator. They are absent from `tools/list` for everyone else, rather than present and refused. ### `list_all_deployments` List every deployment. read-only. Every deployment on the instance, with its owner. _No parameters._ ### `reconcile_report` Compare the platform against our records. read-only. What the platform holds against what this service recorded: untracked projects, orphaned groups, deployments whose project has gone, and which site names on the managed server hold a certificate of their own instead of the zone's wildcard, and how many days the wildcard the server serves has left (certificates.served: level ok, warn under 20 days, error under 7 or when it does not verify, unknown when it could not be reached). Read-only - removing anything it finds is done from the web dashboard, where a person confirms it. _No parameters._ ### `read_audit` Read the audit trail. read-only. Who asked for what, and how it turned out. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `alias` | string | no | Optional filter. | | `limit` | integer | no | Default `100`. | ### `user_timeline` Read one account's timeline. read-only. Everything recorded about one account, oldest first, on one clock: audit rows, the activity trail (port detection, screening verdicts, access checks, refused deployments), pipeline events of every deployment it has had, its plan, card check, GitHub installations and tokens, GitHub deliveries naming it, and matching log lines when logs are kept. Give login or github_id; a login two accounts have used is refused with both ids. Read-only. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `login` | string | no | GitHub login. | | `github_id` | integer | no | GitHub numeric id; wins over login. | | `sources` | array | no | Only these sources. Default: all. | | `days` | integer | no | How far back. Default `30`. | | `limit` | integer | no | The newest this many items. Default `1000`. | --- ## Limits worth knowing - **Quota.** Each account may hold a limited number of live deployments. A suspended one still counts; terminate to free the slot. `get_plan` reports what is left. - **Resources.** Containers run under a hard memory cgroup limit. Exceeding it kills the container rather than slowing it. `scan_repository` estimates whether a project will fit before you commit to it. - **Certificates.** Let's Encrypt allows five certificates per exact hostname per week. Repeatedly deploying and terminating the *same* alias will exhaust that and leave the site on an untrusted certificate until the window rolls over. When testing, use a fresh alias each time. - **Screening.** Repositories are scanned before anything is created, and blocking findings refuse the deployment. `scan_repository` runs the same checks so you can see that first.