TL;DR
A developer built a free, open-source system that opens an interactive web terminal into a failed GitHub Actions run by creating a direct WebRTC peer-to-peer link between the Actions VM and a browser. The design uses OAuth and GitHub OIDC tokens for identity, a lightweight signaling server for introductions, and optional one-time passwords to reduce trust in the server.
What happened
The author created a tool that gives developers an interactive browser terminal connected directly to a GitHub Actions runner when a workflow fails. Instead of relaying terminal traffic through a central service, the system uses WebRTC to form a peer-to-peer connection between the Actions VM and the user’s browser by exchanging ICE candidates. A small signaling server handles introductions; it authenticates the browser via GitHub OAuth and the runner via an OIDC token issued by Actions. The runner streams a spawned PTY over a WebRTC data channel, while the browser renders the session with a Ghostty/xterm-compatible client. The implementation also estimates terminal size in the browser and sends setup information so the PTY starts with appropriate rows/columns. To limit reliance on the signaling server, an optional one-time-password step can be required before the runner accepts input from the browser.
Why it matters
- Provides direct interactive debugging inside the environment where a CI failure occurred, reducing guess-and-check cycles.
- Peer-to-peer data flow avoids routing large terminal traffic through a central service, lowering bandwidth and operational costs.
- Authentication via GitHub OAuth and Actions OIDC ties access to the triggering actor and repository context.
- An optional OTP workflow can limit the trust placed in the signaling server and mitigate certain compromise scenarios.
Key facts
- Project is described as free and open-source (author-provided URL and code referenced).
- WebRTC is used to establish a direct P2P connection between the Actions VM and the browser by exchanging ICE candidates.
- The signaling server only performs introductions; it does not proxy terminal data which flows directly between peers.
- Browser identity is verified using GitHub OAuth; runner identity is verified using a GitHub Actions OIDC token.
- Workflows must grant the Action id-token: write permission to request an OIDC token from the runner.
- The server validates OIDC tokens cryptographically against GitHub’s JWKS endpoint before linking sessions.
- The runner spawns a PTY and forwards its I/O over a WebRTC data channel; the browser renders the terminal with a Ghostty/xterm-compatible client.
- The client estimates terminal rows/columns from font sizing and sends setup JSON to start the PTY with correct dimensions.
- Signaling uses Server-Sent Events (SSE) so the server can push connectivity details to both browser and runner.
What to watch next
- Whether the project gains wider adoption or integrates into other CI tooling: not confirmed in the source
- Independent security audits or reviews of the signaling server and overall authentication flow: not confirmed in the source
- Potential GitHub platform support or changes to Actions networking/permissions that could affect behavior: not confirmed in the source
Quick glossary
- WebRTC: A set of web standards that enables real-time peer-to-peer audio, video, and arbitrary data channels between browsers and other endpoints.
- OIDC (OpenID Connect): An identity layer built on OAuth 2.0 that issues verifiable tokens about a caller’s identity and context.
- OAuth: An authorization protocol that lets applications obtain limited access to user accounts on an HTTP service.
- ICE candidates: Network information endpoints exchanged between peers during WebRTC signaling to determine possible paths for a direct connection.
- PTY (pseudoterminal): A system facility that emulates a terminal device, letting a program interact with shell processes as if a human user were typing.
Reader FAQ
Is this tool free and open-source?
Yes, the author describes it as free and open-source and provides a public demo and code link.
Does the signaling server relay terminal data?
No. The signaling server only exchanges connectivity details; terminal I/O flows directly between the browser and runner over WebRTC.
How are identities verified for each end of the connection?
The browser authenticates via GitHub OAuth while the runner requests an Actions OIDC token; the server validates the OIDC token using GitHub’s JWKS.
Do workflow permissions need to change to use this?
Workflows must allow id-token: write so the Action can request an OIDC token from the runner.
Using WebRTC to launch a debugging terminal into GitHub Actions Jan 11, 2026 Spoiler: I made a free and open-source way to get an interactive web terminal to your GitHub…
Sources
- Launch a Debugging Terminal into GitHub Actions
- maxmcd/webtty: Share a terminal session over WebRTC
- How to interactively debug GitHub Actions with netcat
- How to do network tracking or debugging WebRTC peer- …
Related posts
- Fossil vs Git: comparing features, architecture, hosting and workflows
- Lightpanda Replaces LibDOM with Zig-Based zigdom DOM Implementation
- Microsoft schedules a heavy slate of product retirements across 2026