Skip to content

armgit / mso

Public Imported from GitHub
0

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.

30.1 KB
Raw Blame
# mso — environment. Copy to .env.local (gitignored) and fill in.
# mso is self-contained: a Next.js app that runs AS a host process and
# controls the machine it runs on. No database, no external backend.

# --- Auth (required) ---
# Owner-first deployment login. Min 6 chars; use a strong password for any exposed host.
# Each approved browser is assigned Viewer, Operator, or Owner. Roles are device-scoped
# application controls over one Unix service account—not named-user SSO or Linux users.
# Device approval is a browser allowlist, not standards-based MFA.
OS_LOGIN_PASSWORD=change-me
# HMAC key that signs the session cookie. MUST be strong — generate with:
#   openssl rand -hex 32
OS_SESSION_SECRET=
# Session lifetime in hours (default 24). Keep it short — a live session can run
# shell commands. Raise only behind a trusted network.
# SESSION_EXPIRY_HOURS=24
# The cockpit session cookie is always host-only. The obsolete OS_SESSION_COOKIE_DOMAIN
# setting is used only for clearing legacy cookies. App hosts use separate tickets.

# Experimental source-only tenancy seam. Default legacy leaves current behavior unchanged.
# tenant-preview denies unimplemented capabilities and has no live registry/storage adapter.
# Do not enable on a production/shared-user deployment; it is not multiuser readiness.
# OS_TENANCY_MODE=legacy
# Existing canonical private tenant store; no default, auto-initialization or enrollment.
# OS_TENANCY_STORAGE_ROOT=

# --- Filesystem bounds (optional) ---
# Colon-separated roots. "~" = home, "/" = whole filesystem.
# READ defaults to the running checkout + ~/projects; add other roots deliberately.
# OS_AGENT_VAULT_ROOT=~/mso-vaults
# OS_AGENT_VAULT_PROJECT=                 # Optional default source repo id/name/path; private local configuration
# OS_FS_READ_ROOTS=/
# WRITE defaults to home + ~/projects (narrow, so the OS can't clobber system files).
# OS_FS_WRITE_ROOTS=~:~/projects
# Sensitive home files (~/.ssh, ~/.aws, shell history, shell rc/profile files —
# where `export …_TOKEN=` lines live — …) are blocked even within
# the read roots. Set =1 to lift that denylist (you accept the exposure).
# OS_FS_ALLOW_SENSITIVE=1
# Optional markdown vault for the Memory app (/memory, `mso memory-graph`).
# Must sit inside OS_FS_READ_ROOTS. The owner can also type a path in the app.
# ~/vault is on the sensitive-home denylist; use a path such as ~/notes or
# ~/obsidian/vault. Unset scans project knowledge and agent memory only.
# OS_MEMORY_GRAPH_ROOT=

# --- Exec safety + audit (optional) ---
# Catastrophic shell commands (rm -rf /, mkfs, dd to a block device, fork bomb…)
# are refused by default. Set =1 to allow them (do real disk surgery over SSH).
# OS_EXEC_ALLOW_DESTRUCTIVE=1
# Append-only audit trail of exec/file/browser/auth actions. Default path below.
# OS_AUDIT_LOG=~/.mso/audit.log
# Optional override for the owner-private, metadata-only Channels store.
# OS_CHANNEL_STORE=~/.mso/private/channels.json
# Transcript of the last Settings → About "Software update" run — the panel polls
# this file, and scripts/self-update.sh truncates it on every start. Rarely worth
# moving; it is here because the updater runs as a transient systemd unit and the
# path is passed to it explicitly rather than inherited.
# MSO_UPDATE_LOG=~/.mso/self-update.log
# Where the unattended updater records its last attempt and failure streak. Written by
# the nightly timer, read by Settings → Update MSO; never set by a client. Delete it to
# clear a pause after two failed builds (or run `mso update`, which does that for you).
# MSO_AUTO_UPDATE_STATE=~/.mso/auto-update-state.json
# Directory the nightly update timer units are written to. Defaults to
# $XDG_CONFIG_HOME/systemd/user (or ~/.config/systemd/user). Override only in tests or
# on a host whose user manager reads units from a non-standard path.
# MSO_SYSTEMD_USER_DIR=~/.config/systemd/user
# Optional advanced SSH transport override for custom/private Git origins. Canonical
# MSO origins are normalized to public HTTPS, so ordinary installs should leave this
# unset. When unset, MSO update paths use `ssh -oBatchMode=yes` for non-interactive
# custom SSH remotes; set only when your private/fork origin needs another SSH command.
# GIT_SSH_COMMAND=
# Number of trusted reverse-proxy hops in front of the app. Public rate
# limiters key on the (N-from-last) x-forwarded-for hop, so a wrong value
# collapses every client into one bucket (too small N) or trusts spoofed
# client headers (too large N).
# Default 0 ignores forwarding headers. Set 1 for a direct trusted proxy or 2
# for Cloudflare → nginx → app only when direct origin access is firewalled.
# OS_TRUSTED_PROXY_HOPS=0


