[netanelgilad]

Note

Description

base44 dev becomes the single front door for the whole app, the way the platform serves it in production: the CLI origin answers the platform's surface locally (/api/apps/** for entities, functions, auth, media, plus /api/app-logs/**) and forwards everything else — the app's own /api routes and the HMR websocket included — to the app's own dev server, carrying the SDK header contract (Base44-App-Id, Base44-Api-Url, a locally minted service-role Base44-Service-Authorization) after the caller's copies of those platform-owned headers are dropped. Full-stack apps can therefore call createClientFromRequest locally just as they do in production; previously those headers were absent under base44 dev, so SSR pages and server functions could not build an SDK client at all. On top of that, the front door stands in for the platform's login on a private or workspace app — a page load with no session goes to the CLI's own /login, which signs the developer in as the account the CLI is logged in with, hands the app an access token and keeps it in a session cookie — and base44 dev --remote runs the same front door against the live app's data (and now accepts --port).

Related Issue

None (internal: base44-dev/apper#25003). Split out of #643, which keeps the deploy-routing changes.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

The front door

• New createAppServerProxy (src/cli/dev/dev-server/routes/app-server.ts): HTTP proxy + websocket relay into app-owned code. Strips the visitor's Base44-App-Id / Base44-Api-Url / Base44-Service-Authorization / Base44-State / Base44-Functions-Version / X-Base44-App-Url / X-Data-Env before setting the CLI's own, so a caller cannot point the app's SDK (and the credential travelling with it) at a host they chose. Authorization passes through untouched — it is the visitor the app's server code acts as.
• Routing split in main.ts: PLATFORM_PATH_PATTERN (new platform-paths.ts, matching /api/apps and /api/app-logs) stays local; everything else goes to the app dev server. Websocket upgrades follow the same split — REALTIME_PATH (now exported from realtime.ts) keeps the entity-events socket, all other upgrades are relayed.
• Websockets relayed frame by frame via ws rather than tunnelled: under Bun (the compiled binary), bytes written to a node:http upgrade socket never reach the wire. Client frames sent before the upstream opens are buffered and flushed on open.
• Loop guard: every forwarded request carries Base44-Dev-Forwarded; seeing it come back answers 508 with the fix (narrow the Vite proxy to /api/apps and /api/app-logs, or update @base44/vite-plugin) instead of looping. Proxy failures answer 502 with the underlying message.
• App dev server discovery (serve-runner.ts): ServeRunner reads the first http://localhost:<port> the child announces on startup, stripping ANSI first (Vite bolds the port) and skipping the front door's own port, which the Vite plugin echoes as its proxy target. serve-command-runner.ts threads onOrigin / ignorePort through.

Sign-in for private and workspace apps

• New createLoginGate (src/cli/dev/dev-server/routes/login-gate.ts): a page load (GET, Accept: text/html, outside /api/ and /media/) with no session cookie redirects to /login?from_url=…; the CLI's own page offers "Continue as <the CLI's account>"; submitting it mints an access token, sets the HttpOnly SameSite=Lax base44_dev_session cookie and redirects back with ?access_token=, the hosted login's own hand-off. A cookie-bearing request with no Authorization gets the cookie's token as one, so server-rendered pages act as the visitor. The SDK's /api/apps/auth/logout clears it. from_url is forced back onto the front door's origin so a crafted link cannot carry the token elsewhere, and the values rendered into the page are HTML-escaped.
• Gating decision: visibility in config.jsonc wins (it is what deploy applies), else the app's public_settings from the server via the new getAppVisibility (core/project/api.ts, AppPublicSettingsSchema); an unreachable server means public, and a public app keeps handling /login itself.
• Token source: locally a JWT for the account seeded as admin in the local database (createJwtToken); under --remote, the account's app-user token from the platform (getAppUserToken), so the app reads and writes the live app's data as that user.

--remote

• New createRemoteFrontDoor (remote-front-door.ts): the same single origin with no local backend — the platform's paths and the entity-events socket proxy to the live app, and the app dev server gets Base44-App-Id / Base44-Api-Url but no service-role token (the CLI cannot mint one the live app accepts). --port is now accepted (it picks the front door's port, default 4400) instead of being rejected, and SIGINT/SIGTERM exit the process, since the front door lives in it.

