Proxied App Runtime
The Proxied App Runtime is the shared model for third-party websites that Prox
The Proxied App Runtime is the shared model for third-party websites that Prox OS can understand as app-like assets. It covers compatibility status, launch mode, fallback copy, catalog seed data, and UI metadata. It does not bypass browser security policy.
Shared Runtime Package
Runtime data and helpers live in @prox-os/embed-runtime:
ProxiedAppCatalogItemProxiedSpaceProxSwitchbarRuleProxiedAppIframeStatusProxiedAppLaunchMode- compatibility badge metadata helpers
- fallback copy helpers
- URL matching and Switchbar rule matching
The React badge, fallback surface, and install destination menu live in
@prox-os/os-apps shared UI because @prox-os/embed-runtime is runtime data
and helper code, not a React package.
Compatibility Status
| Status | Meaning |
|---|---|
allowed | The curated catalog recommends iframe launch for the URL. |
blocked_x_frame_options | The site likely blocks iframe embedding with X-Frame-Options. |
blocked_csp_frame_ancestors | The site likely blocks iframe embedding with CSP frame-ancestors. |
blocked_mixed_content | Browser mixed-content policy prevents safe embedding. |
blocked_auth_or_login | Auth/session behavior requires an external top-level context. |
unknown | The site is searchable, but embed behavior needs per-URL review. |
Launch Modes
| Launch mode | Meaning |
|---|---|
iframe | Open inside a managed OS iframe window. |
external | Use external fallback in the browser top-level context. |
new_tab | Open in a new browser tab. |
dedicated_fallback | Reserve a future first-party fallback UI for a popular blocked app. |
native_connector_future | Reserve a future connector/native integration path. |
Fallback Design
Fallback UI should state:
This site cannot be embedded safely.
The website may use X-Frame-Options or CSP frame-ancestors to block embedding.Actions:
- Open externally.
- Copy link.
- View app settings.
- Request dedicated fallback.
The fallback is a normal product state, not an error box. It should explain that site policy is doing its job and that Prox OS is choosing a safe launch mode.
Browser Boundary
The browser shell can load iframes only when the target site permits embedding. It cannot safely or legally strip security headers, proxy around a site policy, or provide desktop-level cookie/profile/session isolation inside a normal web page.
Future extension or desktop clients can improve link interception, profile handling, local indexing, and system integration, but the browser shell must document its limits honestly.