# --- System Monitor Service Center (optional) ---
# Inventory for system/user *.service units is read-only by default. Logs require
# Operator/Owner. Lifecycle requires BOTH Operator/Owner and an exact comma/space
# separated scope:unit entry below. Wildcards, paths, flags and non-service units
# are ignored/rejected. Example:
# OS_SERVICE_CONTROL_UNITS=user:mso.service,system:nginx.service
# System units use the process user's existing permission. Set =1 only when you have
# deliberately granted narrowly-scoped non-interactive sudo for the exact units/actions.
# Never pair this with broad NOPASSWD systemctl/root access.
# OS_SERVICE_CONTROL_USE_SUDO=0
# Advanced binary overrides; normally leave unset. Useful only on unusual layouts/tests.
# MSO_SYSTEMCTL_BIN=/usr/bin/systemctl
# MSO_JOURNALCTL_BIN=/usr/bin/journalctl
# MSO_SUDO_BIN=/usr/bin/sudo
#
# Package Updates reads the EXISTING local cache only; it never refreshes or applies.
# Auto-detected managers: apt, dnf, yum, pacman, zypper. Optional detection/binary overrides:
# MSO_PACKAGE_MANAGER=apt
# MSO_APT_BIN=/usr/bin/apt
# MSO_DNF_BIN=/usr/bin/dnf
# MSO_YUM_BIN=/usr/bin/yum
# MSO_PACMAN_BIN=/usr/bin/pacman
# MSO_ZYPPER_BIN=/usr/bin/zypper

# --- Stock photo search (optional) ---
# The image picker's Stock tab searches the keyless Openverse API by default.
# Set an Unsplash Access Key (https://unsplash.com/developers) to search
# Unsplash instead (better quality). The key stays server-side.
# OS_UNSPLASH_ACCESS_KEY=

# --- AI assistant "Alfa" (optional, BYOK) ---
# Bring your own Anthropic key. Can also be set in the OS via Settings → AI
# (stored in ~/.mso/config.json). If unset, the assistant returns 501.
# ANTHROPIC_API_KEY=
# Official OpenAI API key. It may instead be saved through Settings → AI under
# provider OpenAI; the 0600 host credential store wins over this env fallback.
# OPENAI_API_KEY=
# Custom provider base URLs require HTTPS and public DNS/IP destinations. Set this
# only for an explicitly trusted loopback/LAN development endpoint; production
# requests still apply destination validation and redirect controls.
# OS_CUSTOM_PROVIDER_ALLOW_INSECURE_HTTP=0
#
# Provider-run tools the Codex backend may use, comma/space separated. EMPTY by
# default — no provider built-in is declared unless you name one here. Allowed:
# web_search, web_search_preview, file_search, code_interpreter,
# computer_use_preview, local_shell. `image_generation` is NOT allowed: MSO has no
# image generation on any surface, and a GPT client already carries its own.
# Provider-run usage may bill the connected ChatGPT account.
# OS_CODEX_BUILTIN_TOOLS=

