Skip to content

Setup guide

Connect your Rails app from Claude

You will add the connector files to your app, copy your First Draft connection key into Claude, and start a session. You only need to do this once for each environment.

Before you begin: create a preview in First Draft. Keep its page open so you can copy the connection key when the guide asks for it.

Add the connector to your Rails app

Run these commands in your app's repository. Then commit and push the generated files so Claude can use them.

Run in your repository

bundle add agent_vm_tunnel --github firstdraft/agent_vm_tunnel
bin/rails generate agent_vm_tunnel:install --provider=claude

Add a Claude cloud environment

Open Claude Code ↗, choose Add cloud environment, and select this repository and branch.

Environment variables

Open Previews in First Draft, choose Set up preview or Continue setup, and copy the connection key. It has this shape:

AGENT_VM_TUNNEL=<position>:<password>
Setup script 
#!/bin/bash
set -euo pipefail

repo="${CLAUDE_PROJECT_DIR:-}"
if [ ! -f "$repo/cloud-vm-setup.sh" ]; then
  repo="$(find / -maxdepth 6 -name cloud-vm-setup.sh -printf '%h\n' 2>/dev/null | head -n1)"
fi

test -n "$repo" && test -f "$repo/cloud-vm-setup.sh"
cd "$repo"
exec bash cloud-vm-setup.sh
Network access
Choose Full. The current Trusted setting blocks the connection that keeps your preview available.

Save the environment and start a session

The generated repository hooks start your app and reconnect it after the environment wakes. Return to First Draft after the session starts; the preview should change to Connected.

If the preview does not connect

Ask Claude to run these commands in the repository, then check the reported status.

bin/agent-vm-tunnel ensure
bin/agent-vm-tunnel status