Ordo
Sign in

Documentation

Ordo Kit takes a GitHub repository — public or private — containing a Dockerfile and gives you back a running container on its own subdomain, with a Let's Encrypt certificate and a project of its own. This is how it works, end to end, and what to do when a step fails.

Overview #

One pipeline drives everything. The dashboard and the MCP server are two front doors onto it, sharing the same quota, ownership rules and audit trail. A deployment made by an agent is the same as one made by a click, and either can manage the other's work.

GitHub sign-in → plan → repository → target → address → deploy → live URL
You supply A GitHub repository with a Dockerfile, the port its container listens on, and a subdomain to publish it at.
We supply The build, the host, the reverse proxy, the TLS certificate, and a project of your own.

Accounts and plans

Sign-in is GitHub OAuth, requesting only read:user. The service never reads or writes your repositories on your behalf — it clones public code the same way anyone else would.

Your account is your GitHub numeric id, not your login. Logins can be renamed and reclaimed, so ownership, plan and operator rights all key on the id. Your login is kept beside it as a label and refreshed at each sign-in. Renaming your GitHub account costs you nothing.

Any GitHub account can sign in, and there is no approval step. What you can deploy is decided by your plan: start the free trial, or subscribe, and deploying opens as soon as the payment provider confirms the subscription — usually within seconds of the checkout.

Quick start #

From a standing start to a live URL is three screens and one to three minutes of waiting.

Before you begin

  • A public GitHub repository containing a Dockerfile that builds and runs your app.
  • The port the container listens on. If you are not sure, the wizard reads the repository and suggests one.
  • A plan: the free trial, or a subscription.

1. Repository

Paste owner/repo or the full https://github.com/owner/repo URL, pick a branch, and set the container port. Two things happen while you type:

  • Port detection. The repository's Dockerfile and framework conventions are read and a port is suggested, with the evidence it used and how confident it is. It is advisory — a confident guess is worth taking, a hesitant one is worth checking, because a wrong port builds and starts perfectly and then never answers. When no port can be found the field is left empty, and you enter the port your container listens on.
  • The Dockerfile. If there is no Dockerfile where the build will look, a red panel lists the Dockerfiles the repository does have, and Continue stays disabled until one is found; a repository with exactly one has it picked. The folder it builds in is worked out from the files it copies.
  • No Dockerfile at all? The wizard writes one, with a .dockerignore, for the stack it finds — Next.js, Nuxt, SvelteKit, Astro, Vite and other single-page apps, Node servers, NestJS, Bun, Django, FastAPI, Flask, Go or a static site — from fixed templates: a build stage, a pinned base image, the lockfile installed exactly, a production server listening on 0.0.0.0, a non-root user. Copy both into your repository, commit and push, then press Check again. The build reads your repository, so the files have to be there.
  • Suggestions for your Dockerfile. When there is one, a panel lists optional recommendations — a dev server as the start command, a server bound to localhost, an unpinned base image, no .dockerignore — with an improved copy of the file where the fix is mechanical. None of it is needed to deploy.
  • Screening. The code is scanned before anything is created. Continue stays disabled while a scan is in flight and stays disabled if the repository is refused. See Security screening.

Under Advanced: the build context (the folder the build runs in, / by default) and the Dockerfile location, relative to it. Both are filled in for you; set the context by hand only to override what was worked out, and it is then checked against the Dockerfile. Also an optional health-check path — a URL that returns 200 once the app is ready. Leave the health check blank and the container counts as healthy as soon as it runs.

2. Target

Managed host needs nothing from you — press Continue. My own VPS asks for an address, an SSH user and a key, and requires you to read and accept what that access involves; see Bring your own VPS.

3. Address

Choose between a shared domain and your own domain.

A shared address is https://<alias>.ordokit.dev and works the moment the site is deployed. Generate proposes a free one from the repository name plus four random characters — press it again for another, or type your own. Availability is checked as you type, so a taken name is caught in milliseconds rather than at 22% of a deployment.

With your own domain the site is served at your hostname and at its shared address; see Your own domain. A contact email is optional and is used only to send you the welcome message — it grants nothing and selects nothing.

The step ends with a summary of exactly what Deploy will do, because everything it commits to was entered on screens you have already left.

Your own domain

One hostname per deployment — app.example.org or example.org. At your DNS provider, add an A record for it pointing at the address the wizard shows: the managed host for managed hosting, or your server’s public IPv4 address if you brought one. Below the root of a domain a CNAME to the site’s shared address works too, and keeps working if the host ever moves.

  • Only that address. An extra A record, or an AAAA (IPv6) record, sends some visitors — and Let’s Encrypt — somewhere else, so either is refused.
  • Not proxied. With Cloudflare, set the record to DNS only (grey cloud); proxied, it resolves to Cloudflare and the check cannot see us behind it.
  • Checked before anything is built. Check DNS now asks public DNS straight away. At Deploy the same check runs again, and a wrong record stops the deployment there — before anything is created or built — with the record it expected.

Each hostname gets its own certificate. The shared address keeps working alongside it, so the site is reachable while a new record is still propagating. Over MCP, pass domain to create_deployment; check_domain answers the same question as the button.

Adding or changing it later. A site that is already running can be given its own domain, or a different one, from Your own domain on its page, or over MCP with set_domain. The same DNS check comes first, and a wrong record is refused with the record it expected. The site is then redeployed at the commit it is running — no rebuild — and the new hostname gets its certificate; the steps appear in the site’s timeline, or through get_progress. A site has one own domain, so a new one replaces the old. Remove (or remove_domain) stops serving it and frees the hostname for another site; the shared address keeps working either way, and the DNS record is yours to delete. Only the site’s owner can change its domain, and only while it is running: start a suspended site first.