# --- Managed apps: Hermes / OpenClaw (optional) ---
# MSO detects these two known apps through bounded service/package probes and can
# install/control/log/update/back up/restore them. It does NOT scrape vendor SPA routes
# into MSO features. The URLs below are only the known loopback dashboards used by the
# optional split-origin proxy.
# HERMES_DASHBOARD_URL=http://127.0.0.1:9119
# OPENCLAW_DASHBOARD_URL=http://127.0.0.1:18789
# NINE_ROUTER_DASHBOARD_URL=http://127.0.0.1:20128
# Existing browser-facing 9Router URL, if the deployment already owns one. This is
# preferred for the in-shell UI; do not create a new subdomain just because MSO can.
# Without it, MSO may use its split-origin host. There is no public-IP fallback
# unless the operator explicitly enables the Docker bind below.
# NINE_ROUTER_PUBLIC_URL=https://9-router.example.com
# Default 0: publish 127.0.0.1:20128 only. Set 1 only with a deliberate firewall/auth
# decision; this exposes 9Router's credential-bearing dashboard on every interface.
# NINE_ROUTER_EXPOSE_PUBLIC=0
# Hermes install home. Default ~/.hermes. Absolute, or "~/…" for the home of the
# user running mso. This is the tree the managed-app backup action copies.
# HERMES_HOME=/home/you/.hermes

# Public origin the BROWSER uses, e.g. https://mso.example.com. Only the scheme
# + host + port are read. Set this only to the deployment's stable HTTPS hostname
# (normally with `mso gateway domain set https://mso.example.com`). Never use a
# random *.trycloudflare.com Quick Tunnel URL as OS_PUBLIC_ORIGIN.
# The managed-app proxy scopes its Content-Security-Policy
# to this origin; without it the origin is inferred from the Host header and then
# from X-Forwarded-Host, and the latter is client-settable — set this whenever the
# app sits behind a reverse proxy so the policy can't be steered by a request.
# In split-origin mode (below) this is also the origin the app hosts name in
# `frame-ancestors`, so it decides whether the cockpit may frame the dashboard at
# all. Unset, it falls back to the parent name of the host template
# (`{id}.mso.example.com` → `https://mso.example.com`); if THAT yields nothing
# usable the policy emits `frame-ancestors 'none'` and the window stays blank —
# closed, on purpose, rather than naming a guessed origin as a permitted framer.
# OS_PUBLIC_ORIGIN=https://mso.example.com
# Optional operator-declared role shown in private connection diagnostics.
# Allowed: development, test, staging, production. Unset/invalid means not configured.
# This is independent of NODE_ENV; a production build does not identify a production host.
# OS_INSTANCE_ENVIRONMENT=staging
# Compatibility fallbacks for MCP/browser origin discovery when OS_PUBLIC_ORIGIN is unset.
# Prefer OS_PUBLIC_ORIGIN for normal MSO deployments.
# APP_URL=https://mso.example.com
# NEXT_PUBLIC_APP_URL=https://mso.example.com
# Optional dedicated origin assigned to ChatGPT MCP Apps. When unset, MSO derives
# mso-ui.<rest-of-host> from a leading mso.<rest-of-host>; otherwise it reuses the
# sanitized public origin. This is instance configuration, never source-owned.
# OS_MCP_UI_ORIGIN=https://mso-ui.example.com
# Reviewed Page/Surface app catalog. Portable source stays empty; each owner may
# maintain ~/.mso/surface-apps.json (0600) as the live per-instance registry. The
# Page re-reads it when resources/read runs, so reviewed app/CSP changes do not
# require a source edit or rebuild. Optional alternate file:
# MSO_SURFACE_APPS_FILE=~/.mso/surface-apps.json
# Backward-compatible deployment override: when this variable is DEFINED it wins
# over the file (an empty value intentionally disables external Page apps).
# MSO_SURFACE_APPS_JSON=[{"id":"demo","title":"Demo","description":"Reviewed instance app","origin":"https://demo.example.com","startPath":"/embed","renderer":"iframe","presentation":"inline","environment":"production","sandbox":"allow-scripts allow-same-origin allow-forms"}]
# Authenticated inbound A2A also requires this exact HTTPS origin. It is never
# inferred from Host/X-Forwarded-Host for the public Agent Card/protocol endpoint.
# The CLI can set/clear the stable value safely with:
#   mso gateway domain set https://mso.example.com
#   mso gateway domain clear
# Temporary `mso gateway start` Quick Tunnels deliberately do NOT write this value.
# Optional CLI-only gateway controls (normally leave unset):
# MSO_GATEWAY_LOCAL_URL=http://127.0.0.1:4005
# MSO_GATEWAY_NO_AUTO_INSTALL=1  # require a pre-provisioned/reviewed cloudflared binary
# MSO_GATEWAY_PUBLIC_READY_SECONDS=60  # bounded HTTPS edge propagation wait (10..120)

