MiroFish Network Error Fix 2026: VITE_API_BASE_URL Explained for VPS & Remote Access

MiroFish network error on VPS or Docker almost always means the browser is calling localhost:5001 instead of your server. This guide explains VITE_API_BASE_URL, maps ports 3000 and 5001, and links SSH remote access, OpenClaw deployment on Mac mini M4, and short-term node selection when you host experiments on VpsGona.

Disclosure: VpsGona is the Mac rental provider mentioned for optional cloud Mac hosting. MiroFish is an independent open-source project; fix steps cite GitHub issues and Vite documentation.

New install? Start with our MiroFish Docker deployment guide for .env, LLM keys, and docker compose up -d.

Why you see "Network Error" in MiroFish

Quotable fact: The UI can load on :3000 while API calls fail—users report handleNewProject: Network Error during ontology generation when the axios base URL still targets the wrong host (GitHub #57, #511).

Backend logs may show Flask listening on 0.0.0.0:5001; that only proves the server process is up—not that your browser reaches it.

The localhost trap (browser vs server)

When you open http://YOUR_VPS_IP:3000/ from a laptop, localhost inside JavaScript means your laptop, not the VPS. The Vite dev proxy (/api → 127.0.0.1:5001) helps only when Vite serves the page on the same machine you browse from.

Rule: Set VITE_API_BASE_URL to a URL your browser can open directly—usually http://PUBLIC_IP:5001 or an HTTPS API hostname behind nginx.

What VITE_API_BASE_URL does

Vite exposes env vars prefixed with VITE_ at build time into the frontend bundle (Vite env documentation). Changing .env without rebuilding Docker images often leaves the old localhost baked in—tracked in docs issue #514.

# project root .env
VITE_API_BASE_URL=http://203.0.113.10:5001

Fix checklist: LAN, Docker, and VPS

1. Edit .env beside docker-compose.yml.
2. Map ports 3000:3000 and 5001:5001.
3. Run docker compose down && docker compose up --build -d.
4. Hard-refresh the browser (disable stale service worker if any).

Ports 3000 and 5001: Docker & firewall

ports:
  - "3000:3000"
  - "5001:5001"

Allow both ports in your cloud security group and OS firewall (ufw allow 5001/tcp). A curl timeout here will reproduce the UI error even with correct env vars.

Verify the backend before blaming API keys

1. From your laptop: curl -sS -o /dev/null -w "%{http_code}" http://PUBLIC_IP:5001/ — connection refused means firewall/Docker, not LLM keys.
2. DevTools → Network: failed XHR host must be PUBLIC_IP, never localhost.
3. After env changes, rebuild frontend assets (Vite bakes env at build).

Optional: run MiroFish on a VpsGona cloud Mac

Linux VPS works; some teams rent a Mac mini M4 from $20.7/day for short swarm-intelligence pilots with familiar Docker Desktop + SSH. Use SSH vs VNC for CLI-first setup; node selection for HK/JP/KR/SG/US East latency.

Frequently asked questions

Does a 404 on http://IP:5001/ mean the backend is down?

Not necessarily—the root path may be undefined. Test connectivity (TCP) and a documented API route; timeout means firewall or Docker mapping.

I set VITE_API_BASE_URL but still see localhost in DevTools—why?

The frontend bundle was not rebuilt. Run docker compose with --build or restart npm run dev after saving .env.

Can I use HTTPS with a domain?

Yes—set VITE_API_BASE_URL to https://api.example.com and terminate TLS at nginx/Caddy; the browser must use the same scheme.

Is this related to LLM API keys?

Network Error before any HTTP response usually means wrong host/port. Fix connectivity first, then verify LLM keys in .env.

Why does LAN IP access work on the server but not my phone?

Set VITE_API_BASE_URL to the LAN IP the phone can reach, not 127.0.0.1, and ensure port 5001 is open on the host firewall.