Deeplinks

4RGE registers a custom URL scheme, x4rge://, that the desktop app handles. Deeplinks hand control back to the desktop from the browser — completing sign-in, OAuth flows, and MCP authorization without leaving tokens in web-accessible storage longer than necessary.

How deeplinks work

1. Browser completes a flow

   You sign in, authorize OAuth, or finish MCP setup in the browser (authenticator at auth.4rged.ai).

2. Bridge builds an x4rge:// URL

   The auth bridge page constructs a deeplink with tokens or OAuth parameters in the fragment or query string.

3. OS opens the desktop app

   The browser navigates to x4rge://…. macOS, Windows, or Linux routes the URL to the installed 4RGE desktop app.

4. Desktop completes securely

   The app exchanges tokens (PKCE where applicable), stores the session, and returns you to the workbench.

Deeplink catalog

Web apps use HTTPS handoff instead of x4rge:// when the target is a browser surface:

Universal and app links

The long-term cross-platform direction is verified HTTPS universal/app links rooted at https://4rged.ai. HTTPS links should be preferred for user-facing navigation and can open the installed app after the platform association files and route allowlists are deployed. x4rge:// remains the canonical custom-scheme transport for desktop auth and OAuth callbacks.

Authentication handoff

After you sign in in the browser, 4RGE forwards the result to the desktop app:

x4rge://auth/callback#access_token=…&refresh_token=…&expires_in=3600&token_type=bearer&type=magiclink

The desktop app receives the callback and completes the sign-in. Fragment parameters include:

Bridge page flow

The authenticator hosts a bridge at /auth/desktop-callback:

// Simplified — reads hash from browser location, redirects to desktop
const hash = window.location.hash.slice(1);
window.location.replace(`x4rge://auth/callback#${hash}`);

If automatic redirect is blocked, a clickable Open 4RGED IDE link appears as fallback.

MCP OAuth handoff

MCP server authorization uses a similar bridge at /auth/mcp-callback. On success, the authorization code is appended to the callback URI stored in the OAuth state parameter:

x4rge://your-mcp-callback?code=AUTH_CODE

On failure, errors are forwarded so the desktop can clear stale registrations and retry:

x4rge://your-mcp-callback?error=invalid_client&error_description=…

CLI device auth

The CLI uses HTTPS device auth endpoints on the platform API rather than x4rge:// directly:

1. CLI starts auth

   POST /api/runtime/cli-auth/start returns a device code and verification URL.

2. User approves in browser

   Complete sign-in at auth.4rged.ai in the browser.

3. CLI polls for completion

   POST /api/runtime/cli-auth/poll returns session credentials when approved.

Platform API auth endpoints

CLI device login uses HTTPS routes on api.4rged.ai, not the x4rge:// scheme. The flow starts with POST /api/runtime/cli-auth/start, which returns a device code and verification URL; the user completes sign-in at auth.4rged.ai; the CLI polls POST /api/runtime/cli-auth/poll until credentials are issued. Desktop interactive sign-in uses a parallel /api/runtime/desktop-auth/start and /complete pair. Both paths store Supabase session tokens bound to your organization.

Troubleshooting deeplinks