> ## 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.

# HTTP Integrations

> Let agents call approved HTTP APIs while Roomote keeps credentials server-side.

HTTP integrations let Fast sessions and sandbox agents call an API without
receiving its credential. The agent chooses a configured integration, method,
path, and request body. Roomote checks the current actor's access, attaches the
server-side credential, and sends the HTTPS request.

This works through the same Roomote API for every sandbox provider, including
Roomote Cloud, Modal, Docker, E2B, Daytona, Azure, Blaxel, and Box. It requires no
provider-specific networking configuration or proxy service. Existing connected
integration tools remain available and should be used first.

<Warning>
  This is credential mediation, not network isolation. Agents are instructed to
  use the integration tools, but normal sandbox networking remains available.
  It does not remove credentials you independently put in an environment,
  repository, or custom MCP configuration.
</Warning>

## Configure the deployment

Operator-managed integrations are opt-in and configured by the deployment
operator, not through the curated integration connection dialogs. The same API
broker also serves [Session secrets](/session-secrets), which are individually
approved by the Session owner and do not require an operator manifest.

For Session grants only, leave `R_HTTP_INTEGRATIONS_ENABLED` unset or `false` and
`R_HTTP_INTEGRATIONS_CONFIG_PATH` unset. No per-service credential environment
variables are needed on the Roomote API: the owner saves each key in the secure
Session form. Existing deployment encryption and job-signing configuration remain
required. See [dynamic-only setup](/session-secrets#dynamic-only-setup).

1. Create a JSON manifest on the API server and mount it read-only. Use narrow
   paths and least-privilege upstream credentials.
2. Set `R_HTTP_INTEGRATIONS_ENABLED=true` on the Roomote control-plane services
   that run the API, resolve task configuration, or execute Fast sessions
   (including web and background workers). Set
   `R_HTTP_INTEGRATIONS_CONFIG_PATH` to the manifest's absolute path on the API
   server only.
3. Supply each referenced credential environment variable to the API process
   only, using your deployment's secret management. Do not add it to task
   environment variables or sandbox images.
4. Restart the affected services and start a new session or refresh the task's
   integration configuration. An enabled API refuses to register the feature
   if its manifest is missing or invalid.

An explicitly enabled but invalid operator configuration never falls back to
dynamic-only mode. Disable operator mode intentionally if only Session grants
are wanted.

Example manifest, using a placeholder domain and Roomote user ID:

```json theme={null}
[
  {
    "id": "inventory",
    "description": "Read inventory items",
    "origin": "https://api.example.com",
    "rules": [
      { "method": "GET", "pathPrefix": "/v1/items" }
    ],
    "credential": {
      "header": "Authorization",
      "valueEnv": "R_HTTP_INTEGRATION_INVENTORY_TOKEN",
      "prefix": "Bearer "
    },
    "allowedUserIds": ["replace-with-roomote-user-id"]
  }
]
```

The manifest names the environment variable; it must not contain the actual
credential. `prefix` is optional. For an API-key header, use its header name and
omit `prefix` unless the upstream API requires one.

## Access and request rules

* `allowedUserIds` restricts both discovery and calls to those Roomote user IDs.
  If omitted, the integration is shared with **all active human members** of the
  deployment. An empty list is invalid; remove the entry to disable it.
* Fast uses its acting user's authentication. Sandbox requests use their
  run-scoped token and the task's current server-recorded actor, not the token's
  original user. Actorless service-principal runs and external Roomote MCP OAuth
  clients cannot use this endpoint.
* `origin` must be an HTTPS origin, without a path, query, fragment, or userinfo.
  Private, loopback, metadata, and other unsafe addresses are rejected, including
  unsafe DNS answers at connection time. There is no private-network exception.
* Each rule pairs a method with a path prefix. `/v1/items` permits `/v1/items`
  and `/v1/items/123`, but not `/v1/items-other`. A `/` prefix permits every path
  on that origin, so avoid it unless that scope is intentional.
* Available methods are `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, and `DELETE`.
  Mutating methods must be explicitly allowed. A method label is not proof that
  an upstream operation is read-only; check the API's semantics.
* Query parameters are allowed in the request path and are not independently
  restricted by the manifest. Do not expose endpoints that use a query or body
  parameter to select arbitrary destinations, execute arbitrary operations, or
  expand the configured authority.
* Agents cannot supply arbitrary headers, override authentication, choose an
  unregistered origin, or follow an upstream redirect. Redirect responses are
  rejected, including same-origin redirects.

These deployment-managed credentials are separate from existing user-linked
OAuth connections. This feature does not import their tokens, refresh OAuth
tokens, or replace the inference gateway. Use an existing integration for those
connection flows.

## Use an integration

Ask Roomote to list the available HTTP integrations. The `_roomote_http_integrations`
server exposes `list_integrations` and `integration_request` to both Fast and
sandbox agents. Listings contain permitted origins and rules, never credential
values or environment-variable references.

If an environment or deployment already defines an MCP server named
`_roomote_http_integrations`, sandbox tasks preserve that server and skip the HTTP
integrations broker with a warning. Rename the operator-defined server to receive
both. Environment definitions still take precedence over deployment definitions;
Fast sessions are unaffected.

For example, a request after listing `inventory` is:

```json theme={null}
{
  "integrationId": "inventory",
  "method": "GET",
  "path": "/v1/items?limit=10"
}
```

For a permitted write, `body` is a string and `contentType` can be
`application/json`, `text/plain`, or `application/x-www-form-urlencoded`.
For `GET` and `HEAD`, omit `body`, pass `null`, or pass an empty string. These
representations are sent without a body or content-type header; nonempty bodies,
including whitespace, are rejected. `contentType` may also be omitted or `null`
and is ignored for these bodyless methods. Responses contain `status`, a `body`
string, and only the permitted response headers: `content-type`, `retry-after`,
and `x-request-id`. Non-redirect upstream errors can be returned as responses;
the agent should check `status` rather than assume a completed call succeeded.

## Limits and credential safety

Requests have a 30-second timeout, a 1 MiB UTF-8 request-body limit, and a 2 MiB
outer MCP request-envelope limit. Responses are buffered up to 2 MiB and must be
UTF-8 text or JSON, except for empty `HEAD` or `204` responses. Binary downloads,
streaming APIs, WebSockets, cookies, custom request headers, and multi-header
authentication are not supported.

Concurrency is limited to four requests per run or user and 32 total per API
process. This is not a deployment-wide quota or upstream spending limit.

Roomote rejects responses containing the literal credential or full injected
authorization value in their body or returned headers. This is **not general
data-loss prevention**: encoded, transformed, split, or unrelated secrets may
still appear in responses. Never authorize credential-echo, diagnostic,
token-management, arbitrary proxy, or similar endpoints. Use an upstream
credential whose own permissions match the intended integration scope.

The manifest is loaded at API startup. Restart the API after changing rules,
access lists, or entries. Credential values are read from the API process
environment per request; updating deployment environment variables normally
requires restarting or recreating that process. Apply configuration and secret
changes to every API replica.

To disable operator-managed integrations, set `R_HTTP_INTEGRATIONS_ENABLED=false`
on the same control-plane services and restart them. The broker remains available
for owner-approved Session grants, but no operator manifest entries are loaded.
This does not cancel an already-running operator request. Revoke Session grants
separately in the Session UI; those changes are checked live before dispatch and
before returning upstream responses, without reloading the manifest or restarting.

## Verify and troubleshoot

Use a staging API and a narrowly scoped test credential first. Verify that an
allowed actor can list and call an approved path, a different actor cannot see
or call a restricted integration, and a disallowed method or path is refused.
Confirm that the upstream receives authentication without printing its value.

If a call is rejected, check the manifest ID, current actor, method, path,
credential environment-variable presence, upstream content type, and response
size. Missing credentials, TLS or DNS failures, blocked destinations, redirects,
timeouts, and unsafe responses fail closed with a generic error. Error messages
deliberately omit credentials and outgoing query details. There is no fallback
that gives the agent credentials or bypasses request authorization.