Rendering Local URLs

Urlbox renders pages from our cloud infrastructure, so the URL you pass has to be reachable from the public internet. A URL like http://localhost:3000 or a private LAN address won't work - localhost would resolve to the render server itself, not your machine.

To render a site running on your own machine or inside a private network, give it a temporary public URL with a tunnel.

Cloudflare Tunnel

Cloudflare Tunnel is free, and its quick tunnels don't even require an account (Cloudflare intends them for exactly this kind of testing and development use):

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

This prints a random https://<something>.trycloudflare.com URL that forwards to your local server. Pass that URL to Urlbox:

{
  "url": "https://your-tunnel.trycloudflare.com/some-page"
}

If you want a stable hostname that survives restarts (useful for webhooks and repeated test runs), create a named tunnel on a domain you manage on Cloudflare - also free on every plan.

ngrok

ngrok is the best-known tunnelling tool:

ngrok http 3000

It prints a public https://<id>.ngrok-free.app URL forwarding to your local port. The free tier gives you a random URL per session; paid plans offer stable subdomains.

Other options

Any tool that gives your local server a public HTTPS URL works the same way:

• Tailscale Funnel - expose a port from your tailnet to the internet
• localtunnel or ssh -R based services like localhost.run - quick, no-install options
• VS Code port forwarding - the built-in Ports panel can make a forwarded port public

Alternatively, sidestep the tunnel entirely:

• Preview deployments - if your project deploys previews (Vercel, Netlify, Cloudflare Pages), render the preview URL instead of your local server
• Raw HTML - if what you really want is to render markup you have locally rather than a running app, pass it directly with the html option and skip the server completely

Securing the tunnel

A tunnel URL is public: anyone who discovers it can browse your dev server. Random tunnel URLs are hard to guess, but for anything sensitive, put auth on it and pass the credentials in the render request:

• HTTP Basic auth on your dev server or tunnel, with the credentials passed via the authorization option: "authorization": "Basic base64credentials" (ngrok can enforce this itself with ngrok http 3000 --basic-auth "user:password")
• A secret header your dev server checks, passed via the header option: "header": "X-Dev-Secret=some-long-random-value"

Allowlisting Urlbox's IP addresses isn't practical: they are dynamic and subject to change, so header-based auth is the way to lock a tunnel down. If you do require fixed IP addresses, please speak to us.

Close the tunnel when you're done rendering.