4. Watch it run

Progress streams over Server-Sent Events, so the bar tracks real named stages rather than a timer. You can close the tab: the run continues, the events are stored, and opening the deployment again replays it from where it got to. A dropped connection resumes from the last event seen and is not a failed deployment.

Try it with something known to work

The repository field has a use an example link that fills in a small repository with a working Dockerfile and the right port. Worth using for a first run, so anything that goes wrong is the platform and not your build.

What you get #

When a run completes, the final screen carries three things:

ItemWhat it is
Live URL https://<alias>.ordokit.dev, served over HTTPS with a certificate that a browser accepts.
Certificate status Verified, or pending if issuance had not completed in time. Pending is not failure — see Certificates.
Webhook A payload URL and secret for rebuilding on every push. See Push to deploy.

Plans #

PlanPriceManaged sitesBandwidthOwn VPS
Free trialFree for 7 days15 GBNo
Starter$5 / month10100 GBNo
Full$20 / month100500 GBYes
Your own VPS$10 / monthnone on oursnot meteredYes

Yearly billing is offered too, and the dashboard shows the saving. Billing in the dashboard changes or cancels a plan and opens the payment provider's portal for invoices and cards. Payments are handled by Paddle, which is the merchant of record; refunds follow the refund policy.

On every plan

  • A GitHub repository with a Dockerfile, public or private, is the whole input
  • Your own subdomain with a Let's Encrypt certificate, renewed for you
  • Security screening before anything is built
  • Each project kept to itself, with its own variables, keys and logs
  • Live build logs, health and one-click stop, start and terminate
  • An MCP server, so an agent can deploy on your behalf

Changing plan

  • Upgrading applies at once, charged for the rest of the period.
  • Downgrading is refused while you hold more sites than the smaller plan allows, or sites of a kind it does not cover (a plan without your own servers will not take an account that has one), or when this month's bandwidth would get your sites paused on the smaller plan. Nothing is suspended as a side effect of a billing click; the message says what to change first.
  • A failed payment keeps what is running and refuses anything new for a grace period. After it, running sites are suspended, not deleted; start them again from Projects once the payment has gone through.
  • Cancelling runs to the end of the period you paid for.
The free trial and the MCP API

The trial needs no card. Using the MCP API on the trial asks for a card check at $0, nothing charged, because an agent can do in a loop what a person does by hand. Paid plans need nothing extra.

The deployment pipeline #

These are the named steps the progress view shows, in order. Knowing which one you are on is usually enough to know what went wrong.

  1. Checking the repository The repository exists, is public, and is on GitHub. A refusal here costs nothing.
  2. Screening the code Security and resource screening, before a project or an application exists.
  3. Isolating your project A project of its own, so nobody else can read its variables or act on it.
  4. Creating project and application An SSH key, a server reference, a project and a Dockerfile-based application, each created only if it does not already exist.
  5. Handing over the project The project is moved into that space.
  6. Preparing your server Bring-your-own-VPS runs only. Waiting until your machine is reported usable and its proxy is running. A deployment dispatched before that fails instantly with “Server is not functional”.
  7. Building and deploying The image is built and started, and the run is watched until the build queue reports it finished. A failed build fails the deployment, and carries the reason the builder announced.
  8. Issuing the TLS certificate Waiting for a verified TLS handshake and a non-5xx response from the site. Both, because a valid certificate in front of a 502 is not a working deployment.

Termination is a tracked pipeline too, with its own progress view: stop, drain, release (brought servers only), verify, gone. It is reported complete only once the address has actually stopped answering.

Repository requirements #

  • On GitHub, public or private. A public repository needs nothing more. A private one needs our GitHub App and a deploy key — see Private repositories. Other hosts are refused. Anything the build needs must be in the repository or fetched by it.
  • Contains a Dockerfile. Build packs like Nixpacks or static are not used here; the Dockerfile is the contract. Without one, the wizard (or suggest_dockerfile for an agent) writes one for you to commit.
  • Listens on one port. That port is published behind the proxy; the container does not need to handle TLS itself.
  • Binds to all interfaces. A server listening on 127.0.0.1 inside the container is unreachable from the proxy. Bind 0.0.0.0.
  • No credentials in the URL. A repository reference carrying user:pass@ is refused rather than stored.

A docker-compose.yml in the repository is not used. The application is a single container built from a single Dockerfile; a Compose file declaring databases and queues will be reported by screening as services that will not exist here. Bring your own managed database.

Private repositories

Two grants, each as narrow as GitHub allows, because they do different jobs:

  1. The Ordo Kit GitHub App, installed on the repository — Contents: read and Metadata: read, nothing else. It lets us screen the code and read its Dockerfile, and it is how pushes reach us. Install it on only the repositories you deploy; GitHub lets you choose. Every token we mint from it is narrowed to the one repository being read and expires within the hour.
  2. A deploy key, which the wizard generates for you: a read-only SSH key for that one repository. Our build server keeps it to clone on every redeploy, so if it ever leaked, what leaked is read access to one repository — not to everything you granted the app. Add it under Settings → Deploy keys with Allow write access unticked, then press check: we ask GitHub whether it accepts the key for that exact repository before anything is built.

Access is checked for you, not for the installation: the repository owner installing the app does not let everyone who types its name deploy it. It is checked again on every push, so somebody removed from a repository stops receiving its new code. A deploy key must be added by an admin of the repository; if that is not you, the wizard shows the key and link to send them.

We cannot see or delete deploy keys on GitHub — that would need the Administration permission, which also covers deleting the repository and is deliberately not requested. Terminating removes our copy of the key; remove GitHub’s under Settings → Deploy keys. Uninstalling the app from Settings → Applications on GitHub ends our access at once.

