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.
Contributing
MSO is a focused, single-owner project. Issues and pull requests are welcome, but changes should preserve the narrow security and deployment model.
Setup
bun install
cp .env.example .env.local
bun run dev
Set OS_LOGIN_PASSWORD and OS_SESSION_SECRET for live auth. The mock adapters let most UI
work proceed without VPS credentials or host access.
Before a PR
Run:
bash scripts/gates-12.sh full
bun run verify
node scripts/check-docs.mjs
bash scripts/verify-build.sh
Start with bash scripts/gates-12.sh full. It is the local mirror of the GitHub
Actions verify job: the same checks in the same order, so a red build shows up on your
machine instead of in your Actions minutes. full adds coverage, the production build and
every browser journey; the default fast mode is about two minutes and skips the slow
three.
A clean run ends with either of these, and both are green:
mode=full passed=17 failed=0 skipped=0
mode=full passed=16 failed=0 skipped=1
The difference is the bundle budget, which verify-build.sh enforces inside the same run
rather than twice, so it reports as SKIP rather than PASS.
Run only one gates-12.sh at a time per worktree. Two concurrent full runs corrupt
each other in ways that look like real defects: vitest refuses to start because both
write the same coverage/ directory, and verify-build.sh copies the tree into /tmp
per run, so two copies can exhaust the tmpfs. fast mode alongside full is also unsafe:
they share /tmp/gate-out.txt, so one run's failure text can appear under the other's
name.
bun run verify covers typecheck, lint, the Vitest suite, repository checks and the
high/critical dependency audit. verify-build.sh compiles a throwaway copy of HEAD so it
is safe even when the checkout is also the production WorkingDirectory.
Do not run a bare production build inside a live production checkout merely to prove
that code compiles; replacing .next underneath next start can create a chunk mismatch
until the service is replaced.
Where the CI work actually runs
The verify job is fully reproducible locally; the security workflows are not yet, and
this is deliberate rather than an oversight:
| Workflow | Local equivalent |
|---|---|
ci.yml verify |
bash scripts/gates-12.sh full |
ci.yml native-host (macOS/Windows) |
not reproducible; needs those runners |
ci.yml dependency-watch |
bun run audit:strict plus npm audit --prefix scripts/install/node-gyp --omit=dev --audit-level=high |
security-core.yml |
partially: docs/SELF-HOSTED-CI.md lane is BLOCKED |
codeql.yml, dast.yml, dependency-review.yml, scorecard.yml, security-alerts.yml, codex-security.yml |
no local equivalent |
bun run ci:plan prints the repository-owned CI plan, and bun run ci:verify --sha "$(git rev-parse HEAD)" runs it. The security and release profiles return BLOCKED
on purpose: the scanner adapters are written but not yet verified end to end, and a
blocked lane must never be reported as a pass. See
docs/SELF-HOSTED-CI.md for the migration matrix and the
evidence rules.
You can still run the three scanners by hand with the exact image digests the workflows pin. All three have been verified locally:
docker run --rm -v "$PWD:/src:ro" semgrep/semgrep@sha256:f1f7b71861c7b28b6e0f661225a2c4f58a484f5d0f182465c6d6b3b22f972ade \
semgrep scan --metrics=off --config=p/javascript --config=p/typescript \
--config=p/owasp-top-ten --strict --error \
--exclude=node_modules --exclude=.next --exclude=coverage /src
docker run --rm -v "$PWD:/repo" zricethezav/gitleaks@sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9ab65d25e6bc8abbb7f \
git --gitleaks-ignore-path /repo/.gitleaksignore /repo
docker run --rm -v "$PWD:/src:ro" ghcr.io/google/osv-scanner@sha256:8108ae94eadea5a02c9bec6e646909d5b790b44bd62d7f5b7f0b1d6d0ffc7734 \
scan source --recursive /src
The --exclude flags are not decoration. CI scans a clean checkout; a working tree also
has node_modules, .next and coverage, and scanning those produces findings in
third-party code that CI never sees. Without them Semgrep reported 7 findings here and
0 with them.
Run the Gitleaks command from the main checkout, not from a git worktree. A worktree's
.git is a file pointing at the real git dir, so the scanner sees no repository and reports
0 commits scanned followed by no leaks found. That reads like a pass and proves nothing:
the same command in the main checkout scanned 1165 commits and is the only form of the
check that means anything.
The OSV result depends on bun.lock. It reports No issues found on a tree that already
carries the minimatch override to 11.0.3, and two medium findings (minimatch 3.1.5 and
10.2.6) on one that does not. If you see those two, the fix exists and your base predates it,
so rebase rather than adding a second override block.
Two things these catch that the gates do not. Semgrep fails on a parse warning under
--strict even with zero findings, so a generic type argument on await importOriginal<...>() in a test breaks the required check; apply the type with a cast on
its own const instead. Gitleaks scans all history, so a secret in an old commit fails the
check regardless of what your diff contains.
The committed source of truth for pre-push policy is scripts/gates.sh. The actual
.git/hooks/pre-push file is intentionally a tiny untracked shim. Install/reinstall it with:
bash scripts/gates.sh --install
A healthy push runs the shared typecheck/lint/test path (or in-repo fallback), cycle/docs/ changelog checks, dependency audit and the out-of-tree build. It should end with both:
audit: clean at high/critical.
build: HEAD compiles (out-of-tree).
The GitHub CI workflow is still useful for a clean-checkout dependency/install proof,
especially after changes to package.json, bun.lock or installer/release scripts.
Conventions
The current architecture is in docs/ARCHITECTURE.md and the
documentation map is docs/README.md. Reviewers will hold changes to
these rules:
- vertical application slices live under
frontend/slices/<slug>/; - cross-slice imports use public barrels;
- host operations flow through
lib/hostinstead of reimplementing path/process guards in routes or components; - keep files small/single-purpose where practical and use the existing UI primitives/tokens;
- keep responsive/mobile behaviour first-class;
- preserve the single catch-all app routing model;
- use conventional commit subjects.
When you add/remove/rename a current capability, update the relevant current reference doc
in the same change. scripts/check-docs.mjs catches selected machine-verifiable drift but
cannot infer every semantic change.
Releasing maintainer changes
Normal contributor PRs should not deploy production. The maintainer release path after a verified merge is:
bun run ship "feat(scope): describe the verified change"
A Git push by itself is not deployment. See docs/DEVELOPMENT.md.
Security issues
Do not open a public issue containing exploit details or secrets. Follow
SECURITY.md.