Zrok setup

Use zrok when Convex cloud needs to dispatch triggers to your local Flowman app. Convex actions cannot call your machine's localhost, so zrok gives the local Next.js server a public https://*.share.zrok.io URL. Product preview sessions use the same CLI, but they are separate shares for repository preview ports rather than the Flowman app callback URL.

Prerequisites

Install the zrok CLI.
Have a zrok account token ready.
Make sure your local FLOWMAN_INTERNAL_DISPATCH_TOKEN is set. Convex cloud must use the same value.

Share local Flowman

Enable zrok once on your machine:
```
zrok enable <account-token>
```
Start the Flowman dev server:
```
pnpm dev
```
The repo's dev script serves Next.js on http://localhost:4208.
In another terminal, create a public share for that port:
```
zrok share public 4208
```
Copy the generated zrok URL.

Update Convex cloud environment

Set FLOWMAN_APP_URL on the Convex cloud deployment that evaluates triggers. Use the zrok URL as the value, without a trailing slash.

pnpm exec convex env set FLOWMAN_APP_URL 'https://<your-share>.share.zrok.io'

If the dispatch token is not already set in Convex, set it there too:

pnpm exec convex env set FLOWMAN_INTERNAL_DISPATCH_TOKEN '<same-token-as-local>'

Add --prod for the production Convex deployment, or --deployment <deployment> for a specific cloud deployment. Ephemeral zrok shares get a new URL when restarted, so repeat the FLOWMAN_APP_URL command after restarting the share.

Where it is used

Trigger evaluation reads this host runtime variable from Convex, not from a project's Environment variables page. See Triggers and events for the dispatch path.

Product previews

Coding preview sessions are configured on registered repositories. Each preview target stores a command and port; when a preview is queued, the coding runtime first checks whether that port is already serving. If it is, Flowman treats the server as externally managed and only creates a zrok share. If the port is free, Flowman starts the configured command, waits for the port, then creates the zrok share.

zrok share public <preview-port> --headless

Preview URLs are attached to preview sessions, not repositories. They can be regenerated from the run detail page if zrok exits or the URL is lost, and Flowman stops managed preview processes when the coding session is marked done.