Deploying on push

With the app installed, every push to a deployed branch is screened before it is built, and only that exact commit is built. If pushes arrive faster than screening, only the newest is built — a slow screen never leaves the site on an older commit. Suspended deployments are not restarted by a push.

Without the app, the deployment page offers a webhook to add by hand. That path builds every push without screening. If you have added it and then install the app, remove the webhook, or each push builds twice.

Addresses and DNS #

Every deployment is published at <alias>.ordokit.dev. An alias is 3–32 characters, lowercase letters, digits and hyphens, starting and ending with a letter or digit.

The name is claimed, not assumed: the check and the write happen in one statement, so two people pressing Deploy on the same name at the same moment cannot both get it. The live availability check while you type is fast but advisory; the binding answer comes at deploy time. An address becomes free again only once nothing remains of what held it — a terminated or failed deployment.

DNS for the zone is handled for you on managed hosting. On your own VPS the record has to point at your machine: see DNS for a brought server.

Security screening #

This platform builds and runs other people's code with network access, so every repository is screened at intake — before a project or an application exists, when a refusal costs nothing to undo. Two layers, with deliberately different postures:

LayerCatchesPosture
Built-in rules Crypto miners and mining pools, reverse shells, Docker-socket access, privileged containers, host-root mounts Blocks
Built-in rules curl | sh, hardcoded IP:port, long base64 blobs, wallet addresses Warns
Trivy Leaked secrets, HIGH and CRITICAL misconfiguration Warns

Blocking is reserved for patterns with essentially no legitimate reason to appear in a repository you are asking someone else to host. Everything broader warns instead, on the principle that a scanner which refuses a deployment over a false positive gets switched off, and then it protects nothing.

A separate capacity check reports whether the project looks likely to fit the plan — a JVM base image, a bundled Postgres, headless Chromium, a machine-learning runtime, an unusually large repository. Capacity findings never block. Runtime memory cannot be predicted from source, and a guess that refuses a deployment would be a guess with consequences.

A blocked repository cannot be deployed

There is no override in the wizard and none over MCP. Remove the finding from the code and screen it again. Screening runs a second time inside the pipeline, so it cannot be skipped by calling the API directly.

Phishing checks

Every site here shares the ordokit.dev domain, so one phishing page can get every customer's address blocked by browsers and mail filters. Sites are checked for phishing three times: the code at screening, the live page right after the deploy, and every running site once a day.

A check looks for combinations legitimate sites do not have: a form asking for a wallet's recovery phrase, or a sign-in form under another company's name that sends what is typed elsewhere. An ordinary login page, or a "Sign in with Google" button, is neither.

A site with strong signs is paused for review

It is stopped, nothing is deleted, and a person looks at it. Until then it cannot be started from the dashboard or over MCP. If it was a mistake, write to us from the Support page and we will restore it.

Plan and limits #

LimitValueWhat it means
Memory512M A hard cgroup limit. A container that exceeds it is killed, not throttled. Swap is pinned to the same figure, so a memory limit means what it says.
CPU ceiling0.5 A hard cap that applies even on an idle host.
CPU shares64 Relative weight under contention. Docker's default is 1024.
Restarts10 Caps a crash loop rather than letting it run for ever.
DeploymentsSet by plan: 1 on Free trial, 10 on Starter, 100 on Full A suspended deployment still counts. Terminate one to free the slot.
BandwidthSet by plan: 5 GB on Free trial, 100 GB on Starter, 500 GB on Full Outbound traffic from your sites on our hosting, per calendar month (for the whole trial, on the trial). Sites on your own server are not counted.
Container logs50 MB per container 10 MB across 5 rotated files, compressed. Docker's own default is unbounded, which no memory or CPU limit protects against.
Outgoing emailPort 25 blocked On managed hosting, as spam protection. Send email through a provider such as Resend or Postmark, on port 587 or 465.

Limits are set when the application is created, never patched on afterwards: a container deployed unlimited and constrained a moment later has already had a window in which it could take the whole host.

When bandwidth runs out

At 80% of the allowance we email you once. Past 120% your sites on our hosting are suspended, with the reason on the record. They start again on their own when usage fits again: a new month, or a larger plan. Nothing is deleted, and a site you suspended yourself is left alone.

Builds are not bounded by these

Images are built on the host, outside any cgroup, so a repository whose build needs 4 GB will get it — and a runtime limit of 512M says nothing about it. Screening reports heavy build tooling separately for this reason.

Capacity and the build queue #

Ordo Kit is in beta, and our managed hosting has room for a set number of sites across all accounts. Your plan's limit is how many of them can be yours; this is how many there are in all.

  • When hosting is full, a deploy to managed hosting puts you on a waitlist and tells you your place. When a place opens we email the next person in line, so give an address in the wizard. Places are not held: if somebody deploys first, you stay at the front and hear from us again. Deploying to your own server is never waitlisted.
  • Deploys build a few at a time. A deploy that has to wait shows Waiting for a free build slot with its place in line, then carries on by itself. If it waits too long it stops with nothing created, and you can try again.
  • New deploys may be paused for a while, during maintenance. Sites already running are not affected, and the wizard says so before you fill it in.

The plan line at the top of the wizard, and the MCP get_plan tool, say whether hosting is full, whether deploys are paused, and your place on the waitlist.

Managed hosting #

The default, and the only target available to agents over MCP. Your container runs on our infrastructure, behind our proxy, on a subdomain of ordokit.dev whose DNS and certificates we handle. Nothing is installed anywhere of yours, and there is nothing to clean up afterwards: terminating removes the application and its project, and frees the address.

Isolation is per deployment: each one holds exactly one project, with its own variables, keys and logs. See Isolation, which also says what the shared host does and does not protect.