# --- Embedded managed-app dashboards: optional split-origin decision ---
# Unset (default) = MSO does not EMBED vendor web UIs. Managed-app lifecycle and
# Details still work without a domain. 9Router remains loopback-only unless
# NINE_ROUTER_EXPOSE_PUBLIC=1 is explicitly set; public-IP access is never inferred.
#
# There is no fallback to serving them under a path on the cockpit's origin. That
# mode existed and was removed: those SPAs need allow-same-origin to run at all,
# so upstream JS reached `window.top` and called /api/v1/exec with your session —
# and `window.open('/')` did the same from a plain tab. No CSP can stop either (a
# policy binds a realm, not a reference across realms). Only a separate origin can.
#
# Set the template before building. Provision each exact app host with DNS/TLS.
# App dashboards exchange a 60-second ticket for an audience-bound, host-only
# HttpOnly cookie. Cockpit sessions remain host-only and are never sent to apps.
# Existing Domain sessions are invalidated; sign in again after upgrading.
# NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE={id}.mso.example.com
# Configure DNS/tunnel automation once with: mso domain setup --user <user> --connection <cloudflare-connection> --apply
# Then deploy the template and run: mso mapp enable 9router
# Private persistent routing settings + receipts live outside the code checkout.
# OS_MANAGED_DOMAINS_STORE=~/.mso/private/managed-domains.json
# Shell-app public domains (POST /api/v1/shell-apps/<id>/domain) persist their phase here.
# OS_SHELL_APP_DOMAINS_STORE=~/.mso/private/shell-app-domains.json
# Advanced local CLI transport; mso domain normally derives these from its selected env and port.
# MSO_DOMAIN_ENV=/absolute/path/to/.env.local
#
# Orca web bridge. The dashboard URL is the managed loopback endpoint; its port is
# the managed Orca port (default 6769) the bridge expects for the bound socket.
# ORCA_DASHBOARD_URL=http://127.0.0.1:6769
# Private state root defaults to ~/.local/share/mso/orca; this is MSO-owned state,
# never the owner's personal ~/.orca. Override only with a clean absolute path. An
# invalid value fails the bridge closed, it does not fall back.
# ORCA_HOME=/absolute/mso-owned/orca-state
# MSO_DOMAIN_LOCAL_ORIGIN=http://127.0.0.1:4005
# OS_SESSION_COOKIE_DOMAIN is obsolete; retained only to clear legacy cookies.
# OS_SESSION_COOKIE_DOMAIN=

# --- Camoufox viewer origin: separate auth, safe sibling by default ---
# The Browser viewer does not reuse the cockpit session cookie. An authenticated
# Operator/Owner receives a short-lived ticket, exchanged on the viewer origin for
# a host-only HttpOnly cookie before noVNC loads. With a namespace cookie such as
# mso.example.com, MSO derives camoufox.example.com automatically; with host-only
# login at mso.example.com it derives the same sibling. Provision DNS/TLS for the
# derived host, or override it with another HTTPS origin that is outside the current
# cockpit cookie Domain. Broad two-label cookie Domains intentionally require an
# explicit isolated origin because no safe sibling can be inferred.
# CAMOUFOX_VIEWER_ORIGIN=https://camoufox.example.com
# CAMOUFOX_NOVNC_URL=http://127.0.0.1:6080

