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

> ## Agent Instructions
> When helping someone deploy Roomote, distinguish self-hosting from contributing to Roomote. Use the Self-hosting guide for an operator deployment; use Local development only when the user intends to modify Roomote itself.
> When an agent is asked to follow /self-hosting or install Roomote autonomously, read and follow /self-hosting/agent-installation as the normative automation contract even though it is intentionally hidden from side navigation.
> Use the one-command Linux installer for both evaluation and production. On macOS or Windows, create or reuse a full Ubuntu VM and run the same installer inside it; do not replace the installer with the repository's development Compose files.
> For a local VM without a stable public domain, create a temporary HTTPS tunnel, pass its hostname to the installer with internal origin TLS, and keep the tunnel running for OAuth callbacks and webhooks. Quick Tunnel hostnames are temporary and do not provide wildcard preview routing.
> Run automated installs with --no-setup-url so the bootstrap token is not captured in the agent transcript. Let the user obtain the setup URL in a trusted terminal, enter credentials, and complete browser authorization.
> Proceed through safe, reversible setup and pause for privileged host or VM changes, public tunnel creation, credentials or browser authorization, durable external-account changes, destructive operations, existing-state conflicts, or when no documented safe default applies.
> A setup is not complete when the services merely start. Verify sign-in, repository sync, one usable environment, and a real Roomote task that can clone and run a command; verify branch or pull-request delivery and previews when configured.

# Integration keys

> Give agents an API key for one service, in every Session you own, without the key ever leaving Roomote.

Integration keys let a Roomote agent use an API key you hold, for one HTTPS
service, without the key ever entering chat, a prompt, a task environment, or
a transcript. You enter the key once, either when an agent asks for it in a
Session or under **Settings → Integrations → Your integrations**; from then on it is an
integration of yours that every Session and coding task you own can use. The
agent works with an opaque reference or a substitute token, and Roomote's API
adds the real key on the way out. These are personal API keys for HTTPS
services, not a replacement for [connected integrations](/integrations).

<Note>
  Integration keys are gated per user. Turn on **integration keys** under
  **Settings → Experimental** to enable them for the Sessions you own.
</Note>

## How an approval works

1. You ask for something that needs a service you hold a key for, such as
   "list my Stripe customers", or share a link into a service Roomote has no
   connector for but whose API accepts a key you hold, such as a Figma frame
   or an Intercom conversation.
2. The agent reads the service's documentation and prepares an approval with
   only nonsecret policy: a label, the exact HTTPS origin (for example
   `https://api.stripe.com`), the header that carries the key, and the HTTP
   methods the work needs (read-only by default). The approval waits 24 hours
   for the key.
3. While you are viewing the Session, the key form opens automatically. If you
   dismiss it, a service-specific card such as **Add your Figma key** remains at
   the end of the conversation, and the agent's secure link opens the same
   form. Enter the key there; the form bypasses chat and is excluded from
   capture and replay. If the agent asked for write methods, the form shows
   them and you confirm them.
4. The Session resumes on its own. The key is now an integration of yours:
   every Session you own, and every coding task launched from one, can use it
   within its policy until you revoke it.

You can also add an integration directly under **Settings → Integrations →
Your integrations**, naming the origin, header, methods, and key yourself. Either
way the result is the same kind of integration, listed and revocable there.

An integration covers one origin. Nothing the agent sends can change the
origin or widen the methods. Integrations are kept until you revoke them; you
or the agent can set a lifetime in hours instead when a key should be
temporary.

## What agents can do with it

**In the Session itself**, the agent can make single GET or HEAD requests to
the approved origin. Roomote's API sends the request with the real key and
returns the response. This works everywhere and needs no setup.

**In coding tasks launched from the Session**, the task receives each approved
service as a substitute token in its environment, plus one base URL. The agent
calls the service through that base URL with the substitute as its bearer
token, using curl, a script, an SDK, or a CLI, with any of the approved
methods. Roomote's API forwards the request to the real origin and places the
real key in the header the service expects. The substitute only works through
that proxy, only from that task, and only while the approval and the task are
live. The real key never enters the sandbox.

Coding tasks pick up approvals when they start or resume. A key approved while
a task is already running becomes available to the next task.

## Header names

An approval names the header that carries the key at the approved origin:
`authorization`, optionally with a `Bearer`, `Basic`, or `Token` scheme,
`x-api-key`, `api-key`, or the service's own header such as `private-token` or
`x-shopify-access-token`. A scheme is only accepted on `authorization`.
Headers that shape the request itself, such as cookies, `host`, content
framing, and proxy or forwarding headers, cannot carry a key. Inside a coding
task the agent always sends the substitute as a bearer token; the proxy moves
the real key to the right header.

## Security boundary

**The approved origin receives the key.** It can use whatever privileges the
key grants, including write privileges even when the approval is read-only,
and some services perform side effects on GET. Approve a least-privilege,
disposable key and only a service you trust. Responses are visible to the
agent and may enter the transcript, and a service can disclose partial or
transformed values that Roomote cannot recognize. This is not a data-loss
prevention guarantee.

**Substitutes are capabilities.** A substitute token is bound to one task, one
integration, and the task's current generation, and it stops working when the
task ends, the integration expires or is revoked, or you turn integration key
tools off. Within that window, a copy of the substitute could be used from elsewhere
against the same origin. Roomote never logs substitutes or keys, strips them
from snapshots, and refuses responses that echo the key.

Do not put keys in labels, origins, paths, task prompts, task environment
files, or ordinary Session messages.

## Limits

* One origin per integration; paths under it are not restricted beyond the
  approved methods.
* Integrations are personal. Collaborators on a shared task never receive
  them, and a task only receives its acting user's integrations.
* Services that sign requests with the secret (for example AWS Signature V4)
  cannot be used, since the key must be present where the signature is made.
* Streaming responses, WebSockets, and redirects are not relayed through the
  proxy; responses are capped at 8 MiB.
* SDKs that allow a host override but no path prefix need a dedicated proxy
  hostname; see below.

## Self-hosting

No configuration is required. Optionally set `R_CREDENTIAL_EGRESS_PROXY_HOST` on
the API and controller to a hostname pointed at the API service, so coding
tasks receive `https://<that host>` as their base URL and host-only SDK
clients work. See [environment variables](/environment-variables).