Bring your own VPS #

You can point a deployment at a machine you already have. Choose My own VPS on the target step and supply an address, an SSH user (typically root) and a private key.

What your host needs

A newly registered server is validated over SSH and marked unusable if any of these is missing. On a minimal image they are easy to overlook:

RequirementSymptom if absent
bash sh: bash: not found; the server is reported unreachable
curl, jq Prerequisites (curl, jq) are not installed; the server is unusable
A running Docker daemon Validation fails; Docker is installed for you if absent, but a broken daemon is not repaired
Ports 80 and 443 free The proxy will not start, so nothing is served and no certificate can be issued
The key's public half in authorized_keys Registration fails at the first connection
This gives us privileged access to that machine
  • We sign in over SSH as the user you name — typically root — using the key you paste, and act with that user's full privileges.
  • Docker is installed if it is not already present.
  • A reverse proxy (Traefik) is started and takes ports 80 and 443. If something else is using them, it will not start.
  • A monitoring agent (Coolify Sentinel) is started with access to the Docker socket and the host process namespace — which is equivalent to root on that machine.
  • That agent reports the server's running containers to this service every 60 seconds, for as long as the deployment exists.
  • A directory is created at /data/coolify for proxy configuration and certificates.
  • All of the above is removed when you terminate the deployment, along with our copy of your key.

The terms come from the API, not the page, and the version you agreed to is stored with a timestamp. A consent record is only evidence if the exact wording can be recovered later. The check runs on the server, not in the tick box: without a current consent version, registering a machine is refused.

How your SSH key is handled

  • Held in memory for the single provisioning call.
  • Streamed over stdin into a short-lived container, never written to a file on the host.
  • Cleared from the browser field as soon as the request is sent.
  • Never logged.
  • Deleted from our side entirely when the last deployment on that machine is terminated.

A key scoped to this purpose is still the better practice. Generate a fresh one, add it to authorized_keys, and remove it when you are done.

DNS for a brought server

The address still ends in ordokit.dev, but traffic has to reach you. Point the A record for <alias>.ordokit.dev at your server, and let it resolve before the certificate step runs. Let's Encrypt validates over HTTP on port 80, so an unpropagated record means no certificate.

A second project on the same machine

Deploying again to the same machine reuses it. Nothing is registered twice and no key is added. Reuse is gated on ownership: a machine somebody else brought, or one registered outside this service, is refused — and the refusal does not say whose it is.

Our own servers are refused as brought servers, before ownership is even considered. Internally they are registered like any other machine, so an address pointing at one would look like a server with neighbours. Terminating that “deployment” would stop the proxy for every tenant on it.

Teardown respects the same fact. The proxy is shared by everything on the machine, so terminating one of two projects removes only that project. The last one out releases the server.

What termination removes from your machine

Dropping our record of a server touches the host not at all — which would be reasonable for a cloud VM we could destroy, and useless for a machine we were merely lent. So termination stops the agents we started, removes what they leave behind, deletes our copy of your key, and only then drops the server record.

Everything removed is named. There is no prune and nothing is matched by pattern: your unrelated containers, networks and volumes are not candidates for removal. If something cannot be reached during teardown, what was left behind is written to the audit trail rather than silently retried, so it can be finished by hand.

Not available to agents

Registering a machine needs a person to read the terms above and agree to them. The MCP server has no parameter for it at all — see What it will not do.

Automatic provisioning Coming soon #

Today there are two targets: our managed host, and a machine you already run. A third is in progress — creating the server for you at a cloud provider, so that “bring your own VPS” no longer requires you to have brought one.

ProviderStatusWhat it will do
Hetzner Cloud Coming soon Pick a region and a server type; the machine is created, registered and provisioned in one run, and destroyed when the last deployment on it is terminated.
Vultr Coming soon The same flow against Vultr's regions and plans.

The groundwork is in place. The provisioning tool already knows a third server mode, and answers a request for it with a clear “not implemented” rather than falling back to something else. Teardown is written against the same distinction — a mode that only ever borrowed a server can never delete one.

Two things will not change when it lands:

  • Provider credentials stay yours. A token you supply is used for the calls you asked for, on the account you supply it for.
  • Consent still belongs to a person. Creating a server that bills your account is not something an agent will be able to do on your behalf over MCP.

Until then: create the machine at your provider by hand, make sure it meets the prerequisites, and bring it.

Lifecycle and projects #

Projects lists everything you own, with live container state read from the host rather than from our record. A container that died overnight shows as stopped, not running.

ActionEffectFrees the slot?
Start Redeploys a suspended deployment.—
Suspend Stops the container. The address and project both survive. No
Terminate Permanently removes the application and its project, releases the address, and — on a machine you brought — removes our software from it. Yes
Termination cannot be undone

Anything stored inside the container is gone: containers here are disposable, so persistent data belongs in a database or object store you control.

Every deployment has a page of its own with its health, its address, its repository and branch, our pipeline steps and the build output for each run — newest first. When a deployment fails, the build log is the thing to read.

Deleting your account #

Billing ends with a Danger zone, and Delete account is there. The dialog it opens lists every project you still have and says what will happen. Deleting needs two things from you: ticking Terminate these projects (when you have any), and typing your GitHub login.

  1. Each project is terminated, one after another, exactly as the Terminate button does it. If one cannot be terminated, everything stops there: your account is not deleted, the dialog names the project and the reason, and you can try again.
  2. A paid plan is cancelled immediately. You are not charged again, and the rest of the current period is not refunded. A card you verified for the free trial is released too.
  3. Your plan, connected apps, API tokens, deploy keys and settings are deleted, and you are signed out everywhere.

If a project is still starting, suspending or terminating, wait for it to settle first. If a project was created after you opened the dialog, nothing happens and the dialog shows the list again: nothing is terminated that you did not see.

