# Roomote Runtime Integrations

> Trace how Roomote agents run through the Roomote runtime and integrations. Use when debugging or changing controller/worker/queue behavior, preview proxy flows, snapshots, MCP setup, or Slack/Linear/GitHub entry points that create or resume Roomote agent work.

- Skill: `roocodeinc/roomote-runtime-integrations` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add roocodeinc/roomote-runtime-integrations`
- Raw SKILL.md: https://api.skillmd.com/api/skills/roocodeinc/roomote-runtime-integrations/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: RooCodeInc (https://skillmd.com/u/roocodeinc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/roocodeinc/roomote-runtime-integrations

---


# Roomote Runtime Integrations

Trace the full Roomote agent path before changing runtime code.

## Start Here

- Read `packages/cloud-agents/src/server/cloud-job-queue.ts` for queue claim/release behavior.
- Read `apps/controller/src/BaseController.ts` and `apps/controller/src/orphaned-cloud-jobs.ts` for dispatch and recovery.
- Read `apps/worker/src/run-task/*` and `apps/worker/src/commands/*` for worker execution and harness startup.
- Read `packages/cloud-agents/src/system-prompt.ts` and `packages/cloud-agents/src/server/workflows/` for prompt assembly and workflow builders.

## Runtime Map

- Producers create tasks from web UI, API routes, or integration webhooks.
- Queue/controller logic turns those requests into dequeued jobs and machine dispatch.
- Workers prepare repos/services, configure MCPs, and run the active harness.
- Preview proxy exposes preview URLs and auth flows for running agent environments.
- Slack, Linear, GitHub, and MCP routes are entry surfaces into the same Roomote agent runtime.

## OpenCode Runtime Debugging Playbook

Use this when you need to debug worker, sandbox-server, or OpenCode server
harness behavior with the currently checked-in repo surfaces.

### Preferred Validation

- Confirm the OpenCode CLI exists: `command -v opencode`.
- Confirm auth exists when needed: `OPENAI_API_KEY`.
- Start with the smallest targeted worker or sandbox-server test that covers
  the code you are changing.
- If you need lower-level payload inspection beyond the checked-in tests, use
  the real caller under test or add a temporary local-only probe in your branch.
  Do not leave ad hoc probe helpers committed unless you intentionally turn
  them into supported scripts.

## Read By Problem

- Queueing, claim/release, orphan recovery:
  - `packages/cloud-agents/src/server/cloud-job-queue.ts`
  - `apps/controller/src/BaseController.ts`
  - `apps/controller/src/orphaned-cloud-jobs.ts`
- Worker execution and harness startup:
  - `apps/worker/src/commands/*`
  - `apps/worker/src/run-task/*`
- Preview URLs, auth, and nested routing:
  - `apps/preview-proxy/src/*`
  - environment package code under `packages/` related to environment config
- Slack / Linear / GitHub flows:
  - webhook handlers under `apps/api/src/handlers/`
  - related packages under `packages/slack`, `packages/linear`, and GitHub handlers
- MCP setup:
  - `packages/types/src/mcp-oauth.ts`
  - `apps/worker/src/commands/setup/setup-mcps.ts`
  - `apps/api/src/handlers/mcp/index.ts`
  - `apps/api/src/handlers/mcp/routing.ts`

## Current Invariants

- Docker is the default worker compute provider for Roomote local and self-hosted deployments.
- Hosted compute providers should preserve the sandbox-compatible API/contract surface used by Docker, Vercel Sandbox, and Modal-backed workers.
- Local preview-proxy runs on port `8081`.
- Webhook mounts are under `/api/webhooks/*`.
- GitHub MCP is router-side today. The worker-side integration catalog is no
  longer just Linear; treat `packages/types/src/mcp-oauth.ts` as the source of
  truth for the current task-facing integrations.
- GitHub App installation flow and GitHub user OAuth flow are separate concepts.

## Output Standard

- Name the exact entry surface affected by the change.
- Trace the handoff path end-to-end before proposing a fix.