# --- Storage paths (optional overrides) ---
# OS_DEVICE_STORE=~/.mso/auth-devices.json   # approved devices + live roles
# OS_ACCOUNT_STORE=~/.mso/account.json       # owner display name and icon (not the login password)
# OS_CONFIG_STORE=~/.mso/config.json         # BYOK key + model (owner config)
# OS_MULTIUSER_ROOT=~/.mso/users             # per-tenant <id>/config.json; a named tenant never falls back to owner env keys
# OS_PREFS_PATH=~/.mso/prefs.json            # synced UI prefs (theme, layout)
# OS_MEMORY_STORE=~/.mso/memory.json         # Alfa assistant long-term memory
# OS_THREADS_DIR=~/.mso/threads              # Alfa assistant chat threads (one file each)
# OS_AGENT_MEMORY_DIR=~/.mso/agent-memory    # isolated MSO Agent USER.md/MEMORY.md stores
# OS_AGENT_SESSIONS_DIR=~/.mso/agent-sessions # durable CLI/MCP agent session records
# OS_AGENT_PROFILES_DIR=~/.mso/agent-profiles # private Owner-device saved profiles and revisions
# MSO_AGENT_WORKTREE_ROOT=~/.cache/mso-worktrees # task-owned Git worktrees for source-changing agent workflows
# MSO_AGENT_THEME=dark                      # TUI palette: dark (default) | light | mono; NO_COLOR or a non-TTY forces mono
# MSO_AGENT_TIMEOUT_MS=120000               # upper bound for one local API request, so a dead server cannot freeze the TUI
# Session artifacts use this same root: temp/<client-hash>/<session-id> (owner-only).
# OS_AGENT_ARTIFACT_RETENTION_DAYS=7 # dormant artifacts only; clamped 1-30; active leases preserved
# OS_PROJECT_AGENT_TASKS_DIR=~/.mso/project-agent-tasks # private project-agent message/status records
# OS_SUBAGENT_MAX_TURNS=12 # server policy cap for one foreground subagent; default 12, absolute max sees OS_SUBAGENT_ABSOLUTE_MAX_TURNS
# OS_SUBAGENT_ABSOLUTE_MAX_TURNS=48 # hard ceiling OS_SUBAGENT_MAX_TURNS may reach; default 48
# OS_SUBAGENT_DEFAULT_TURNS=6 # turns a subagent gets when the caller passes none; default 6
# OS_SUBAGENT_MAX_TIMEOUT_MS=120000 # longest one foreground subagent may run; default 120000
# --- Agent turn budgets (each has a conservative default; raise deliberately) ---
# OS_AGENT_MAX_ROUNDS=1000 # interactive MSO Agent model rounds per turn (stream → tools → stream); default 1000
# OS_ASSISTANT_MAX_TURNS=8 # web Assistant tool rounds per request; default 8
# OS_AGENT_PROFILE_MAX_TURNS=6 # rounds one saved-profile read run may take; default 6
# OS_AGENT_PROFILE_MAX_TOOL_CALLS=16 # tool calls one saved-profile read run may make; default 16
# Native Local Agents use private defaults; overrides are normally unnecessary.
# OS_LOCAL_AGENT_PRESENCE_STORE=~/.mso/private/local-agent-presence.json # live receive leases/aliases (0600)
# OS_LOCAL_AGENT_MESSAGE_STORE=~/.mso/private/local-agent-messages.json # durable explicit local messages/tasks (0600)
# OS_LOCAL_AGENT_STANDBY_STORE=~/.mso/private/local-agent-standby.json # durable workflow-bound standby/claim state (0600)
# OS_ORGANIZATION_STORE=~/.mso/private/organization.json # owner-private org units/seats/reporting/agent bindings (0600)
# OS_AGENT_GROUP_STORE=~/.mso/private/agent-groups.json # owner-private multi-agent discussion groups and run transcripts (0600)
# Multi-agent groups run each member as a headless Hermes profile turn.
# HERMES_BIN=~/.local/bin/hermes # path to the hermes CLI used by Agent groups
# OS_LOCAL_AGENT_LEASE_MS=60000 # receiver lease; CLI heartbeat is lighter than this expiry
# OS_TOOL_FORGE_DIR=~/.mso/tool-forge      # private inert Tool Forge candidate/evaluation records
# OS_TOOL_FORGE_NODE_IMAGE=mso-forge-sandbox:node22-v1 # labelled cached Docker image used only for executable Forge fixtures
# OS_A2A_STORE=~/.mso/private/a2a-agents.json # public A2A Agent Card registry; no credentials
# OS_A2A_CREDENTIAL_STORE=~/.mso/private/a2a-credentials.json # outbound peer API-key/Bearer/OAuth access-token profiles (0600)
# OS_A2A_INBOUND_TOKEN_STORE=~/.mso/private/a2a-inbound-tokens.json # inbound bearer hashes only (0600)
# OS_A2A_TASK_STORE=~/.mso/private/a2a-tasks.json # bounded explicit inbound A2A task/message state (0600)
# Authenticated inbound A2A is enabled by default when OS_PUBLIC_ORIGIN is set.
# Set OS_A2A_INBOUND_ENABLED=0 as a kill switch. This publishes /.well-known/agent-card.json and /a2a/v1, but every protocol
# call still requires an owner-minted scoped bearer from `mso a2a inbound create`.
# OS_A2A_INBOUND_ENABLED=1
# Same-host A2A is disabled by default. Set OS_A2A_ALLOW_LOOPBACK=1 only for trusted same-host agents.
# It permits
# HTTP only for 127.0.0.1, ::1, and localhost; RFC1918/LAN/Docker/link-local and
# hostnames resolving to private addresses remain blocked. This flag affects A2A only.
# OS_A2A_ALLOW_LOOPBACK=1
# Optional override for the same-host A2A origin. Normally leave unset; MSO derives
# loopback from the installed service port and still validates exact-loopback policy.
# OS_A2A_LOOPBACK_ORIGIN=http://127.0.0.1:4005
# Owner-private local A2A auth state. Normally leave at its default private path.
# OS_A2A_LOCAL_AUTH_STORE=~/.mso/private/a2a-local-auth.json
# Runtime/service port aliases used by installer and local A2A origin discovery.
# MSO_PORT=4005
# PORT=4005
# Production Node listener bind address (installer flags override this).
# HOSTNAME=0.0.0.0
# Session context is estimated provider-neutrally and compacted when it reaches this
# threshold. Raw/older context is first written as a SANITIZED gzip backup; secrets
# are recursively redacted before archival. Defaults: 700k threshold, 140k recent.
# OS_AGENT_SESSION_COMPACT_TOKENS=700000
# OS_AGENT_SESSION_RECENT_TOKENS=140000
# Frozen memory projection: stable core + query-relevant JIT pack
OS_AGENT_MEMORY_CORE_CHARS=6000
OS_AGENT_MEMORY_JIT_CHARS=8000
# OS_AGENT_SESSION_ARCHIVE_DIR=~/.mso/agent-session-archive
# JEV preservation receipts are SHA-bound evidence that gates archive deletion.
# OS_AGENT_SESSION_PRESERVATION_DIR=~/.mso/agent-session-preservation
# Optional owner-private JEV decision telemetry store; metadata only, no credentials/raw transcripts.
# OS_JEV_TELEMETRY_STORE=~/.mso/private/jev-telemetry.json
# OS_AGENT_SESSION_ARCHIVE_DAYS=30
# Owner-private Dokploy/Cloudflare/Hostinger connection state. Defaults to the path
# below; normally leave it there so the 0700 directory + 0600 file policy applies.
# OS_INFRA_STORE=~/.mso/private/infra-providers.json
# Optional selectors for the owner-private OpenAI / ChatGPT App integration used by
# plugin:link-app. These are connection names only; the registered App ID itself stays
# inside the 0600 Integrations store and must not be committed or placed in env files.
# MSO_OPENAI_APP_USER=
# MSO_OPENAI_APP_CONNECTION=
# Optional owner-private destination for plugin:stage-private output.
# MSO_OPENAI_PLUGIN_STAGE=~/.mso/private/plugin-packages/mso
# CLI-only override for `mso skills install`; default ~/.mso/skills. The target is
# the explicit operator-trust root, so point this only at a private directory you own.
# MSO_SKILL_INSTALL_ROOT=~/.mso/skills