This cannot be undone

Signing in again later starts a new account, and a deleted account does not get another free trial. We keep a record that the account was deleted and what was done to it, and nothing of its content.

What is deleted, what is kept and for how long is set out in the Privacy Policy.

Our GitHub App, if you installed it, lives on GitHub and is yours to remove. The page you land on after deleting links to it; you can also find it under Settings → Applications on GitHub. If you added a deploy key to a private repository, remove it from the repository's settings too.

Isolation #

Each deployment is its own project, holding one application. Your environment variables, build logs, deploy key and webhook secret belong to that project. Nobody else can read them or act on it, and neither can your own other deployments.

None of it has a sign-in of its own. This dashboard is the only panel: the deployment page is where you see health and build logs, redeploy, suspend, terminate and set up push to deploy. There is no second control panel to learn, and no second password to keep.

The private network is not a security boundary

On managed hosting your container shares a host and a Docker network with other tenants'. Treat anything it listens on as reachable: authenticate it, or bind it to the port we publish and nothing else. Do not run an unauthenticated admin endpoint or database on the assumption that only your own containers can see it.

Your own VPS is yours alone, so this does not apply there.

Push to deploy #

Every application gets a webhook URL and a secret, shown on the completion screen and the deployment page. Add them to the repository under Settings → Webhooks → Add webhook and every push to the deployed branch rebuilds and redeploys.

FieldValue
Payload URLFrom the deployment page
Content typeapplication/json
SecretFrom the deployment page
EventsJust the push event

Nothing needs enabling server-side: the endpoint verifies an HMAC against the secret and rebuilds. We do not add the hook for you — that needs write access to your repository settings, a much larger grant than this feature is worth. Installing the GitHub App does the same job without the manual step.

Only pushes to the deployed branch rebuild. Pushing to a different branch does nothing, which is usually what you want and occasionally the reason a deploy “did not happen”.

The MCP server #

The same platform, for agents. The server is at https://ordokit.dev/mcp — JSON-RPC 2.0 over Streamable HTTP. The MCP page carries the full specification, generated from the live tool registry so it cannot drift.

Endpointhttps://ordokit.dev/mcp
TransportStreamable HTTP — JSON-RPC 2.0 over POST
AuthOAuth sign-in with GitHub; for scripts, Authorization: Bearer omcp_…
Specificationhttps://ordokit.dev/mcp.md
Token checkhttps://ordokit.dev/mcp/whoami
OAuth metadatahttps://ordokit.dev/.well-known/oauth-protected-resource

A connected agent acts as the GitHub account that owns your deployments. An MCP call is the same actor as a click: same quota, same ownership rule, same audit row. An agent can manage a deployment you made in the browser, and the reverse.

Connecting an agent

Give your agent the address https://ordokit.dev/mcp. It asks you to sign in: your browser opens on our site, you sign in with GitHub and approve it on the consent page, and it connects. There is no token to copy. Settings → Connect an agent in the dashboard has the steps for each client with the address filled in. Claude, Cursor and VS Code also take a one-click link that opens them with the address filled in; each asks you to confirm before anything is added:

ClientHow
Claude (web, desktop)Add to Claude, or Customize → Connectors → + → Add custom connector, paste the address, Connect
Claude Codeclaude mcp add --transport http ordo https://ordokit.dev/mcp, then /mcp to sign in
Codexcodex mcp add ordo --url https://ordokit.dev/mcp, then codex mcp login ordo
Gemini CLIgemini mcp add --transport http ordo https://ordokit.dev/mcp; /mcp auth ordo if it does not ask
CursorAdd to Cursor, or "url" in ~/.cursor/mcp.json
VS CodeAdd to VS Code, or "type": "http" and "url" in .vscode/mcp.json
opencode"type": "remote" and "url" in opencode.json; opencode mcp auth ordo

The consent page names the app and where it will send you back. An app with published metadata is named by that URL's host — the name inside the document is only its own claim. Any other app is named as it registered, so check the address beside it. On the free trial, it asks you to verify a card first ($0, nothing charged).

Under the hood this is the MCP authorization standard. A request with no token gets a 401 pointing at our OAuth metadata; the client registers itself or presents published metadata, and uses PKCE. Access tokens last an hour. Refresh tokens last sixty days, work once, and the client renews them itself. Tokens are issued only for https://ordokit.dev/mcp.

Connected apps

Settings → Connected apps lists every agent you have approved, with when it connected and was last used. Disconnect ends its access at once; connecting it again means signing in again. An app you have not used for sixty days is disconnected by itself, and deleting your account removes them all.

API tokens, for scripts

For scripts and CI, where a browser sign-in is not possible, mint a token under Settings → API access. Tokens start with omcp_ and are shown exactly once: only a SHA-256 hash is stored, so a copy of our database yields nothing usable and the plaintext genuinely cannot be displayed again. Lost it — revoke it and mint another. A token grants the MCP surface and nothing else; it cannot be used to browse the dashboard.

Check the token first. One request, one plain answer:

curl -s https://ordokit.dev/mcp/whoami -H "Authorization: Bearer $TOKEN"

A working token answers "authenticated": true. Then send it as a header on every request; a client that takes a JSON config takes it like this:

{
  "mcpServers": {
    "ordo": {
      "type": "http",
      "url": "https://ordokit.dev/mcp",
      "headers": { "Authorization": "Bearer omcp_REPLACE_WITH_YOUR_TOKEN" }
    }
  }
}

Tools

The usual order for a deployment, and what each call 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.

