OpenChamber Relay Transport Skill
Build WebSocket, SSE, and streaming endpoints that actually work over OpenChamber's end-to-end encrypted relay tunnel, where desktop-only testing silently hides failures.
Security posture is strong: mandates shared runtime transports, forbids host-side credential injection, forbids trusting loopback as auth, and requires testing against real auth/origin gates. No direct external effects on users; MIT license; SECURITY.md with responsible disclosure exists. Deductions: unverified publisher; token minting and forwarding details live in files not reviewed here; E2EE implementation correctness cannot be confirmed from this file alone.
Internally consistent with concrete verification commands (bun test per file, type-check, lint, node --check) and explicit failure modes (origin 'null' 403 in WKWebView, raw WebSocket scheme errors). Deductions: nothing executed in this static review; the suite admits order sensitivity; coverage of the referenced cross-compat.test.js and other tests is not visible in this file.
Frontmatter description precisely scopes triggers (adding/changing WebSocket, SSE, streaming, relay modules), with an explicit boundary split against the ui-api-decoupling skill, reducing false invocation; branch structure covers inputs and expected outputs. Deductions: applicability is confined to this repository's codebase; no Chinese-language support; environment fit is fine since the skill depends only on in-repo code, not external services.
Good information architecture: overview, mental model, change-type branches, verification and completion criteria, pointing to higher-level DOCUMENTATION.md; MIT license explicit; compatibility field present. Deductions: the skill itself has no version or changelog; availability of the referenced sibling skill (ui-api-decoupling) is assumed but unguaranteed; no explicit known-limitations list for the skill itself.
Targets high-frequency, hard-to-diagnose relay bugs (first mobile WS, dual allowlists, token minting, origin traps) with an actionable checklist; marginal value over manual trial-and-error is significant. Deductions: results unverifiable statically; the completion criteria depend on extensive context files and test infrastructure, limiting direct reusability outside this repository's maintainers.
Key claims trace to concrete file paths (tunnel-host.js, ui-auth.js, runtime-socket.ts, cross-compat.test.js); repository includes CI workflows and test scripts. Deductions: actual test coverage of relay key paths is not shown; no independent third-party verification; the origin-check-bug narrative is author-asserted; fact/inference separation is only moderate.
- This is a static source review; no tests or verification commands were executed and confidence is low.
- The skill applies only to relay transport development inside the openchamber/openchamber repository and has no direct reuse value elsewhere.
- The skill references multiple files outside this review scope (tunnel-host.js, cross-compat.test.js, the ui-api-decoupling skill); their actual state is unverified.
- The test suite self-reports order sensitivity; run tests per file as instructed.
- The publisher is not verified by the FollowSkills registry; identity is treated as unknown, which neither deducts nor endorses.
What does this skill do, and when should you use it?
relay-transport is one of 18 skills bundled in the OpenChamber repository (openchamber/openchamber, MIT licensed), located at .agents/skills/relay-transport/SKILL.md. It codifies the rules for OpenChamber's private relay: clients reach a user's instance through an OpenChamber-hosted relay over an end-to-end encrypted tunnel, with all HTTP, SSE event-stream, and WebSocket traffic multiplexed over one connection per client. Its value comes from hard-won lessons — relay bugs don't surface in normal testing, and WebSockets in particular cannot send auth headers, requiring short-lived URL-scoped tokens. The skill also draws a clear boundary: it owns relay mechanics, while the shared UI/runtime boundary belongs to the ui-api-decoupling skill.
The skill provides four rule branches. (1) WebSocket endpoint branch: connect only via openRuntimeWebSocket, never raw new WebSocket; register the path in BOTH allowlists (ALLOWED_WS_PATHS in tunnel-host.js and isUrlAuthWebSocketPath in ui-auth.js); mint oc_url_token via refreshRuntimeUrlAuthToken() before connecting; never touch origin handling (loopback origin is already trusted; forwarding window.location.origin causes 403 in iOS WKWebView); and test over the real relay. (2) Wire format and codec branch: keep the TS implementation (normative) and JS host mirror byte-compatible, mirror frame types across protocol.ts, tunnel-codec.ts, and tunnel-codec.js, preserve capability-negotiated batching with single-frame fallback, and keep the per-direction, strictly increasing encrypted-frame counter. (3) Runtime transport branch: when refactoring runtime-switch/fetch/url/socket/auth, preserve both relay and direct branches byte-identically; the host dispatcher must never inject credentials or trust loopback as authentication. (4) Reconnect branch: use exponential backoff on consecutive failures, long caps while offline or hidden, long backoff for permanent 4xx (408/429 stay retryable), interruptible waits on online/visibility/abort signals, and reset only after a genuinely healthy connection. Verification requires mirroring real auth and origin gates in tests, running bun test per file (order-sensitive suite), type-check/lint on packages/ui, and node --check on changed JS host files.
- A developer adding a new WebSocket endpoint to OpenChamber (e.g. terminal or dictation features) who needs it to work over the relay tunnel on mobile
- A maintainer changing E2EE or frame-format codecs who must mirror updates in both TS and JS and keep cross-compat tests green
- An engineer refactoring runtime-fetch / runtime-socket modules who must preserve identical behavior for non-relay runtimes
- A developer implementing SSE or WebSocket auto-reconnect who needs to avoid battery-draining blind retries and flooded server logs when offline or hidden
- Someone writing relay integration tests who must replicate the real oc_url_token auth and origin gates rather than a permissive stub server
What are this skill's strengths and limitations?
- Rules are distilled from recurring real relay failures (e.g. Origin being 'null' in iOS WKWebView causing 403), making them highly actionable
- Covers the full delivery path: allowlists, URL tokens, origin handling, dual-side codec compatibility, and testing checklists
- Explicitly delineates scope against the ui-api-decoupling skill, avoiding rule conflicts
- Includes easily overlooked requirements like capability-negotiated frame batching and reconnect backoff pacing
- Only applies to the OpenChamber codebase; no direct reuse value in other projects
- SKILL.md declares compatibility: opencode, so use outside the Agent Skills standard may need adaptation
- The relay test suite is order-sensitive and must be run per file with bun test
- Some details (e.g. token lifetimes, deployment config) require reading packages/web/server/lib/relay/DOCUMENTATION.md; the skill does not cover everything
How do you install this skill?
The skill ships with the OpenChamber repository. Get the repo: git clone https://github.com/openchamber/openchamber; the skill lives at .agents/skills/relay-transport/. If OpenChamber itself uses the OpenCode Agent Skills mechanism, skills in this directory are loaded via its skills catalog / local skill management; the README does not document a standalone installation path for this single skill.
How do you use this skill?
When a task touches OpenChamber WebSocket, SSE, streaming endpoints, shared UI sockets, runtime transport internals, private relay behavior, or files under the ui/server relay modules, have the agent load and follow this SKILL.md. Example prompt: 'Add a new /api/terminal-ws WebSocket endpoint to OpenChamber, following the relay-transport skill.' If the change also adds or alters a shared runtime API or URL/auth contract, load the ui-api-decoupling skill as well.
How does this skill compare with similar options?
The SKILL.md positions this skill as complementary to the sibling ui-api-decoupling skill in the same repo: relay-transport owns relay transport mechanics, while ui-api-decoupling owns the shared UI/runtime boundary (APIs, URL/auth contracts, bridges, proxies). No external alternatives are named.