Runtime View

Current Runtime Shape

Browser
  -> Cloudflare Pages
    -> apps/os-shell

Browser / OS Shell
  -> api.prox-os.com
    -> Cloudflare Workers
      -> apps/api-worker

Future Runtime Shape

apps/os-shell
  -> apps/api-worker
    -> packages/os-actions
      -> packages/data/db
      -> packages/backend/storage

apps/mcp-server
  -> packages/os-actions
    -> packages/data/db
    -> packages/backend/storage

Long-term MCP direction:

OS App declares MCP capabilities.
Prox MCP Gateway enforces auth, scopes, rate limits, audit logs, and user approval.

Do not assume every app should expose its own unmanaged MCP server. Space, Source, Context, and App capabilities should route through a governed platform gateway when MCP execution becomes real.

Frontend Runtime

apps/os-shell is the frontend runtime.

It owns:

• Shell UI composition
• Window state
• App launching
• Frontend routing
• Local visual state
• Managed links: resolveManagedLink (apps/os-shell/src/shell/links/) supervises app content links. Same-origin shell routes and known platform hosts resolve to registry app ids; left-click opens those directly in the OS (or routes website mode to the matching /website surface), while right-click opens ManagedLinkMenu. External web links are also supervised: left-click and right-click both show the menu instead of letting embedded app content navigate the shell. Hostnames are infrastructure entrypoints, not long-term app identity — see app-namespace-and-domain-strategy.md.

It does not own:

• Database credentials
• Storage credentials
• Server-side auth checks

API Runtime

apps/api-worker is the Cloudflare Workers runtime.

It owns:

• HTTP routes
• Runtime environment bindings
• Server-side validation
• Database and storage access through packages

Future API/runtime responsibilities may include metadata control-plane records: manifests, Space index, profile, stars, watches, install relations, connector state, permission grants, and MCP audit logs. This is not implemented today.

Local Development

Use root-level commands where possible.

Examples:

pnpm dev
pnpm dev:os
pnpm dev:api

Use package filters for package-specific commands.

pnpm --filter @prox-os/os-shell dev
pnpm --filter @prox-os/api-worker run dev