ToolDoes
get_planLimits, and how many of your slots are in use
suggest_aliasFree addresses for a repository name
check_aliasWhether a subdomain is free
inspect_repositorySuggests the container port, with evidence
suggest_dockerfileWrites a Dockerfile and .dockerignore for a repository that has none, to commit
review_dockerfileOptional recommendations for an existing Dockerfile, with an improved copy where the fix is mechanical
scan_repositoryScreening findings and a capacity estimate
create_deploymentDeploys; returns a job_id
get_progressSteps, percentage and status for a job
list_deploymentsEverything you own, with live state
get_deploymentOne deployment in detail
get_logsPipeline steps and the build output
start_deploymentRedeploys a suspended one
suspend_deploymentStops the container, keeps everything else
terminate_deploymentDestructive. Removes it and frees the address

Four further tools — list_all_deployments, reconcile_report, read_audit and user_timeline — exist for operators and are read-only. They are absent from tools/list for everyone else, rather than present and refused.

Some results carry text we did not write

Build output, other tenants' chosen names and errors from the infrastructure underneath reach a model's context verbatim, which makes them a route for injected instructions. Those results are labelled with their source rather than sanitised: the text opens with Source: third-party. and fences the payload between --- begin third-party content --- markers, and the structured form carries "_source": "third-party" and a _source_note. Anything inside those markers is quoted material written by other people, not by Ordo Kit.

What it will not do

Three limits are deliberate, and each has a test that fails if a later change undoes it.

  • Bring-your-own VPS is not exposed. create_deployment pins the target to managed hosting and offers no parameter for a server address or an SSH key. A JSON field asserting consent is not a person agreeing to root access, and the audit record would say a human agreed when none had.
  • Secrets are never returned. Not the webhook secret. 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 dashboard.
  • Operator tools are read-only. Removing another tenant's project stays where a person confirms it.

Troubleshooting #

Grouped by where the run stopped. The progress view names the step it failed on, and the deployment page carries our pipeline log alongside the build output — between them they usually name the cause outright. If they do not, the Support page says how to reach us and what to include.

Sign-in

Subscribed, but still asked to choose a plan

Deploying opens when the payment provider confirms the subscription, which it does by webhook, usually within seconds of the checkout. The Billing page picks it up on its own; if it has not after a minute, reload it.

Signed out unexpectedly, or asked to authorise GitHub again

Sessions issued before accounts moved from logins to GitHub numeric ids are dropped rather than guessed at, because a login is not an identity — it can be renamed and reclaimed. For an account that has already granted access this is a redirect and nothing more.

Being signed out after every restart of a self-hosted instance is a different problem: SECRET_KEY is unset, so a new one is generated at start-up and every previously issued session becomes invalid.

Repository and build

“Repository not found or not public”, or “has not been given access to it”

GitHub answers a private repository we have not been granted, a typo in the owner or name, and a repository that does not exist with the same 404, on purpose. Check the address and branch. If the repository is private, install the app on it from the wizard (Private repositories); if the app is already installed, check that this repository is among the ones it was given.

“Your GitHub account does not have access”

The app is installed on the repository, but the account you signed in with cannot read it. Access follows GitHub’s own: ask an admin of the repository to add you, then reload.

The deploy key check says “does not recognise this key yet”
  • Not added yet, or not saved. GitHub accepts it the moment it is saved; check again.
  • Added to your account instead of the repository. The check says so by name. A key on your account would give us every repository you can read, so it is refused — remove it from Settings → SSH keys and add it under the repository’s Settings → Deploy keys.
  • Added to a different repository. A deploy key belongs to exactly one; the check names the one it found.
A push did not redeploy

Pushes rebuild only running deployments of the pushed branch, and only after the commit passes screening — a commit that is refused is not built, and the site keeps serving the last good one. Check the deployment page shows push-to-deploy as on, which needs the app installed on the repository.

“Only GitHub repositories are supported”

