back to blog

developer tutorial

how to access your vite dev server running on an ai agent

17 min read

You launch a React app on an agent, Vite says it's ready on 5173, and your browser still can't reach it. If you're trying to access Vite server on AI agent infrastructure, this is expected until ports are explicitly exposed and proxied.

Dev servers usually run inside private networks, so localhost output in logs is only valid inside the container. The fix is not a random tunnel script. The fix is deterministic networking: open port, bind correctly, proxy with a stable URL shape.

This tutorial walks through the full flow in in10nt, including create-instance API calls, startup verification, proxy URL construction, and HMR troubleshooting. You can apply the same pattern to Next.js, Vue, and custom app servers.

Why dev servers fail on remote agents

  • Private machine addresses are not publicly routable
  • Port 5173 is not open by default
  • Server is bound to localhost only
  • Proxy path exists but WebSocket upgrade is blocked
  • Instance ID or route is stale after restart

What developers typically try: copying `http://localhost:5173`, swapping in an internal IP, or curling random ports. Those approaches fail because they bypass the intended network boundary model.

Useful references: Vite server options, Caddy reverse proxy docs, and Fly networking.

How in10nt port proxying works

in10nt routes public traffic to isolated agent containers through a proxy layer. You access a public URL, the proxy resolves instance + port, and forwards the request into the private runtime safely.

https://api.in10nt.dev/instances/{id}/ports/{port}/

Example for Vite:

https://api.in10nt.dev/instances/ins_abc123/ports/5173/

This pattern also supports nested routes and static assets. For deeper network details, see in10nt proxy architecture and network model deep dive.

Step 1: create an instance with openPorts: [5173]

curl -X POST https://api.in10nt.dev/instances \
  -H "Authorization: Bearer $IN10NT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vite-demo",
    "image": "node:20",
    "openPorts": [5173]
  }'
{
  "id": "ins_abc123",
  "status": "starting",
  "openPorts": [5173]
}

If 5173 is not in `openPorts`, the proxy endpoint will not forward traffic. Keep ports explicit so access is auditable and predictable.

Step 2: start Vite and bind to 0.0.0.0

curl -X POST https://api.in10nt.dev/instances/ins_abc123/run \
  -H "Authorization: Bearer $IN10NT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "npm install && npm run dev -- --host 0.0.0.0 --port 5173"
  }'

Binding to localhost is a top cause of access dev server on agent failures. Use `--host 0.0.0.0` or equivalent Vite config so the proxy can reach the service.

Step 3: verify with logs and open the proxy URL

curl -N https://api.in10nt.dev/instances/ins_abc123/stream/logs \
  -H "Authorization: Bearer $IN10NT_API_KEY"
curl -I https://api.in10nt.dev/instances/ins_abc123/ports/5173/

Then open the URL in browser. If you get HTML with script tags, your dev server proxy path is working.

Step 4: support routes, assets, and HMR

  • Route access: `/ports/5173/settings`
  • Asset access: `/ports/5173/src/main.ts`
  • HMR requires WebSocket upgrades to pass through proxy
  • Keep consistent origin and base paths to reduce CORS friction

If HMR is unstable, tune Vite HMR host/path and confirm proxy upgrade headers. See WebSocket proxy tips for agents.

Using the same pattern for other dev servers

  • Next.js: open 3000, bind host 0.0.0.0
  • Create React App: often 3000
  • Vue + Vite: usually 5173
  • Custom Express preview: any declared open port

A shared framework matrix helps teams avoid port drift. Keep one table in docs and reuse it in templates. Example: framework port matrix for agent dev.

Troubleshooting common failures

Port not found

Recreate or update instance with the expected open port. Confirm metadata before retrying the URL.

Connection refused

Service is not listening yet, machine is cold, or bound to localhost. Add readiness checks and retries; review connection refused root causes.

CORS errors

If frontend and API are on different origins, configure allowed origins explicitly. Prefer single-origin proxy patterns when possible.

WebSocket not working

Validate proxy upgrade support and Vite HMR config. Check browser devtools WS frames to isolate routing vs app-level issues.

Security and best practices

  • Treat public proxy URLs as internet-accessible endpoints
  • Do not expose admin ports or secrets in dev previews
  • Use short-lived instances for demos and pull requests
  • Apply rate limiting to high-traffic preview URLs
  • Monitor usage and logs continuously

More guidance: agent exposure security checklist and rate limiting public endpoints.

Real workflow example

  • Create instance with `openPorts: [5173]`
  • Run Vite with `--host 0.0.0.0 --port 5173`
  • Stream logs until ready
  • Open `https://api.in10nt.dev/instances/{id}/ports/5173/`
  • Share preview URL with your team

Conclusion

To access Vite server on AI agent runtimes reliably, you need explicit port exposure, correct host binding, and stable proxy routing. in10nt gives a consistent URL model and instance APIs so you can move from "it works locally" to shareable remote previews without custom tunnel infrastructure.