Local development

NextMQ runs your processors by calling your webhook route over the public internet, so localhost isn't reachable on its own. Expose your local server through a tunnel and point callbacks at it.

Why you need a tunnel#

Producing jobs from localhost works out of the box — that's just an outbound HTTPS call to NextMQ. The catch is the other direction: NextMQ runs your jobs by calling your webhook route, and http://localhost:3000 only exists on your machine. A tunnel gives your local server a public HTTPS URL; you tell NextMQ to deliver callbacks there with NEXTMQ_WEBHOOK_BASE_URL.

Environment#

.env.local

NEXTMQ_CONNECTION_STRING=nextmq://v1....
NEXT_PUBLIC_APP_URL=http://localhost:3000
# The public tunnel origin from the next step:
NEXTMQ_WEBHOOK_BASE_URL=https://your-tunnel.example.com

Tip

Use a separate project for local development so test jobs never touch your production queues. Each project has its own connection string — set the dev one here and the prod one in your deployment.

Pick a tunnel#

Tunnel	Install	Account needed
Cloudflare Tunnel	`brew install cloudflared`	No (for quick tunnels).
ngrok	`brew install ngrok`	Yes — free authtoken.

Option A — Cloudflare Tunnel#

With your Next.js dev server running on port 3000, start a quick tunnel in another terminal:

cloudflared tunnel --url http://localhost:3000

It prints a https://<random>.trycloudflare.com URL. Put that in NEXTMQ_WEBHOOK_BASE_URL and restart next dev so the value is picked up.

Option B — ngrok#

Add your authtoken once (from the ngrok dashboard), then start the tunnel:

ngrok config add-authtoken <your-token>
ngrok http 3000

Copy the https Forwarding URL into NEXTMQ_WEBHOOK_BASE_URL and restart next dev.

Heads up

On both free tiers the public URL changes every restart. When it changes, update NEXTMQ_WEBHOOK_BASE_URL and restart Next so workers re-register at the new origin. A reserved ngrok domain or a named Cloudflare tunnel gives you a stable URL.

Register and verify#

Once the dev server is up with the tunnel set, hit the health path. It registers your workers at the tunnel origin and confirms NextMQ can reach you:

curl -fsS https://your-tunnel.example.com/api/nextmq/health

A 200 with registered workers means callbacks will arrive. To register worker automatically on boot, see Registering on startup.

Configuration — the full environment reference.
Registering on startup — auto-register on boot.