GitLab, Bitbucket, Codeberg and self-hosted Git are not accepted. A reference carrying credentials (https://user:pass@…) is also refused rather than stored — remove them from the URL.

The screening step refused the repository

A blocking finding was matched: a miner, a reverse shell, Docker socket access, a privileged container or a host-root mount. The panel names what was found and where. There is no override — remove the code and screen it again.

Warnings are different: they are advisory and do not stop a deployment. See Security screening.

The build failed

The pipeline watches the build queue and fails with the reason the builder announced, so the deployment page has the cause. Common ones:

  • Build context. Paths in COPY are relative to the build context, not to the Dockerfile's directory. Ordo Kit works the context out for you: the folder, from the Dockerfile's own up to the repository root, in which every file it copies exists. A file it copies that exists in none of them — often a lockfile that was never committed — is reported before anything is created. Set the context under Advanced only to override that.
  • The build needs a secret. Build-time secrets are not supplied, and environment variables cannot be set here yet; the build has to succeed without one.
  • Out of memory during the build. Builds run on the host outside any cgroup, so this is genuine exhaustion, not the plan's runtime limit.

A build that exceeds the build timeout is reported as still running rather than as failed, because it usually is.

It deployed, the certificate is valid, and the site returns 502

This is almost always one of two things.

Wrong port
The container listens on a port other than the one declared. Run inspect_repository or redeploy with the right one.
Bound to loopback
The server inside the container listens on 127.0.0.1, which the proxy cannot reach. Bind 0.0.0.0.

The pipeline checks for exactly this: a deployment is not complete until the site answers with a non-5xx status, because a valid certificate in front of a 502 is not a working deployment.

The container keeps restarting

Check memory first. The plan's limit is a hard cgroup ceiling and a container that exceeds it is killed outright, which reads as a crash loop rather than as an out-of-memory error. Swap is pinned to the same figure deliberately, so there is no thrashing period to disguise it.

Restarts are capped, so a crash loop stops rather than running for ever.

Addresses and DNS

“does not resolve yet” or “points to …, not …”

The check asks public resolvers, not this server’s, so a record you have just added may take a few minutes to appear — how long depends on your provider. If it names addresses you did not add, the record is proxied (turn the proxy off for it) or an older record is still there (remove it). The message always ends with the exact record it expected.

“also has an IPv6 (AAAA) record”

This service answers on IPv4. A client that prefers IPv6 — including Let’s Encrypt — would follow the AAAA record elsewhere, so remove it for this hostname.

“That address is taken”

Somebody holds it, possibly you — a suspended deployment still holds its address. An address is released only when nothing remains of what held it: a terminated or failed deployment. Terminate the old one, or pick another name.

The address does not resolve, or resolves to the wrong place

On managed hosting DNS is handled for you; if a brand-new subdomain does not resolve for you immediately, a resolver is caching the earlier NXDOMAIN. Try a different resolver before treating it as a fault.

On a server you brought, the record must point at your machine, and it must be in place before the certificate step runs:

dig +short <alias>.ordokit.dev

If that returns nothing, or an address that is not your server's, the certificate will fail for a reason that looks like TLS and is actually DNS.

The site answers on my own machine but not through the address

The proxy takes ports 80 and 443. If something else on the host was already bound to them, it did not start, and nothing is served no matter how healthy the container is:

ss -lntp | grep -E ':(80|443)\s'
docker ps

Our reverse proxy should be among those containers and holding both ports. If something else has them, it is not running.

A cloud firewall or security group that does not allow 80 and 443 inbound produces the same symptom from outside while everything looks correct from inside.

Certificates

The certificate is “pending” on the completion screen

Issuance had not finished within the wait, which is reported as pending rather than as failure — the deployment exists and the certificate is usually seconds away. Reload the site shortly afterwards.

The wait requires two things, both deliberately: a TLS handshake that succeeds with verification enabled, and a non-5xx response from the site. A handshake that only succeeds with checks disabled tells you nothing a browser would accept.

The certificate never arrives

Work through these in order:

  1. Does the name resolve to the right host? Validation is over HTTP on port 80; a record pointing elsewhere cannot be validated.
  2. Is port 80 reachable from the internet? Redirecting or blocking it breaks the challenge. Firewalls and security groups count.
  3. Is the proxy running? On a brought server, if something else holds 80 or 443 the proxy never started.
  4. Have you exhausted a rate limit? See below.
“too many certificates already issued”

Two different Let's Encrypt limits produce this.

Five per exact hostname per week
Deploying and terminating the same alias repeatedly exhausts it, and the site stays on an untrusted certificate until the window rolls over. When testing, use a fresh alias each time.
Fifty per registered domain per week
An operator-level concern. Some free-domain suffixes are not on the Public Suffix List, so Let's Encrypt treats the suffix itself as the registered domain and every customer of that provider shares one quota — deployments then fail because of strangers' usage. The fix is a domain you control, or a wildcard certificate for the zone issued over DNS-01, so that one certificate covers every alias.

SSH and your own VPS

The server is reported unreachable

The SSH connection itself failed. In rough order of likelihood:

  • The key's public half is not in authorized_keys for the user you named. Confirm from your own machine first:
    ssh -i ./that-key -o IdentitiesOnly=yes root@<your-server> true
    IdentitiesOnly matters — without it your agent may offer a different key that works, and you will have proved something other than what you meant to.
  • The wrong half was pasted. The private key is wanted, the one beginning -----BEGIN OPENSSH PRIVATE KEY-----, not the .pub file.
  • The key is passphrase-protected. There is nowhere to type a passphrase; use an unencrypted key created for this purpose.
  • Truncated on paste. The whole block is needed, header and footer lines included, with its trailing newline.
  • The user cannot act. A non-root user needs passwordless sudo; otherwise name root.
  • Firewall. Port 22 must be reachable from here.
  • bash is missing. On a minimal image this reads as sh: bash: not found and the server is reported unreachable even though SSH worked perfectly.
“Prerequisites (curl, jq) are not installed”

Validation reached the host and found it under-equipped, so the server is marked unusable. Install them and deploy again:

apt-get update && apt-get install -y bash curl jq   # Debian/Ubuntu
apk add --no-cache bash curl jq                      # Alpine
“Server is not functional”

A newly registered server is validated asynchronously — Docker checked, proxy started — and a deployment dispatched before that finishes fails immediately with this. The pipeline waits for it on your behalf, which is what the Preparing your server step is, and that step is shown only for brought servers.

If it times out there, the host never became usable: check the Docker daemon is running and that ports 80 and 443 were free for the proxy.

“Private key already exists”, or a server that is refused

A key is deduplicated by content. Deploying a second project onto a machine you already lent us therefore reuses the existing registration rather than adding the key again — that case is handled, and needs nothing from you.

A refusal means one of three things: the address is registered to somebody else, it was registered outside this service, or it is our own managed host. None of them says whose machine it is, because that would answer a question nobody should be able to ask by typing addresses into a form.

The managed host is refused before ownership is even considered. Attaching a “brought” deployment to it would put a tenant in a position to stop the proxy for everybody on it.

Something of ours is still on my machine after terminating

Termination stops the agents we started, removes what they leave behind, and deletes our copy of your key. If the machine was unreachable, the deployment is still removed: failing a termination over an unreachable server would strand the record. Whatever was left behind goes to the audit trail.

That audit record names every resource removed and every one that could not be. Work from it rather than guessing. We install four things: a reverse proxy container, a monitoring agent container, one Docker network and one configuration directory. Ask us for the exact names on your server.

docker ps -a
docker network ls

Nothing else of ours is on the host. There is no prune and nothing is matched by pattern, so your own containers and volumes were never candidates for removal.

If two projects were running there, this is expected until the last one is terminated: the proxy is shared, and removing it for one would take the other down.

MCP clients

The client gets 401, or says it needs an API token

Every request needs credentials, the handshake included, and one without is answered with HTTP 401. A client set up with an API token that still gets 401 is not sending a usable one. The server names which failure it is:

MessageMeaning
No Authorization header was sent The header never left the client — configured where the client is not reading it, or dropped by the shell.
Must read Authorization: Bearer <token> The scheme is missing. 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 the quickstart, pasted unedited.
Not recognised Revoked, or from a different instance.

Two checks, in order:

curl -s https://ordokit.dev/mcp/whoami -H "Authorization: Bearer $TOKEN"
claude mcp get ordo

If the first says true, the token is fine and the problem is in the client. The second confirms the header is attached to the server entry rather than merely typed at the shell when it was added.

A tool returned an error instead of failing the call

Two kinds, and they mean different things.

JSON-RPC error
The request was malformed or not permitted: bad JSON (-32700), not a valid request (-32600), unknown method (-32601), unknown tool or bad arguments (-32602), missing or revoked token (-32001).
Tool error
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.
An agent asked to use my own VPS and was refused

Working as intended. create_deployment has no parameter for a server address or an SSH key at all. Use the web dashboard, where the access terms can be read and agreed to by a person.

An agent could not read the webhook secret

Also working as intended. The webhook secret does not appear in any MCP response. Read it from the deployment page in the dashboard.

Rate limits

HTTP 429, or “slow down”

Ours, not Let's Encrypt's. The response carries Retry-After — wait that long rather than retrying in a loop. Rate limits lists every class.

Agents: poll get_progress every few seconds, not continuously, and keep to 3 progress streams at once.

Quota, capacity and holds

“You have reached your deployment limit”

Each account may hold as many live deployments as its plan allows (1 on Free trial, 10 on Starter, 100 on Full), and a suspended one still counts — it holds its address, image and project. Terminate one to free the slot. get_plan, or the plan line in the wizard, reports what is left.

“Our managed hosting is full for now”

Every place on our managed hosting is taken, and you are on the waitlist; the message gives your place. We email the next person in line when a place opens, so the address you gave in the wizard matters. See Capacity and the build queue. A deploy to your own server is not affected.

A deploy says “Waiting for a free build slot”

Deploys build a few at a time, and yours is in line; the number is its place. It carries on by itself, and you can leave the page and come back. If it waits too long it stops with nothing created.

“This site is paused while we review it”

The phishing check found strong signs on the site, so it was stopped for a person to look at. Nothing was deleted. It cannot be started until the review is done; if it was a mistake, write to us from the Support page.

A deployment is stuck in a transitional state

A run whose process died mid-flight, usually a restart, is picked up by reconciliation. It waits first, long enough that two teardowns cannot remove the same resources. Give it that timeout before treating it as stuck.

A teardown that could not prove the address stopped answering keeps its record deliberately, marked failed with the reason, because deleting it would leave nothing to report the failure against.

HTTP API #

The dashboard is a thin client over these. They authenticate with the session cookie from GitHub sign-in; for programmatic access prefer MCP, which is the supported surface and takes a bearer token.

Rate limits

Graded by what a request costs us, so reading is generous and the expensive paths are tighter. These apply to the dashboard, this API and MCP alike.

WhatLimitCounted
Signing in, and the OAuth server30 a minute, 300 an hourper address
Reading repositories and branches30 a minute, 500 a dayper account
Deploying, starting, stopping, minting tokens10 a minute, 60 an hourper account
Checkout, plan changes, the portal10 a minute, 30 an hourper account
Everything on /mcp120 a minuteper account
Everything else300 a minuteper address

Over a limit you get 429 with Retry-After and the RateLimit headers. Honour them rather than retrying in a loop. Progress streams are capped at 3 at once per account, so close one before opening another.

Routes

RoutePurpose
GET /api/meThe signed-in account and whether it is an operator
GET /api/planLimits and remaining slots
POST /api/detectSuggest the container port for a repository
POST /api/scanScreen a repository
GET /api/consentThe VPS access terms and their version
GET /api/alias/<alias>Is an address free
POST /api/provisionStart a deployment; returns a job id
GET /api/progress/<job>Server-Sent Events for a running job
GET /api/deploymentsYour deployments, with live state
POST /api/deployments/<alias>/<action>Start, suspend or terminate
GET /api/deployments/<alias>/logsPipeline steps and build output
GET /api/deployments/<alias>/credentialsCompletion details, including the webhook secret — owner only
GET /api/tokensYour API tokens
GET /api/oauth/grantsYour connected apps
POST /mcpThe MCP server — OAuth access token or API token
GET /.well-known/oauth-authorization-serverOAuth metadata: authorize, token, register, revoke
GET /mcp/whoamiDoes this token work
GET /mcp.mdThe generated MCP specification
GET /healthzLiveness

Glossary #

Alias
The subdomain a deployment is published at: <alias>.ordokit.dev. Unique across the instance, and released only when nothing remains of what held it.
Deployment
One repository, published at one alias, in a project of its own. The unit that quota, ownership and termination all act on.
Managed host
Our infrastructure. The default target, and the only one available to agents.
Brought server
A machine you own, registered over SSH. Ours to clean up, never ours to destroy.
Screening
Security scanning at intake. Blocking findings refuse a deployment; warnings do not.
Capacity
An estimate of whether a project fits the plan. Advisory, always — it never blocks.
Job
A running deployment or teardown, identified by a job id, watchable over SSE in the browser or by polling get_progress.
Operator
An administrator of this instance. Sees every deployment and the audit trail; cannot read your webhook secret.