Command, docs and deps

• dev.ts: wires the origin promise (120s startup timeout with a clear error), passes appServer and loginGate to createDevServer, and the outro now prints Your app is available at <cli url> instead of telling users to open the frontend dev server's URL (--remote adds "it runs on the data of <live app>").
• Docs: new docs/dev-server.md topic guide, linked from docs/AGENTS.md; CHANGELOG entries under Changed.
• Deps: ws + @types/ws added as devDependencies (bundled, per the zero-dependency distribution rule).

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (npm test)

New tests/cli/dev-app-server.spec.ts drives the real dev command against two new fixtures: with-app-server (a node dev server that announces a Vite-shaped, ANSI-bolded URL and echoes what each request arrived with, HMR upgrade included) and with-private-app-server, the same app with "visibility": "private". Eleven cases cover SDK header injection, dropping the caller's copies, the app's own /api/time being forwarded, /api/apps and /api/app-logs staying local, the HMR socket relaying with headers, the entity-events socket staying local, the redirect to the sign-in page, the full sign-in hand-off with the cookie travelling as Authorization on later requests, logout ending the session, and a public app keeping its own /login. dev.spec.ts was updated for --remote now fronting the serve command and accepting --port, and waitForDevServer in the testkit for the new outro wording. The suite was not re-run while writing this description (build and test commands were unavailable in this environment), so the box stays unchecked pending CI on this HEAD.

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated docs/ (AGENTS.md) if I made architectural changes

Additional Notes

User-visible workflow change: open the URL base44 dev prints, not the frontend dev server's own URL. Opening the frontend dev server directly still works for pure-frontend apps but bypasses the header contract and the login gate, so SSR/server-function code will not get an SDK client and a private app will not be signed in.

Since the previous description: /api/app-logs moved back to the platform side of the split (commit 3dd96ab) — the SDK posts client logs there, and forwarding them to the app dev server would take them away from the local backend — and the login gate plus the --remote front door landed in 0f02923.

---

_{🤖 Generated by Claude | 2026-10-25 16:38 UTC | 96b3a00}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.2.3-pr.659.96b3a00

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/cli@0.2.3-pr.659.96b3a00"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.2.3-pr.659.96b3a00"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.2.3-pr.659.96b3a00
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}

[netanelgilad]

0f02923 adds sign-in for private and workspace apps under base44 dev and base44 dev --remote. --remote now also runs the front door, with the platform's paths proxied to the live app. Details are in docs/dev-server.md under "Private and Workspace Apps".

End-to-end check. I created a new private app (the apps-examples TanStack guestbook with "visibility": "private"), deployed it, and drove both modes in headless Chromium.

The live app is private: an anonymous GET / returns 401, and an anonymous entity API call returns 403.

Local, base44 dev:

• / redirects to the CLI's /login, which shows "Continue as netanelg@base44.com".
• After signing in, the browser lands back on / and the SDK has stored its token.
• Signing the guestbook writes an entry, and the entry is still there after a reload.
• Logout returns to /login.

Remote, base44 dev --remote:

• The same flow passes.
• The entry it wrote is in the live app's database. I read it back through the app's API with the account's app-user token.
• Ctrl-C exits the process.

Public app: GET / isn't gated, and /login goes to the app.

Bugs found during the check and fixed in this push:

• Server-rendered pages called the live private app anonymously and got a 500. The session cookie now carries the token and is sent as Authorization when a request has none, as the platform's cookie does.
• The live-app proxy had ws: true, which made http-proxy-middleware take every websocket upgrade, so HMR failed with "Invalid frame header".
• Ctrl-C didn't exit --remote.

Tests:

• dev-app-server.spec: 4 new gate cases (redirect, sign-in hand-off and cookie identity, logout, public app untouched). 11 of 11 pass.
• The two dev.spec --remote tests are updated for the new contract (front door URL, --port accepted).
• Typecheck, lint and knip are clean.
• The only failures are the two dev.spec cases that also fail on main in this sandbox (no IPv6).

---

Generated by Claude Code