# --- Camoufox browser (the Browser app) ---
# The reserved split-origin camoufox host is mapped by proxy.ts to this noVNC/websockify
# endpoint only after a live Operator/Owner role check. The retired same-origin
# /camoufox-vnc/* path always 404s. This endpoint MUST stay loopback: a value pointing
# off-box would turn the viewer proxy into a relay, and proxy.ts rejects it.
# CAMOUFOX_NOVNC_URL=http://127.0.0.1:6080
#
# Optional dedicated HTTPS origin for the human noVNC viewer when the managed-app
# namespace hostname is not covered by the deployment's edge TLS certificate.
# Keep this on a separate sibling origin (for example camoufox-mso.example.com);
# the cockpit exchanges a short-lived ticket for a host-only viewer cookie, so the
# main MSO session cookie does not need to be widened to unrelated subdomains.
# CAMOUFOX_VIEWER_ORIGIN=https://camoufox-mso.example.com
#
# Plaintext copy of the VNC password, written beside x11vnc's own passwd blob (which is
# not meant to be read back) by scripts/camoufox-vnc-service. 0600, never committed.
# The API hands it to the viewer in the URL FRAGMENT, never the query string.
# CAMOUFOX_VNC_PASSWD_TEXT=~/.vnc/passwd.txt

# --- Agent benchmark defaults (optional, local tooling only) ---
# Used by `bun run bench:corpus` / cross-agent benchmark tooling when the matching
# CLI flags are omitted. These do not select the production MSO model and are not
# secrets. Prefer explicit `--provider` / `--model` in CI or published comparisons.
# MSO_BENCH_PROVIDER=openai-codex
# MSO_BENCH_MODEL=gpt-5.6-terra

