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.
MSO Gateway architecture and operations
MSO Gateway is deployment-agnostic, supervisor-agnostic, and provider-agnostic by design.
The gateway core describes health, identity, ownership and lifecycle state. Cloudflare, Tailscale, ngrok, a reverse proxy, direct HTTPS, systemd, s6, Docker, Kubernetes and similar technologies are provider/supervisor/deployment choices rather than assumptions in the core state machine.
Architecture boundary
MSO Gateway Core
↓
Provider Adapter
↓
Process Supervisor / Runtime
↓
Deployment Environment
The current managed public adapter is Cloudflare. It remains the default for mso gateway start
and keeps the existing Quick Tunnel and named-tunnel safety contract, but Cloudflare-specific binary,
config and launch details stay behind the provider boundary.
Conceptually the core can support:
┌─ Cloudflare Tunnel
├─ Tailscale
Gateway Core ─────├─ ngrok
├─ reverse proxy
├─ direct HTTPS gateway
└─ future provider
and the lifecycle can be hosted by:
┌─ systemd
├─ s6
Gateway lifecycle ───────├─ Docker / Compose
├─ Kubernetes
├─ external supervisor
└─ foreground/manual
Adding another managed provider should implement the provider adapter/capability contract rather than add provider-name branches throughout the core.
State model
mso gateway status --json exposes the provider-neutral state model. Human status preserves the legacy
gateway: running line for healthy running states and adds the precise state/dimensions.
| State | Meaning |
|---|---|
managed-running |
MSO proves ownership of its provider process and local/public identities match. |
external-running |
No MSO-owned provider process exists, but the configured public origin returns the exact selected local MSO identity. |
degraded |
A provider/public route exists or is recorded, but local/public/provider health is not fully healthy. |
recovering |
MSO has durable managed lifecycle evidence but the recorded provider process is stale/missing and needs safe reconciliation. |
stopped |
No owned provider is active and no verified external public route is responding. |
unknown |
State is unsafe/corrupt or cannot be classified safely. |
The dimensions are independent:
localHealth
publicHealth
providerHealth
processHealth
ownership
supervisor
Example managed state:
{
"state": "managed-running",
"ownership": "mso",
"provider": "cloudflare",
"supervisor": "mso-lifecycle",
"localHealth": "healthy",
"publicHealth": "healthy",
"providerHealth": "healthy",
"processHealth": "alive"
}
Example external state:
{
"state": "external-running",
"ownership": "external",
"provider": "custom",
"supervisor": "external",
"localHealth": "healthy",
"publicHealth": "healthy",
"processHealth": "external"
}
provider is dynamic. custom means the public route is verified but MSO does not have enough safe
evidence to name the provider. MSO does not guess provider ownership from a hostname or process name.
Public health and deployment identity
Process existence is not public readiness. A managed tunnel start also refuses to forward an already-bound loopback port unless that listener is either an MSO-owned fallback runtime or is proven by socket inode + cgroup + working-directory evidence to belong to this checkout's active mso.service. A health-shaped HTTP response alone is not runtime identity.
MSO probes the configured public origin at:
https://<public-origin>/api/health
It validates the MSO health contract and compares the public health identity with the selected local
runtime. Identity includes version, buildId, optional buildSha, and runtimeInstanceId.
Therefore:
local healthy
public HTTP healthy
public identity != local identity
is an identity-mismatch and produces a degraded state, not a healthy gateway. This catches a valid
hostname that is routing to a different MSO deployment.
Status and doctor are observational. A failed probe does not itself restart a provider. Existing managed reconciliation remains bounded by proven MSO ownership; external gateways are report-only. This avoids turning transient edge/DNS failures into restart storms.
Provider adapter capabilities
The gateway provider boundary reports capabilities instead of making the core branch on provider names. The current capability vocabulary includes:
publicHealthProbe
managedProcess
namedEndpoint
externalDetection
restart
reconnect
credentialsRequired
dnsRouting
Cloudflare currently reports managed-process/restart/reconnect support. A generic external/custom route reports public-health/external-detection capability but no managed-process/restart authority.
The managed adapter contract is intentionally small: parse/validate start intent, start/reconcile through its provider implementation, inspect health/state through the generic core, and expose capabilities. Provider-specific tool/tunnel code is loaded lazily through this boundary, so read-only status/external-route paths do not import the Cloudflare adapter and generic reconciliation calls the provider probe contract rather than a Cloudflare helper. This is additive to the existing shell architecture; it is not a new heavyweight plugin framework.
Managed versus external gateway
Managed gateway
MSO records and verifies process identity before mutation. Existing protections remain authoritative:
- PID plus kernel process start ticks;
- executable identity;
- command-line identity where stable;
- runtime instance identity for Next;
- owner-private atomic lifecycle state;
- held-child launch handshake;
- checkout/update locks and recovery markers.
mso gateway stop terminates only identities proven to be owned by MSO.
External/unmanaged gateway
When no MSO-owned provider exists but OS_PUBLIC_ORIGIN returns the exact local MSO health identity,
status reports external-running and ownership: external.
For external processes MSO may:
detect yes
inspect yes
health check yes
stop no
restart no
auto-adopt no
mso gateway stop never searches for and kills external tunnel/reverse-proxy processes. There is no
automatic adoption mechanism. Any future adoption feature must be an explicit, separately verified action.
An implicit mso gateway start refuses to create a duplicate connector when a verified external route is
already present. An explicit named-provider start remains an operator-directed action and retains its
existing provider validation contract.
mso gateway status
Human-readable status includes the precise state plus provider/ownership/supervisor and health dimensions:
gateway: running
state: external-running
provider: custom
ownership: external
supervisor: external
process-health: external
local-health: healthy
public-health: healthy
provider-health: healthy
public: https://mso.example.com
local: http://127.0.0.1:4005
Use structured output for automation:
mso gateway status --json
Exit status is 0 for managed-running / external-running, 1 for stopped, and 2 for degraded,
recovering or other non-healthy classified states.
mso gateway doctor
Doctor is read-only. It checks independent dimensions rather than treating Cloudflare availability as the gateway definition:
- selected local MSO health identity;
- raw application binding/exposure safety;
- configured stable public origin;
- public health contract and identity match;
- lifecycle state and ownership;
- process/provider health classification;
- supervisor context;
- provider-specific diagnostics only when relevant.
The Cloudflare adapter diagnostic never downloads or installs a binary during doctor. Managed installation
remains an explicit mso gateway install or managed-start concern.
A public route may be healthy while doctor separately reports an unsafe local bind. For example, a working
reverse proxy does not make 0.0.0.0:4005 safe; the application should normally remain loopback-only.
Supervisor and deployment model
The core does not require systemd. Application lifecycle, gateway lifecycle, provider lifecycle and host lifecycle are separate.
Normal VPS / bare metal
systemd (or another host supervisor)
→ MSO runtime on loopback
chosen gateway provider / reverse proxy
→ public HTTPS origin
The standard installer may use systemd when it is actually available, but the gateway state machine does not derive health/ownership from systemd.
Container / Docker Compose
container lifecycle
→ MSO foreground runtime on loopback/container-private interface
external or sidecar gateway/reverse proxy
→ public origin
Use the container restart policy/orchestrator as the supervisor. MSO can inspect a configured external public route without claiming its process.
s6 / external supervisor
s6
→ MSO runtime
→ selected gateway/reverse-proxy lifecycle
The supervisor owns its processes; MSO reports external-running when the public identity is valid.
Kubernetes
Pod/container lifecycle
→ MSO runtime
Service/Ingress/Gateway implementation
→ configured public origin
Kubernetes owns restart/reconciliation. MSO observes the public identity and does not attempt to kill or adopt ingress/controller processes.
WSL / sandbox / remote development
mso web continues to support the already-built loopback fallback without requiring systemd. The managed
Cloudflare adapter remains available where its binary/process contract is supported, while an externally
provided route is classified independently.
Why there is no new mso gateway supervise command yet
This refactor does not add a second process-supervision implementation merely for abstraction. Existing MSO-managed Cloudflare lifecycle stays intact, and systemd/s6/container/Kubernetes/reverse-proxy deployments are represented safely as externally supervised routes. That is enough to make core health/state portable without duplicating supervisor semantics.
A future foreground gateway supervise should be added only when a managed provider needs one common
signal-aware foreground contract across supervisors. If added, it must use the same provider adapter,
ownership proof, deterministic exit codes and structured health model; it must not daemonize or assume a
specific init system.
Optional cron heartbeat
mso heartbeat is a one-shot health/recovery command, disabled by default. It uses structured gateway
health (including the public MSO identity), rather than treating a live connector PID as healthy.
It starts no monitoring daemon and installs no packages. Existing gateway lifecycle commands retain
update serialization, loopback binding, credential validation and exact process ownership checks.
For a built loopback fallback, set this in the installation's owner-only .env.local:
OS_HEARTBEAT_ENABLED=1
OS_HEARTBEAT_INTERVAL_MINUTES=30
OS_HEARTBEAT_FAILURE_THRESHOLD=1
Run mso heartbeat install-cron once to install a check every 30 minutes and at cron startup. The host
must run cron; in a container the platform must start it after a restart. An @reboot entry does not
keep a suspended workspace alive. The installer preserves unrelated cron jobs and captures the current
Node executable directory in the job's PATH. Repeat installation after changing the interval or Node path.
Set OS_HEARTBEAT_ENABLED=0 to disable checks without removing the job, or run
mso heartbeat remove-cron to remove only this checkout's entries. Existing systemd/s6/container/external
supervisors remain responsible for their own services; heartbeat reports their unhealthy state without
adopting or stopping them.
For an already MSO-managed named gateway, also set OS_HEARTBEAT_GATEWAY_CONFIG to its dedicated
owner-owned config file and OS_HEARTBEAT_GATEWAY_TUNNEL to its name/UUID. The recipe must pass the
existing named-gateway preflight before anything is stopped. OS_PUBLIC_ORIGIN must match the config.
Heartbeat never replaces a named tunnel with a temporary quick tunnel or adopts an external connector.
A stopped external public route requires its own supervisor; setting these values is not an adoption flow.
Each invocation holds a checkout/origin/env-scoped lock and persists only a timestamp, result and
consecutive failure count under ~/.mso/private/heartbeat/. Exit 0 means healthy/recovered, disabled or
already being checked; exit 2 means unhealthy/report-only; exit 1 indicates a validation/lifecycle error.
The default threshold of 1 repairs on the first scheduled failure. Higher thresholds count failed
scheduled checks, not seconds. mso heartbeat once runs the same check manually without scheduling it.
Operational examples
Cloudflare remains the current managed/default provider:
mso gateway start
mso gateway status
mso gateway status --json
mso gateway doctor
mso gateway stop
For a named Cloudflare endpoint:
mso gateway domain set https://mso.example.com
mso gateway start --config ~/.cloudflared/config.yml --tunnel <name-or-uuid>
For Tailscale, nginx/Caddy/Traefik, Kubernetes Ingress/Gateway, PaaS routing or another external provider,
keep MSO on its private/loopback binding where topology permits, set the stable OS_PUBLIC_ORIGIN, and let
the external supervisor/provider own its process lifecycle. mso gateway status --json will report the
route as external only after the public identity matches the selected local MSO runtime.