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/db
      -> packages/storage

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

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

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