# --- Constrained guest builds (optional) ---
# Limit Next build workers for small PRoot/Android guests; normal builds leave unset.
# MSO_BUILD_CPUS=1
# Enable the smaller-memory Next build configuration only on constrained guests.
# MSO_LOW_MEMORY_BUILD=1

# --- Build metadata (optional) ---
# Shown in Settings → About, and compared against the checkout's HEAD by the
# Software-update panel to tell "a build is pending" from "up to date". Set at BUILD
# time (NEXT_PUBLIC_ is inlined into the client bundle). You do NOT normally set it:
# next.config.mjs fills it from `git rev-parse --short HEAD` when it is unset. Set it
# only where the build has no .git (a tarball, a container build stage).
# NEXT_PUBLIC_COMMIT_SHA=
#
# The ONLY way to emit a ?dpl= query on static chunk URLs. Leave UNSET unless you are
# running skew protection: next.config.mjs used to fall back to Date.now() here, and
# because the config is evaluated twice (build, then `next start` boot) that produced
# two different values for the same chunk and every cold load downloaded ~160 KB gzip
# of entry chunks TWICE. Chunks are content-hashed, so unset is correct.
# NEXT_DEPLOYMENT_ID=

# --- Public demo build (optional, BUILD-TIME flag) ---
# Build with =1 for a safe public showcase: no login, no host access, no /api
# calls — forced mock data only. Use a separate checkout/service for the demo.
# NEXT_PUBLIC_OS_DEMO=1

# --- Forward-looking: Server Actions encryption (optional) ---
# NEXT_SERVER_ACTIONS_ENCRYPTION_KEY — UNUSED today (no Server Actions in repo).
# When the first Server Action lands, set this to a 32-byte hex random
# (openssl rand -hex 32) and keep it stable across deploys, else in-flight
# action payloads silently invalidate on rolling restart.
# NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=

# ── MCP server (control this VPS from ChatGPT / Claude.ai / Cursor) ──────────
# Fresh installs enable the OAuth-protected MCP surface by default. /mcp still
# requires explicit OAuth consent and a bearer; this does NOT make host tools public.
OS_MCP_ENABLED=1
# Highest tier the consent screen may grant. read | write | exec. Fresh-install
# default: exec, and consent preselects that highest allowed tier. Lower this to
# read/write before connecting a client that does not need shell access.
# SECURITY: an `exec` bearer is equivalent to remote command execution as the MSO
# service user. Protect, rotate and revoke bearer credentials accordingly.
OS_MCP_MAX_SCOPE=exec
# Where clients/codes/tokens live. Default ~/.mso/mcp.json (0600). Only sha256 of
# each code and token is ever written.
# OS_MCP_STORE=/home/you/.mso/mcp.json
# Optional comma-separated browser origins allowed to call the PUBLIC MCP origin
# with CORS. ChatGPT web origins are built in; server-to-server MCP clients omit
# Origin and need no entry. Exact origins only; this never weakens loopback/DNS-
# rebinding protection. Example: https://claude.example,https://cursor.example
# OS_MCP_BROWSER_ORIGINS=
# Optional exact Azure Blob hostnames for all MCP file imports. `*.oaiusercontent.com`
# is trusted directly. DCR client names and callbacks never grant host trust.
# Comma-separated; wildcards are rejected, including rotating ChatGPT Azure hosts.
# OS_MCP_OPENAI_FILE_HOSTS=oaisdmntprseasia.blob.core.windows.net
# Persistent semantic skill/recipe memory. The default is ~/.mso/skill-memory.json
# (0600). Embeddings are deterministic and local — no API key, model download or
# network call is required.
# OS_SKILL_MEMORY_STORE=/home/you/.mso/skill-memory.json
# Optional private owner-local cache for the bounded project path/skill candidate index.
# Defaults to ~/.mso/cache/candidate-index-v1.
# MSO_CANDIDATE_INDEX_DIR=/home/you/.mso/cache/candidate-index-v1
# Optional live MCP activity log shown in Assistant → MCP. Default
# ~/.mso/mcp-activity.log. This is separate from the forensic audit trail and
# records tool lifecycle (started/completed/failed), including bounded reads.
# OS_MCP_ACTIVITY_LOG=/home/you/.mso/mcp-activity.log
# Internal loopback origin used by the read-only `screen_capture` MCP tool. The
# implementation refuses non-loopback values. Default http://127.0.0.1:4005.
# OS_SCREENSHOT_ORIGIN=http://127.0.0.1:4005

