Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
9Router default MSO app-host: design note
Status: historical proposal, retained as design evidence. Current automatic DNS/tunnel setup and recovery are documented in MANAGED-DOMAINS.md; current authentication is in MANAGED-APPS.md. The cookie-domain expansion discussed below is obsolete: applications now exchange an app-bound ticket for a host-only app cookie. This note is not an instruction to widen cockpit cookies or migrate an existing public deployment.
Problem observed
A managed 9Router installation can be healthy on 127.0.0.1:20128 while publicDashboardUrl remains unset. It is tempting to fix that by routing a public hostname directly to the 9Router container. That makes the dashboard reachable, but it bypasses MSO's managed-app authentication boundary. On the observed runtime, /dashboard returned 200 without a separate 9Router login, so a direct reverse-proxy route would expose the management UI to anyone who can reach the hostname.
The desired owner experience is simpler and safer:
- the canonical browser URL is
https://9router.mso.<owner-domain>/; - users authenticate once to MSO, not once to MSO and again to 9Router;
- the 9Router service itself stays private and is not independently reachable from the public Internet;
- MSO remains the policy enforcement point for browser access.
This is session unification at the MSO boundary, not password synchronization. MSO credentials/session material must never be copied into, stored by, or forwarded to 9Router.
Target request path
browser
-> Cloudflare / DNS / TLS
-> 9router.mso.<owner-domain>
-> MSO managed-app host router
-> MSO session + approved-device authorization
-> MSO managed-app proxy
-> http://127.0.0.1:20128
-> 9Router
The public route must terminate at MSO, not at 9router:20128 and not at a host-published public port.
The current split-origin machinery already provides the important security primitives:
proxy.tsmaps only declared managed-app hosts and does not expose cockpit routes on them;- the managed-app proxy calls
verifyAuth()before proxying HTTP; - WebSocket upgrades have their own approved-session gate;
- the cockpit
sessioncookie is stripped before requests are forwarded upstream; - upstream cookies are namespaced per managed app;
- the proxy target is constrained to loopback for ordinary HTTP proxying;
- unknown hosts inside the managed-app namespace fail closed instead of serving the cockpit.
The implementation should reuse those primitives rather than create a second auth system for 9Router.
Recommended default behavior
When MSO has enough information and authority to manage the deployment domain, installing 9Router should prefer the MSO app-host path automatically:
- Keep the container host publish at
127.0.0.1:20128:20128. - Configure/use
NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE={id}.mso.<owner-domain>. - Configure/use
OS_SESSION_COOKIE_DOMAIN=.mso.<owner-domain>and ensure the cockpit public origin is explicit. - Provision only the explicit
9router.mso.<owner-domain>DNS/TLS route required for the app host. - Route that hostname to the MSO web service / app-host proxy, not to the 9Router container.
- Require the user to sign in to MSO again after widening the cookie domain so the new cookie scope is actually issued.
- Prefer the app-host URL for the managed 9Router UI and keep
publicDashboardUrlaligned with it.
If MSO lacks DNS/TLS authority, installation must still succeed with 9Router private and healthy. The UI should explain that browser access is pending app-host provisioning rather than suggesting a direct public-port exposure.
No second login: security conditions
Skipping a separate 9Router login is safe only when all of the following are true:
- every public browser request to the 9Router UI passes through the MSO app-host auth gate;
20128is loopback-only on the host;- no legacy hostname routes directly to the 9Router container;
- no public-IP fallback is enabled (
NINE_ROUTER_EXPOSE_PUBLICremains off by default); - MSO strips its own session/auth headers before forwarding upstream, as it does today;
- logout/revocation at MSO immediately prevents new proxy access;
- any WebSocket/SSE paths used by 9Router are protected by the same MSO session boundary;
- the implementation has a defined answer for non-browser callers instead of silently making the private management UI an unauthenticated API gateway.
If 9Router itself later adds a mandatory vendor authentication layer that cannot be safely disabled for a loopback-only trusted proxy, MSO should not fake or synchronize passwords. The implementation must either keep that vendor auth or use a documented upstream trusted-proxy/SSO mechanism.
Docker-network caveat
A loopback host bind does not by itself make an unauthenticated container safe if the container is also attached to a broad shared Docker network. Another compromised container on that network may be able to reach 9router:20128 by container DNS/IP even though the host port is private.
Therefore an implementation that intentionally relies on MSO-only authentication should also review network reachability:
- prefer no shared proxy network when the app-host route terminates at MSO and MSO reaches 9Router through loopback;
- otherwise use a dedicated/private network with only the minimum required peers;
- do not attach 9Router to
dokploy-networkmerely so Traefik can proxy directly to it, because the target architecture does not require that direct path.
This network constraint is part of the auth boundary, not optional hardening.
Migration / cleanup rules
When adopting the app-host default on an existing install:
- Verify loopback health (
/api/health) first. - Provision and verify
9router.mso.<owner-domain>through MSO. - Verify an unauthenticated request to the app-host is rejected and an authenticated MSO session succeeds.
- Verify the MSO session cookie is not present in the upstream 9Router request.
- Verify WebSocket/SSE functionality if the dashboard uses it.
- Remove any direct public route such as
9router.<owner-domain> -> 9router:20128unless the operator explicitly chose a separate, independently authenticated exposure model. - Remove stale DNS only after the MSO app-host path is proven working.
- Keep rollback possible without reopening a direct unauthenticated route.
An old standalone hostname must not remain as an accidental authentication bypass just because it existed before MSO began managing the app.
UX expectation
The normal owner flow should be one conceptual setup:
Install 9Router -> MSO verifies runtime -> MSO prepares app-host -> user opens 9Router from MSO
The user should not need to understand container ports, Traefik service names, cookie domains, or a second password merely to use a managed app. Advanced operators may still opt into a standalone/vendor-authenticated exposure, but that is an explicit exception rather than the default path.
Acceptance criteria for the implementation PR
- Fresh managed install keeps
20128off public interfaces. - With a configured MSO domain/provider,
9router.mso.<owner-domain>is provisioned or surfaced as the deterministic desired hostname. - The hostname routes to MSO, never directly to the 9Router container.
- Anonymous navigation to the app-host cannot reach 9Router content.
- One valid MSO owner/operator session can use the 9Router dashboard without a second MSO-created password prompt.
- MSO session/auth material is absent from upstream requests.
- Device revocation/session expiry blocks subsequent app-host access.
- Direct legacy hostname/public-port bypasses are detected and clearly reported during migration.
- Shared-network reachability is either removed or explicitly constrained before relying on MSO as the only browser authentication layer.
- Existing lifecycle health/update/backup behavior continues to work without DNS as a hard dependency.
Non-goals
- Do not copy the MSO password into 9Router.
- Do not teach MSO to know or reset a vendor password unless upstream explicitly requires and documents that integration.
- Do not make 9Router share the cockpit origin.
- Do not weaken the existing split-origin/cookie isolation to remove a login prompt.
- Do not make successful DNS provisioning a prerequisite for starting or health-checking the runtime.