Skip to main content

Hosting & Runtime

Where does your integration's code actually run? ORQO supports four runtimes, and the right answer depends on who built the code and whether it's been reviewed. This page is the developer's map: read it before you decide what to build.

The Four Runtimes​

RuntimeWhere the code runsWho can put code thereWhat it costs you
ORQO-hosted (vetted)ORQO's shared adapters containerORQO platform team, or Integration Builder (which only emits from templates ORQO authored)Nothing. ORQO covers infra.
ORQO-hosted (curated MCP)ORQO's curated-mcp-services container (coming Phase 3.4)Third-party MCP packages ORQO has explicitly reviewed, version-pinned, and added to the catalogNothing for the install; usage is metered (compute)
Bridge-hostedYour own machine, via the ORQO Bridge desktop appAnyone — you write code, ORQO routes traffic to your BridgeYour machine has to be on; no per-call infra cost
Self-hosted (external)Your own server / droplet / k8sAnyone — ORQO calls your registered manifest URLYour infra cost; you operate it

The Trust Boundary​

ORQO only hosts code we've reviewed. That's the architectural rule. It's why third-party developer code never lands on the shared adapters container.

Type of codeWho reviewed itWhere it can run on ORQO
Platform adapter (we wrote it)ORQO teamORQO-hosted (vetted)
IB-built org adapter (template-generated)ORQO team (we authored the templates Integration Builder fills in)ORQO-hosted (vetted)
Curated MCP package (e.g. Filesystem MCP)ORQO team (we evaluated the package and pinned a version)ORQO-hosted (curated MCP) — Phase 3.4
Custom developer code (your own adapter or MCP)Not reviewed by ORQONot on ORQO infra. Run it on Bridge or your own server.

This is a deliberate simplification. It means ORQO doesn't take on the supply-chain risk of arbitrary npm/pip/git packages or custom developer code — and you, the developer, get full control of where your code runs without going through a long review cycle.

Picking Your Runtime​

Are you building it yourself, or letting Integration Builder build it?
├─ Letting Integration Builder build it
│   → ORQO-hosted (vetted). Done. IB packages, ships, and runs the adapter
│      on the shared sidecar. You just provide credentials.
│
└─ Building it yourself
    │
    Is it a curated MCP package on ORQO's catalog?
    ├─ Yes → click install. ORQO-hosted (curated MCP). Phase 3.4.
    │
    Is it a one-off you'll iterate on locally?
    ├─ Yes → Bridge-hosted. Edit-save-test loop on your machine; ORQO
    │         routes traffic to your Bridge. Best for development AND for
    │         small-scale production where you don't want to run a server.
    │
    Will it serve real production traffic with uptime requirements?
    └─ Yes → Self-hosted (external). Stand up a Docker container on
              your own droplet/k8s/Cloud Run/wherever. Register the
              manifest URL in ORQO. ORQO calls your URL; you operate it.

What Each Runtime Looks Like in Practice​

ORQO-hosted (vetted)​

This is the path Integration Builder uses by default. You don't build the adapter yourself — you describe what you want in IB conversation and IB generates the source from a template, packages it as a tarball, uploads it to ORQO's storage, and a small loader inside the shared adapters container picks it up and serves it within ~10 seconds.

Trade-offs:

  • ✅ Zero ops. ORQO runs it.
  • ✅ Always-on, no machine you have to keep up.
  • ✅ Already on the same network as Doorkeeper, the engine, and the workflow runner — no extra latency.
  • ⚠️ Limited to what IB can scaffold from its templates: Sinatra-based Ruby adapters with the standard channel + MCP shape. Power users who want full control should use Bridge or self-hosted.

ORQO-hosted (curated MCP) — Phase 3.4​

For third-party MCP servers that ORQO has reviewed and added to the catalog. You'll see a "click to install" UI for packages like Filesystem MCP, GitHub MCP, Postgres MCP, etc. ORQO's curated-mcp-services sidecar runs a separate process per package (since most are non-Ruby — Node, Python — and can't share a Ruby Puma).

Trade-offs:

  • ✅ One-click install for popular MCP servers.
  • ✅ ORQO handles updates + version pinning.
  • ⚠️ Catalog is curated — if your favorite MCP isn't on it, file a request or run it on Bridge.
  • ⚠️ Compute is metered (cpu_seconds, memory) — see your plan's allowance.

This runtime is not yet live. Until it ships, run third-party MCPs on Bridge or your own infra.

Bridge-hosted​

ORQO's Bridge is a small desktop app (Tauri) that runs on your machine and exposes a tunnel to ORQO over a websocket relay. When you build an adapter, you point it at your local Bridge as the runtime; ORQO routes traffic to your machine through the relay.

Trade-offs:

  • ✅ Full control. Any language, any package, any setup.
  • ✅ Fast iteration loop — edit your code, save, ORQO sees the new version.
  • ✅ Your code, your machine, your data — never leaves your environment except via the explicit traffic ORQO routes.
  • ⚠️ Your machine has to be on for the adapter to respond. If your laptop sleeps, the adapter is down.
  • ⚠️ Best for development, demos, low-volume production where uptime isn't critical.

See the Bridge documentation for setup. (Bridge runtime registration in the Developer Portal is Phase 5; today Bridge is most useful for development and for ad-hoc integrations.)

Self-hosted (external)​

You build your adapter as a normal HTTP service in any language, deploy it to your own infrastructure, and register its manifest URL in ORQO. ORQO calls your service over the public internet (or your VPC, if you set that up).

Trade-offs:

  • ✅ Full control over uptime, scaling, monitoring, secrets.
  • ✅ Real production characteristics — auto-scaling, multi-region, etc.
  • ⚠️ You operate it. ORQO doesn't see inside; you handle the runbook.
  • ⚠️ Network latency is whatever the internet gives you (vs. ~zero for ORQO-hosted).

This is the most flexible runtime and the right choice for any developer who wants to ship something serious to the marketplace.

Implications for the Adapter Contract​

The adapter contract is the same for every runtime. Your adapter exposes the same GET /manifest.json, POST /verify-webhook, POST /deliver, POST /mcp etc. regardless of where it runs. The runtime decision affects deployment, not the contract.

Likewise, credentials flow the same way: ORQO injects per-org credentials into request bodies (or via the MCP Authorization header), no matter which runtime serves the call.

What This Means for the Developer Portal​

When you create an integration in the Developer Portal, the publish flow will eventually ask "where will this run?" and offer the four options above. Today (Phase 3.3.5), the portal works for the self-hosted (external) path: you register a manifest URL and ORQO calls it. The "publish to ORQO-hosted" and "publish via Bridge" paths land in Phase 5.

For now: if you want zero-ops hosting, build via Integration Builder (ORQO-hosted vetted). If you want full control, deploy to your own infra and register the URL.