# Optional exact machine-to-machine ingress for PROJECT integrations on a managed
# app host. Stock MSO leaves this unset and exposes no such lane. JSON array, max
# 8 entries; POST only; target MUST be loopback; auth currently hmac-v2-json.
# MSO only prefilters HMAC-shaped headers — the loopback app verifies the secret.
# OS_PROJECT_INGRESS_ROUTES=[{"app":"hermes","method":"POST","path":"/webhooks/project-example","target":"http://127.0.0.1:8644/webhooks/project-example","auth":"hmac-v2-json","maxBodyBytes":262144}]

# Optional SI-Coder launcher override. Its package/bin identity is verified before use.
# Leave unset to use the owner's ~/.local/bin/sc. No credentials belong here.
# MSO_SC_BIN=/absolute/path/to/sc

# --- Hosted passive security scan (GitHub Actions, not application configuration) ---
# Set MSO_DAST_URL as a repository Actions variable to the approved HTTPS instance.
# Actions does not read this .env.local file. The standalone target-check command
# also accepts the value from its environment. No credentials, query or fragment.
# MSO_DAST_URL=https://mso.example.com


# --- Batonly capability federation (optional) ---
# Start the Batonly pull worker only when this MSO installation has a project
# containing an MCP server alias named "baton". The project hint defaults to "baton".
# Override only when the local project is registered under another exact name/path/id.
# MSO_BATONLY_FEDERATION_PROJECT=baton
# Emergency/instance opt-out. Set 1 to keep the federation worker disabled even when
# the Baton project MCP is configured. Batonly never receives an MSO bearer credential.
# MSO_BATONLY_FEDERATION_DISABLED=0
# Optional XDG state base for the manual independent CI runner. Defaults to
# $HOME/.local/state; the runner appends mso-ci and enforces owner-private access.
# Set in the invoking shell; the CI CLI does not load .env files or credentials.
# XDG_STATE_HOME=/absolute/owner-private/state-base

# External A2A trace CLI identity, private state directory and executable override.
# These are read by the invoking CLI process, not from the web server configuration.
# MSO_A2A_AGENT=external
# MSO_A2A_TRACE_STATE_DIR=/absolute/owner-private/a2a-traces
# MSO_CLI=mso

# Native Windows terminal executable. Leave unset for the standard PowerShell command.
# POWERSHELL_EXE=powershell.exe

# Optional one-shot fallback heartbeat; disabled by default, no persistent daemon.
# Schedule once with: mso heartbeat install-cron (cron daemon is managed by your host).
OS_HEARTBEAT_ENABLED=0
# OS_HEARTBEAT_INTERVAL_MINUTES=30
# OS_HEARTBEAT_FAILURE_THRESHOLD=1
# Explicit recipe for an MSO-owned named gateway (external connectors are never adopted):
# OS_HEARTBEAT_GATEWAY_CONFIG=/path/to/dedicated-cloudflared.yml
# OS_HEARTBEAT_GATEWAY_TUNNEL=<name-or-uuid>