Proxee

Documentation

Proxee Docs

Quick start

Before you start, download Proxee for macOS menu bar app on your Mac.

For the best pairing experience and to keep your iPhone awake while you work, install the Proxee Companion iPhone app on your phone too.

Start Proxee

  1. 1Run your local web app on your Mac, for example on localhost:3000.
  2. 2In Proxee Settings, set Target Port to your app port.
  3. 3Click Go Live.
  4. 4Scan the QR code from Proxee Companion on your iPhone.
  5. 5Approve the iPhone from the Proxee menu on your Mac to pair it.
  6. 6Click Open Proxee Tab. Paired devices stay in sync with it.

Shared URL

The shared URL normally looks like http://proxee.local:7331. Your exact port may differ if you changed Proxee's proxy port in settings.

Using login and OAuth

Proxee supports local login flows, browser-owned OAuth redirects, and shared app-session refreshes across paired devices.

For OAuth, the most important setup is usually in your provider dashboard. If the provider validates redirect URLs, add the Proxee callback URL alongside your normal localhost callback.

Callback URLs

Add the Proxee callback URL

OAuth callbacks usually look like one of these. The important part is using proxee.local:<port> instead of localhost.

http://proxee.local:7331/auth/<provider>/callback
http://proxee.local:7331/api/auth/callback/<provider>

OAuth behavior

Proxee can relay provider redirects and keep one-time OAuth callback routes from being synced to other devices, but it cannot change the provider-side allowlist. If the provider says the redirect URI is invalid, check the registered callback URL and the visible Proxee port first.

For auth-protected apps, private data, or production data, use a trusted Wi-Fi network or a personal hotspot. Proxee is local-first and pairing-protected, but LAN traffic is currently HTTP and not encrypted.

Proxy modes

Start with SSR-Safe. Use Strict only when absolute local URLs need rewriting.

Choosing a mode

SSR-Safe

Default mode. Proxee does not rewrite absolute URLs in HTML, which helps avoid hydration issues in SSR frameworks like Next.js.

Use this when the site already loads correctly through Proxee.

Strict

Rewrites absolute local dev-server URLs so assets or links that still point at localhost can go through Proxee.

Try this when images, scripts, stylesheets, or links still point at localhost on your phone.

If Strict mode causes hydration warnings, duplicate content, or layout flashes, switch back to SSR-Safe and refresh the page.

Pairing and local network safety

Go Live exposes your proxied dev site on your local network, and Proxee blocks unpaired clients.

Proxee requires pairing before a device can browse the proxied site or connect to the sync channel. New approvals happen from the Mac app.

Pairing is stored on the client. If you clear browser site data, switch browser profiles, or revoke a device from the Mac app, that device needs to pair again.

Proxee is for local development on trusted networks. It is not a public tunnel or production proxy.

Troubleshooting

Fast checks for the issues most likely to appear during real-device testing.

Common fixes

Your iPhone cannot connect

Make sure the Mac and iPhone are on the same network, disable VPNs that block LAN devices, and try toggling Go Live off and on as well as refreshing the page on your phone after changing networks. If public or corporate Wi-Fi blocks device-to-device traffic, use a personal hotspot.

A paired device gets 403

The Proxee pairing cookie may be gone, or the device may have been revoked. Open the Proxee URL again and approve the device from the Mac app.

You see 429 Too Many Requests

Wait about a minute and try again. This usually means repeated failed pairing attempts or too many reconnect attempts from the same device.

OAuth says the redirect URI is invalid

Add the Proxee callback URL in the provider dashboard, including the proxy port. The allowlist must match the exact redirect URI your app sends.

Login works on Mac, but the phone looks logged out

Bring the companion app back to the foreground or tap refresh. It checks whether app-session cookies changed and reloads the current safe Proxee page.

Assets still point at localhost

Try Strict mode. If the app is an SSR framework and Strict mode causes hydration issues, switch back to SSR-Safe and check for absolute localhost URLs or custom origin checks in the app.

The browser says Not Secure

Proxee currently serves local LAN pages over HTTP, like many local dev servers. Use trusted networks or a personal hotspot for sensitive work.

Contact support

If the quick checks do not solve it, send over the setup details and what you expected to happen.

Email support@proxee.dev with your Proxee version, framework, local dev server port, and what went wrong.