Skip to content

Troubleshooting

Fix a preview

Start with the symptom you can see. Most connection problems are fixed by waking the cloud environment and asking it to check the app again.

First, check the connection

In your Codex task or Claude session, ask the agent to run:

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

ensure safely starts anything that stopped. status explains whether the app or its connection is down.

First Draft says “Not connected”

If the environment has gone idle, resume the matching Codex task or Claude session. Its setup should reconnect automatically. Then refresh First Draft.

If it still says “Not connected,” run ensure and status as shown above.

The connection key is missing or invalid

In First Draft, open Previews → Preview settings for the matching app, then choose Copy connection key. It begins with AGENT_VM_TUNNEL=.

  • In Codex, put it under Environment variables, not Secrets.
  • In Claude, put it in the cloud environment's environment-variable field.
  • Do not add quotes around the complete value.

If you deleted and recreated the preview, copy the new key; the old one no longer works.

The app process is down

Ask the agent to read the recent app log:

tail -n 100 tmp/agent-vm-tunnel/app.log

The message usually points to an application boot error, a missing dependency, or a database problem. First Draft uses port 3000 unless your app sets APP_PORT.

The tunnel process is down

Ask the agent to read the recent connection log:

tail -n 100 tmp/agent-vm-tunnel/tunnel.log

Common causes are a stale connection key or blocked network access. Check the provider guide for the required network setting:

Check Codex settings Check Claude settings
The preview page says it is asleep

Resume the matching cloud environment, then run:

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

If both processes are running, ask the agent to check the app directly:

curl -fsS http://127.0.0.1:${APP_PORT:-3000}/up
The page opens, but live updates do not work

Ask the coding agent to inspect the browser's WebSocket request and the Rails Action Cable configuration. The WebSocket must use the same First Draft preview host as the page. Remove copied wildcard origin settings; the connector already supports Rails' normal same-origin protection.

Still stuck?

Restart only this app's managed processes, then check again:

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