Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
PortOS Documentation
Index of everything under docs/. Start with the root README for the product overview and quick start, and ETHOS.md for the project's position on autonomy, digital-mind individuality, privacy boundaries, and why consent here is architecture rather than a service.
Something won't start? Run npm run doctor — a read-only report of every install prerequisite (Node/npm floors, submodule, workspace deps, PostgreSQL + pgvector, migrations, seeded data/, pm2, media toolchain, cert, ports). It runs before npm install and prints one pasteable block; add --json for machine-readable output. Then see TROUBLESHOOTING.md.
Guides (living documents)
| Doc | Covers |
|---|---|
| MOSS_IMAGE.md | Optional pinned MOSS Swift/MLX image runtime, explicit installation, resource needs and Apple Silicon validation |
| HTML_COMPOSITIONS.md | Seekable HTML scenes rendered offline to MP4 through hidden managed-browser targets |
| CONTAINMENT.md | Every containment profile (bubblewrap, Seatbelt, Docker) and which consumer uses which; the opt-in Docker containment profile for untrusted installs/tests, its engine policy, two-phase network and contained-run.js |
| SUPERCOLLIDER.md | Managed SuperCollider Docker runtime: setup:supercollider, readiness states, containment policy and platform evidence |
| CODE_ANIMATION_PACKAGES.md | Versioned portable Code Animation source/brief packages, non-executing validation, and contained production execution |
| ARCHITECTURE.md | System design: React client, Express server, PM2 satellites, PostgreSQL + data/ files |
| features/catalog-ingest.md | Catalog extraction graph, context budgets, coverage, and review draft contract |
| CATALOG_LOCAL_MERGE.md | Local catalog consolidation, preserved identities and assets, conflict review, and guarded recovery |
| CATALOG_SHARED_IDENTITY.md | Two-owner canonical identity agreements, preparation, adoption, owner refresh, and coordinated recovery |
| API.md | REST endpoints, complete route-domain index, Socket.IO events |
| API_TOOL_CONTRACT.md | Unified semantic tool, Persistent Mind, and Agent Tools MCP contract |
| COMPANION_APP_API.md | PortDeck native iOS companion client discovery and HTTP API contract |
| SETUP.md | First install: Tailscale, MagicDNS, trusted HTTPS, exact launch URL, and AI-provider readiness |
| REMOTE_DESKTOP.md | PortDeck VNC broker security, host setup, and session flow |
| FEDERATED_MEDIA_PROVIDERS.md | Authenticated, capacity-aware peer audio provider wire contract and setup |
| STORAGE.md | Storage classification contract — PostgreSQL vs filesystem, new-data-store checklist |
| BACKUP.md | Filesystem snapshots + PostgreSQL dumps, restore semantics |
| BACKUP_PUBLICATION_ADMISSION.md | Shared admission lease between the server and portos-cos, and how snapshot and restore cuts drain in-flight asset publications |
| PORTS.md | Port allocation (5553–5569) and how 5555/5553/5554 relate |
| ITERM.md | The Shell page's iTerm2 view — requirements, status states and their fixes, why iTerm2 sessions stay separate from PortOS shells, the clean-room protocol rule |
| INSTANCE_FEATURES.md | Optional per-install features — registry, client-side nav gating, feature groups, reconcile-at-toggle |
| PM2.md | Recommended PM2 ecosystem patterns for sub-projects |
| DEEP-AUDITS.md | Persistent audit coverage, independent passes, checkpoint/resume and completion rules |
| DEEP-AUDITS-LEGACY.md | Legacy (historical) exhaustive Deep audit records and their stored evidence format; new launches no longer run this workflow |
| QUOTA-BURN.md | Quota-burn automation — spending subscription-backed CLI quota before expiry |
| AI_PROVIDERS.md | The AI Providers page: a run composed from Harness × Method × Service × Model × Effort, its Presets / Harnesses / Services views, compatibility matrix, derived vs legacy presets, and what federates (nothing) |
| PROVIDER_COMPOSITION.md | Composite provider ids (harness.method@service[+bootstrap]): the grammar, per-harness enablement, bootstrap apps, how every run path resolves one, and the preset-only surfaces |
| MODEL_ACCESS.md | Scoping a provider to the models your plan entitles you to — free tiers, allow/deny globs, gateway inheritance |
| MODEL_TIERS.md | Light / Medium / Heavy / Ultra tiers as per-preset routing configuration, and how a task or stage names a tier |
| JEV_SETUP.md | Optional local jev entailment scorer: installing, the pinned model and runtime, and recovery |
| PROMPT_GUARD_SETUP.md | Abuse Guard (Prompt Guard) runtime: status and install commands, repair behavior, and diagnosing a failed install |
| PERSISTENT_MIND_MAINTAINER.md | Opt-in, machine-local development maintainer role for the persistent mind: setup, grants, and activation |
| IMAGE_GALLERY.md | Image gallery reads: legacy full-array response, paged and filtered envelope, and media_assets search semantics |
| MODEL-COMPARISON.md | Sourced provider/model/effort comparisons, cost estimates and CoS research refresh |
| THREEJS_MODELS.md | Three.js procedural 3D model generation and trust boundary |
| features/music-video-autonomous.md | One-prompt autonomous music videos: brief → lyrics → mood board → Suno song → production, optional checkpoints, and the music-video-autopilot scheduled task that turns Brain ideas into videos |
| features/music-video-frame-capture.md | Shared paused-video/capture color interpretation, synthetic evidence and browser limits |
| features/music-video-temporal-evidence.md | Performance source provenance, synchronized playback and optional local temporal analyzer protocol |
| features/music-renderer-benchmarks.md | Technical and full-length listening evidence for local music renderer profiles |
| CONTRIBUTING.md | Dev setup (PostgreSQL required), code conventions |
| LOCAL_REVIEW_LIFECYCLE.md | Durable one-time pre-PR review, recovery and hosted-feedback continuation |
| PR_REVIEW_ATTRIBUTION.md | Completed local reviewer model receipts and additive PR labels |
| CLI_REVIEW_OUTCOMES.md | Reviewer tiers, provider pins and bounded, authenticated CLI health reports |
| SECURITY_SCANNER_RUNTIME.md | Runner-owned Codex security scans, pinned execution, process cleanup and observed evidence |
| UX_DESIGN_GUIDE.md | Admin workspace design specification: icon navigation, responsive layouts, disclosure, visual hierarchy, and redesign acceptance |
| UX_DESIGN_AUDIT.md | Representative UX audit and Jev/Performance pilot content maps |
| PAGE_LAYOUT_AUDIT.md | Routed header/navigation layout inventory, fixes, intentional exceptions, and browser regression coverage |
| GITHUB_ACTIONS.md | CI and release workflows |
| VERSIONING.md | SemVer + release process (/do:release) |
| SELF_UPDATE.md | Fork-aware self-update flow — release polling, FORK_SYNC_REQUIRED, fork sync, running a customized fork, and the unattended idle-gated automatic update |
| MANAGED_APP_UPDATES.md | Safe managed-app update default and the opt-in app lifecycle contract |
| MANAGED_APP_FORGE_ACCOUNTS.md | Running managed apps under a second GitHub account — ssh Host aliases and the per-app forgeAccount pin |
| DEPS.md | Dependency audit — every third-party package and its verdict |
| TROUBLESHOOTING.md | Common runtime issues, known issues |
| WINDOWS_CONSOLE.md | Why console windows flash and steal focus on Windows, and the two fixes |
| GOALS_OPERATIONAL.md | Runtime operating principles the CoS agent reads (parsed by goalProgress.js) |
| METRICS.md | The METRICS.md convention — how a managed app exposes its own success metrics so agents (incl. Layered Intelligence) can evaluate it against its goals |
Feature deep dives (features/)
- Music Video private sharing copy — source-bound 720p downloads strictly under 100 MB, private local export and media queue lifecycle
- Music Video making-of export — local multi-variant planning packages, inventory previews, source planning retention and publication boundaries
Start with the product surface map for a complete, user-facing inventory of the application. The focused guides below explain the features with their own operating contracts.
App management: app-wizard · app-quality · autofixer · browser · error-handling · jira-sprint-manager
Chief of Staff: chief-of-staff · branch-reconciliation · cos-agent-runner · cos-enhancement · self-improvement-audits · agent-context · agent-skills · memory-system · claude-ollama · grok-box-local-mind · fleet-llm-host · mtplx · slotstream · dflash2 (DSpark vs DFlash 2, Ternary Bonsai 2 27B) · qwen38-rtx3090 (3090 bring-up) · sglang-qwen38 (SGLang Hopper/Blackwell evaluation) · prompt-manager · development-watchdog · review-queue · scheduled-audit-organization
Federation: peer-administration · tailcat-peers · Models: decision-classifiers
- Persistent Mind continuous play + local context — explore/invent playbook and mind-adjustable
numCtxclamps
Identity & self: digital-twin · identity-system · soul-system · privacy-center · post (insights design spike: plans/2026-06-03)
Knowledge: brain-system · untrusted messages and GitHub automation · scope adherence
Create: writers-room · creative-director-video · apple-video-options · qwen-image-21 · fableloom · FableLoom runtime v1 · FableLoom export v1 · Eidoverse Worlds integration · Eidoverse music-video renderer · OpenWorld historical reference · sprite-export-contract · video-text-encoders · video-speed-profiles · video-render-batches · video-upscale
Comms & voice: beeper · messages-browser-send · openclaw-operator-chat (pre-build audit) · stacker-news · voice (Jev feasibility)
Point-in-time records
Music Video render-grade validation — synthetic encoder parity, visual references, and remaining generated-shot acceptance.
Explicit Music Video render pools — proposed initial shot placement and supplied-audio conditioning; final composition export remains local.
CoS agent permission posture — why unattended agents keep full-bypass instead of vendor auto-approve modes, and where stricter modes apply.
Native trash feasibility study — can PortOS recycle media without the
trashpackage: per-platform comparison, executed macOS/Linux proofs, the Windows acceptance checks, and the regression matrix.Recycle media through OS facilities PortOS owns — replace
[email protected]withosascript/JXA, PowerShell +SHFileOperationW, and an owned XDG adapter; implementation plan and Windows validation gate.Docker containment for untrusted install and test runs — local-only engine policy, per-run egress proxy for installs,
--network nonevalidation, and no host fallback.plans/ — dated design plans (
YYYY-MM-DD-<slug>.md), archived on approval before implementation. Historical records, not living docs. See provider connections and harnesses for stable executable routes, migration and management flows.decisions/ — ADRs (
YYYY-MM-DD-<slug>.md), e.g. the Postgres-as-primary-datastore decision and what may cross the federation layer (user-controlled federation, Privacy Center storage, federated visual prompts, conditioning crosses to an allowlisted peer, AI usage metrics federate on by default, Eidoverse guest chat, numeric PortOS quality federation, federated Eidoverse foundations), why H3 ships the draft-decode gates without an asset, and why closed-set decisions run on a local entailment model that abstains.research/ — investigation tools and incident write-ups (e.g. the H3 scene-continuity comparison, H3 vision precision investigation, mflux GPU-watchdog panic and local LLM performance audit).
superpowers/ — plan/spec pairs from superpowers-driven builds:
specs/<date>-<slug>-design.md(design) +plans/<date>-<slug>.md(implementation plan).
Other
themes/ — UI theme specs and the theme integration contract.
examples/ — copy-ready config examples (e.g. Claude Code → Ollama settings).
.changelog/README.md— how/do:releasesynthesizes release notes from the commit log, and the versioned-file format.media/ — screenshots and logo used by the root README.
Local managed-app visitor broker — opt-in credential provisioning, versioned nonhumanoid scope and host negotiation.
Agent API key — opt-in local credential and
scripts/portos-api.jsCLI for agents PortOS did not spawn.Tool-free model delegation — approved API workers, context packets, and advisory fidelity evaluation for Persistent Mind.
Runway model catalog — supported operations, public schema source, caching, refresh and workflow limits.
Data Maintenance — retained retired-feature storage, LoRA training retirement and explicit removal.