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
/**
* MSO-owned Orca state locations.
*
* The managed root is deliberately separate from the operator's own Orca state
* (`~/.orca`, `~/.orca-remote`). `ORCA_HOME` is honoured only when it is an
* absolute path with no traversal segment; otherwise the portable MSO default
* is used. Nothing here reads or resolves the user's existing Orca install.
*/
import { homedir } from 'node:os'
import { isAbsolute, join, normalize, sep } from 'node:path'
export const MANAGED_APP_ID = 'orca'
export const SERVICE_NAME = 'mso-orca.service'
/** Exact first line that marks a unit as generated by this adapter. */
export const UNIT_IDENTITY_MARKER = '# mso-managed-app: orca'
export const MANAGED_ROOT_RELATIVE_TO_HOME = ['.local', 'share', 'mso', 'orca']
export const SERVICE_CONFIG_FILENAME = 'managed-service.json'
export const INSTALL_RECEIPT_FILENAME = 'managed-install.json'
const CONTROL = /[\0\r\n]/
export function defaultManagedRoot({ home = homedir() } = {}) {
return join(home, ...MANAGED_ROOT_RELATIVE_TO_HOME)
}
function hasTraversal(value) {
return value.split(/[\\/]/).some((part) => part === '..')
}
/**
* Absolute managed root. A relative, blank, non-canonical or hostile `ORCA_HOME`
* is refused rather than silently reinterpreted: a typo must not point the
* installer at `/`, the home directory, or the operator's personal Orca state.
* A set-but-empty override is a misconfiguration, not "unset", so it never
* falls back to the portable default.
*/
export function resolveManagedRoot({ env = process.env, home = homedir() } = {}) {
const raw = env?.ORCA_HOME
if (raw === undefined) return defaultManagedRoot({ home })
if (typeof raw !== 'string' || raw.trim() === '') {
throw new Error('ORCA_HOME must be a non-empty absolute path')
}
if (CONTROL.test(raw)) throw new Error('ORCA_HOME must not contain control characters')
if (!isAbsolute(raw)) throw new Error(`ORCA_HOME must be an absolute path, got: ${raw}`)
const normalized = normalize(raw)
// A trailing slash, a `//`, or a `.`/`..` segment changes the canonical
// spelling; refuse it instead of quietly rewriting the operator's config.
if (normalized !== raw || (raw.length > 1 && raw.endsWith(sep))) {
throw new Error(`ORCA_HOME must be a canonical absolute path, got: ${raw}`)
}
if (hasTraversal(normalized)) throw new Error(`ORCA_HOME must not contain '..': ${raw}`)
if (normalized === sep) throw new Error('ORCA_HOME must not be the filesystem root')
const resolvedHome = normalize(home)
if (normalized === resolvedHome) throw new Error('ORCA_HOME must not be the home directory itself')
for (const denied of ['.orca', '.orca-remote']) {
const prefix = join(resolvedHome, denied)
if (normalized === prefix || normalized.startsWith(`${prefix}${sep}`)) {
throw new Error(`ORCA_HOME must not reuse the operator's ${denied} state`)
}
}
return normalized
}
export function serviceConfigPath(root) {
return join(root, SERVICE_CONFIG_FILENAME)
}
export function installReceiptPath(root) {
return join(root, INSTALL_RECEIPT_FILENAME)
}
/**
* Linux `sun_path` is 108 bytes including the trailing NUL. The upstream server
* binds a Unix socket at `<root>/runtime/user-data/o-<pid>-<hex>.sock`, so a
* managed root that is too deep makes `listen()` fail with a cryptic EINVAL
* before readiness is ever possible. Refuse it with a clear reason instead.
*/
export const UNIX_SOCKET_PATH_MAX_BYTES = 107
const UNIX_SOCKET_LEAF_RESERVE = 'o-1234567-abcd.sock'.length
export function assertManagedRootFitsUnixSocket(root) {
const socketPath = `${root}/runtime/user-data/${'x'.repeat(UNIX_SOCKET_LEAF_RESERVE)}`
if (Buffer.byteLength(socketPath) > UNIX_SOCKET_PATH_MAX_BYTES) {
throw new Error(
`managed root is too deep for the Orca runtime's Unix socket ` +
`(${Buffer.byteLength(socketPath)} > ${UNIX_SOCKET_PATH_MAX_BYTES} bytes); choose a shorter ORCA_HOME`
)
}
return root
}
export function orcaServiceUnitPath({ home = homedir() } = {}) {
return join(home, '.config', 'systemd', 'user', SERVICE_NAME)
}