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.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
// Every knob the code reads must be documented where someone would look for it.
//
// CLAUDE.md carries this as a chore ("still grep process.env before adding a new
// one"), and the chore had already slipped: `OS_CODEX_BUILTIN_TOOLS` — which turns
// on provider-run tools that BILL to the owner's account — was readable by the code
// and absent from `.env.example`. A var nobody can find is a var nobody can turn
// off. This is that grep, run by the suite instead of by memory.
//
// The allowlist below is the other half of the contract: vars that are deliberately
// NOT in .env.example because you never set them by hand. Each one carries the
// reason, so adding to this list is a decision rather than a way to silence a test.
import { existsSync, readFileSync } from "node:fs";
import { execSync } from "node:child_process";
import path from "node:path";
import { describe, expect, it } from "vitest";
const ROOT = path.join(__dirname, "..", "..");
/** Not documented in .env.example, on purpose. */
const NOT_A_KNOB: Record<string, string> = {
// Injected by the framework or the runtime.
NEXT_RUNTIME: "set by Next itself",
NODE_ENV: "standard Node/Next process mode; artifact maintenance starts only in production",
NEXT_PUBLIC_BUILD_ID: "injected by next.config.mjs at build time",
MSO_RUNTIME_INSTANCE_ID: "injected by the installer-managed service to prove restart readiness",
// Set by scripts/verify-build.sh in the out-of-tree archive it just built, so the
// bundle budget knows those bytes describe that source rather than a stale .next.
MSO_BUNDLE_BUILD_IS_CURRENT: "set by scripts/verify-build.sh for its own out-of-tree build; never user configuration",
// Private launcher-to-agent handoff. scripts/mso-cli-agent.sh owns these; users
// should configure the public CLI knobs instead of persisting these in .env.local.
MSO_AGENT_BASE: "internal mso-cli-agent launcher handoff for the selected loopback API base",
MSO_AGENT_CLI: "internal mso-cli-agent launcher handoff for the canonical CLI path",
MSO_AGENT_JAR: "internal mso-cli-agent launcher handoff for the authenticated cookie jar",
MSO_AGENT_ORIGIN: "internal mso-cli-agent launcher handoff for the request Origin header",
MSO_MAINTENANCE_LOCKED: "internal maintenance-lock.sh child handoff; never persist or set this as user configuration",
MSO_AGENT_VERSION: "internal mso-cli-agent launcher handoff for banner metadata",
// Read by bin/orca-mcp.mjs, an MCP stdio bridge a client spawns locally. It
// points at the Orca CLI binary; the app itself never reads it.
ORCA_BIN: "override for the Orca CLI path used by the bin/orca-mcp.mjs stdio bridge, not by the MSO app",
// Standard terminal convention inherited from the invoking shell, not MSO config.
NO_COLOR: "standard terminal color convention inherited from the caller",
VITEST: "set by the test runner",
// Read by scripts/integrations-ui-evidence.mjs, the browser evidence harness.
MSO_EVIDENCE_DIR: "output directory for the integrations UI evidence harness; local diagnostics only",
// The OS gives these to every process.
SHELL: "the OS's",
PATH: "standard executable search path inherited by the lifecycle test harness",
HOME: "the OS's",
XDG_RUNTIME_DIR: "set by logind, or by the unit — see lib/managed-apps/user-bus.ts",
// Standard XDG base directory. Read only as the default parent of the update timer
// units; MSO_SYSTEMD_USER_DIR is the documented override.
XDG_CONFIG_HOME: "standard XDG base-directory convention; MSO_SYSTEMD_USER_DIR overrides its use",
// scripts/audit.mjs seams, not app configuration: the audit contract tests shorten
// the bounded registry probe and relocate its receipt so they never touch the cache.
MSO_AUDIT_TIMEOUT_MS: "scripts/audit.mjs registry probe ceiling; test seam",
MSO_AUDIT_ATTEMPTS: "scripts/audit.mjs registry probe retry count; test seam",
MSO_AUDIT_BACKOFF_MS: "scripts/audit.mjs registry probe backoff; test seam",
MSO_AUDIT_BUDGET_MS: "scripts/audit.mjs registry probe total budget; test seam",
MSO_AUDIT_RECEIPT: "scripts/audit.mjs receipt path; test seam, not user configuration",
// systemd's, read by instrumentation for the watchdog handshake.
NOTIFY_SOCKET: "systemd's",
WATCHDOG_USEC: "systemd's",
// Orca lifecycle test fixtures. scripts/orca/fixtures/*.mjs are disposable
// stand-ins for the real server, daemon, and CLI; these select fake behavior.
FAKE_ADVERTISED: "Orca test fixture only: fake server's advertised pairing endpoint",
FAKE_CLI_LOG: "Orca test fixture only: fixture CLI invocation log path",
FAKE_CLI_MODE: "Orca test fixture only: fixture CLI behavior selector",
FAKE_CLI_TOKEN: "Orca test fixture only: fixture CLI echo token",
FAKE_CRASH_DELAY_MS: "Orca test fixture only: fake server's delayed-crash timing",
FAKE_DAEMON_DELAY_MS: "Orca test fixture only: fake daemon's pid-record delay",
FAKE_DAEMON_ENTRY: "Orca test fixture only: fake server's daemon entry path",
FAKE_MODE: "Orca test fixture only: fake server scenario selector",
FAKE_READY_DELAY_MS: "Orca test fixture only: fake server's delay before readiness output",
// Private installer handoff. lib/managed-apps/install.ts derives these from
// operator-facing install options and passes them to the install scripts.
MSO_INSTALL_APP_ORIGIN: "private MSO installer-to-app handoff for the configured split app origin; not an operator knob",
MSO_INSTALL_GATEWAY_BIND: "private MSO installer-to-app handoff for the validated gateway bind mode; not an operator knob",
// Private Orca runtime environment. scripts/orca/env.mjs writes this into the
// isolated child env so the runtime uses the scratch user-data directory.
ORCA_USER_DATA: "private isolated Orca runtime env set by scripts/orca/env.mjs; not a deployment knob",
// Test + tooling only, never part of a deployment.
E2E_BASE_URL: "test harness",
MSO_SCREENSHOT_DIR: "injected per-session artifact staging path for browser tooling; never persistent app configuration",
E2E_DEMO: "desktop browser harness only: preview has no authentication; never production configuration",
E2E_CAPTURE_ONLY: "desktop browser harness only: capture baseline before native behavior assertions",
CHROME_PATH: "MCP Page browser contract harness executable override, not production configuration",
MSO_SOCKET_POLICY_SECRET: "generated fresh by the production process; never an operator knob",
E2E_PASSWORD: "test harness",
E2E_DEVICE: "test harness",
E2E_HEADED: "test harness",
MSO_RUNTIME_PROC_ROOT: "test-only fake /proc root for live-runtime ownership tests",
OS_MEDIA_BASE: "scripts/gen-readme-media.mjs only",
OS_MEDIA_DEVICE: "scripts/gen-readme-media.mjs only",
};
function usedEnvNames(): string[] {
const files = execSync("git ls-files --cached --others --exclude-standard '*.ts' '*.tsx' '*.mjs'", { cwd: ROOT, encoding: "utf8" })
.split("\n")
.filter(Boolean)
// A test may stub anything, so .test files do not count as "the app reads it".
// The e2e HARNESSES do count — they are committed code, and the vars they read
// are exactly the ones that belong in NOT_A_KNOB rather than in .env.example.
.filter((f) => !f.includes(".test."))
// `git ls-files --cached` still reports tracked paths deleted in the working tree.
// Ignore those so pre-commit verification can validate intentional file retirement.
.filter((f) => existsSync(path.join(ROOT, f)));
const names = new Set<string>();
for (const file of files) {
const src = readFileSync(path.join(ROOT, file), "utf8");
for (const m of src.matchAll(/process\.env\.([A-Z][A-Z_0-9]{2,})/g)) names.add(m[1]);
// `process.env["X"]` and destructuring are not used here; if they appear, this
// regex stops seeing them — which is why the reconciliation lives in a test that
// someone will read, not in a silent script.
}
return [...names].sort();
}
describe(".env.example documents every knob", () => {
const example = readFileSync(path.join(ROOT, ".env.example"), "utf8");
const documented = new Set(
[...example.matchAll(/^#?\s*([A-Z][A-Z_0-9]+)=/gm)].map((m) => m[1]),
);
it("has a line for each env var the app reads", () => {
const missing = usedEnvNames().filter((n) => !documented.has(n) && !(n in NOT_A_KNOB));
expect(missing, "add these to .env.example, or to NOT_A_KNOB with a reason").toEqual([]);
});
it("keeps the exemption list honest — every entry is still read somewhere", () => {
const used = new Set(usedEnvNames());
// An exemption for a var the code no longer reads is stale lore that outlives
// the reason it was written.
const stale = Object.keys(NOT_A_KNOB).filter((n) => !used.has(n));
expect(stale, "these are exempted but no longer read — drop them").toEqual([]);
});
});