> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usepatchwork.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Choosing an integration

> Relay or direct. The difference is who calls us — your backend, or your users' browsers.

Both modes run the same agents, produce the same traces, and call the same patches. They differ in one thing: **who holds the credential and makes the request.**

You do not declare a mode. The form of the bearer token selects it — a JWT is direct, anything else is a relay API key.

Both are ways to put the agent *in your product*. If what you want is your users reaching the agent's tools from their own AI client, that is a third door with its own page: [MCP export](/guides/mcp).

## The comparison

| | Relay | Direct |
| - | - | - |
| **Who calls Patchwork** | Your backend | The browser |
| **Credential** | Workspace API key (`sk_…`) | A short-lived JWT your backend signs |
| **Subject** | `Patchwork-Subject` header, asserted | The token's `sub` claim, verified |
| **You must host** | A mint endpoint, once the agent calls your backend | A keypair, a JWKS document, and a mint endpoint |
| **Setup** | Minutes | An hour or so |
| **Latency** | One extra hop through you | Browser straight to us |
| **Good for** | Slack, WhatsApp, email, cron, your own API | A chat UI inside your product |

## Start with relay

Relay is the shorter path and the one the [Quick start](/quickstart) uses. Your backend already authenticates your users; it makes the call and tells us who it is acting for. Nothing to host to begin with — though the moment the agent calls *your* backend, you host a mint endpoint (see [below](#when-the-agent-calls-your-backend)).

Choose relay when the channel is not a browser you control — a Slack bot, an inbound email handler, a nightly job — or when you want your backend in every path for logging, policy, or rate control.

```
Slack / WhatsApp / your API
        ↓
Your backend  →  Patchwork      Bearer sk_… + Patchwork-Subject
```

[Relay integration →](/guides/loom-relay)

## Move to direct for a product UI

Direct removes the hop: the browser talks to us with a token your backend signed and we verified. Your workspace key never leaves your servers, and the token expires in minutes.

The cost is infrastructure. You generate a keypair, publish a JWKS document, and add an endpoint that mints tokens for signed-in users.

```
browser  ── mint ──▶  your backend      signs with your private key
browser  ── Bearer <jwt> ──▶  Patchwork  verifies with your public key
```

[Direct integration →](/guides/loom-direct)

## What actually differs at runtime

Only the provenance of the subject. In relay we trust what your backend asserts; in direct we verify a signature. Everything downstream — thread scoping, memory, traces, gates — behaves identically.

<Warning>
  The one asymmetry worth knowing: a relay API key can assert **any** subject in your workspace, so it must never reach a browser or a mobile client. A direct session token can only ever be the subject it was signed for. See [Subjects](/guides/subjects#how-it-reaches-us).
</Warning>

## You can run both

They are not exclusive. A product with a web chat and a Slack bot uses direct for the first and relay for the second, against the same agent. Threads stay separate because the subjects differ — `user_9f2` and `slack:T04AB:U0APP` are different partitions.

## When the agent calls your backend

This is where relay stops being "nothing to host." When a wired patch calls an endpoint you run, the egress request carries two things: a `Patchwork-Signature` over your request secret — [verified the same way](/guides/signing) in both modes — and a short-lived **subject token**, so your endpoint knows who it is acting for.

Where that token comes from is the difference:

* **Relay** — Patchwork holds no token, so it mints one by POSTing to your connection's [mint endpoint](/guides/mint-endpoint). That endpoint is the one thing a relay integration hosts.
* **Direct** — Patchwork reuses the session token the browser already presented; no extra call.

So a relay integration hosts nothing until the agent needs *your* backend — and a mint endpoint from then on.

## The third door: their own AI client

Relay and direct are both your product calling us. [MCP export](/guides/mcp) is the other direction: a published agent's tools become available inside Cursor, Claude or ChatGPT, and your user's own client makes the call.

It is not a mode you choose between — you can run it alongside either of the above, on the same agent. The credential is neither a key nor a session token but an OAuth grant the user holds, and the one thing you host is a [login bridge](/guides/mcp-login-bridge) so they authenticate with you. The run, the trace and the signed egress call to your backend are identical to relay.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.