Skip to main content
HTTP integrations let 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 Modal, Docker, E2B, Daytona, Azure, Blaxel, and Box, as well as deployment-managed sandboxes. It requires no provider-specific networking configuration or proxy service. Existing connected integration tools remain available and should be used first. For a general “connect to X” request, Roomote checks the read-only built-in catalog first, including disconnected providers. It uses that provider’s native setup path when present, then checks for an official remote MCP server, and uses HTTP integrations or an integration key only when neither applies. An MCP that requires provider approval, an allowlisted client, a beta or plan, or a token you hold is offered as an option rather than treated as immediately connectable. An explicit request for direct API access keeps that choice. Discovery does not start setup, and permission denials or pending or denied authorization are not bypassed.
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.

​
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 Integration keys, which are individually approved by the session owner and do not require an operator manifest. For integration keys 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 Integration keys self-hosting.
  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 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 integration keys are wanted. Example manifest, using a placeholder domain and 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.
  • A session 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 sessions 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; Sessions are unaffected. For example, a request after listing inventory is:
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 integration keys, but no operator manifest entries are loaded. This does not cancel an already-running operator request. Revoke personal integration keys under Personal Settings → Personal integrations; administrators revoke deployment-wide keys on the Integrations page. 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.