Preview URLs
Preview URLs let you open an app the agent starts inside an isolated environment — a web server on a granted port — in your browser.
How it works
- Grant preview ports under Settings → Environments → Ports (range 3000–3999; default is often just
3000). - Ask the agent to start your app and share a preview link (
get_preview_url). - Open the link. It signs your browser into the workspace gateway, then loads the app.
Preview hosts look like {port}-t-{session}.{gateway} in production.
What you need for a working preview
You only need a preview when you want to open the app in your own browser. Agents never need a preview grant to run or screenshot an app — they open http://localhost:<port> in the workspace desktop browser directly. Grant ports only when you want the link.
- Bind on all interfaces — the process must listen on
0.0.0.0(or equivalent), not only127.0.0.1, so the gateway tunnel can reach it. - Use a granted port — agents cannot expand the allowlist. Add ports yourself, then ask for a new preview URL after saving.
- Keep the conversation open — environments stop after about 10 minutes of idle time. Closing Konvio while you only leave a preview tab open will eventually stop the environment.
- Use the link the agent shared — bare bookmarked hosts without the sign-in step often fail. Ask the agent for a fresh URL when in doubt.
Sharing
Preview links are session-scoped. They are meant for you (or someone already in the same Konvio conversation flow), not as permanent public URLs. Teammates who only have the URL and no access to the conversation/environment will not get a lasting public site.
After something breaks
| What you see | What to do |
|---|---|
| Sign-in required / link expired | Ask the agent for a new preview URL; confirm the conversation (and environment) is still running |
| Environment unavailable | Return to the conversation, wait for the environment to start, then request a new URL |
| Port not available | Add the port under Settings → Environments → Ports, then ask for a new URL |
| App half-loads | Confirm the app binds on 0.0.0.0 on a granted port; open a fresh preview link from the agent; keep the conversation open |
Hot module reload over the preview host may work after the first sign-in (the gateway can authenticate GET WebSocket upgrades via the session map), but it is not guaranteed across every framework. Prefer refreshing the tab after the agent changes code if HMR misbehaves.