Overview
How First Draft previews work
Codex and Claude can run your Rails app in the cloud, but a normal browser cannot open that private workspace directly. First Draft gives the app a stable browser link.
-
Your app starts
The connector starts Rails inside your Codex or Claude environment.
-
It connects outward
The workspace makes an encrypted outgoing connection to First Draft. You do not need to open an incoming port.
-
Your link opens it
First Draft sends browser requests from your preview link through that connection to Rails.
What the connector manages
The generated bin/agent-vm-tunnel command keeps three parts running:
- your development database, when it needs its own process;
- your Rails development server; and
- the encrypted connection to First Draft.
Running bin/agent-vm-tunnel ensure more than once is safe. It repairs only the parts of this app that need attention.
What happens when the environment sleeps
Cloud workspaces pause after they sit idle. While yours is paused, the preview may say it is asleep or not connected. Resume the Codex task or Claude session; its lifecycle setup runs ensure and reconnects the same preview link.
Technical details
The connector uses Chisel over an encrypted WebSocket connection. Caddy receives HTTPS requests for the random preview hostname and routes them to the reverse port assigned to that preview.
The connector pins the server fingerprint so a different server cannot silently take its place. Rails keeps its normal same-origin protection for Action Cable, so Turbo and WebSockets work without allowing every sibling preview origin.
The preview hostname is random and does not include your GitHub username or app name.