Setup guide

Connect your Rails app from Codex

You will add the connector files to your app, copy your First Draft connection key into Codex, and start a task. 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 Codex 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=codex

Create or edit your Codex environment

Open Codex Settings → Environments ↗, choose the environment for this repository, and fill in the fields below.

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>

Use an environment variable, not a Codex secret. Codex removes secrets after setup, but the connector needs this value whenever your environment resumes.

Setup script

bash cloud-vm-setup.sh

Maintenance script

bin/agent-vm-tunnel ensure

Agent internet access

Turn it On. Allow firstdraft.io and tunnel.firstdraft.io. The allowed methods can be limited to GET, HEAD, and OPTIONS.

Save the environment and start a task

Codex checks out your repository, runs the setup script, and connects the preview. Return to First Draft when the task starts; the preview should change to Connected.

If the preview does not connect

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

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