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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
docs: port band is 5553-5569 and the 6000-6099 allocator range is documented (#11851)
Adam Eivy0e835b037fdc
diff --git a/AGENTS.md b/AGENTS.mdindex 6581e279e6..a6c6469943 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -129,7 +129,7 @@ Because both are off by default, **never treat "the password is set" as an availThe server is always user-facing on `:5555` (HTTP or HTTPS). The client runs on the Vite dev server at `:5554` under `npm run dev`; under `npm start` the built client is served from `:5555`. PM2 manages app lifecycles. Where a record persists (Postgres vs a `data/` file) is decided by `docs/STORAGE.md`.-**Ports.** PortOS uses 5553–5561 (system PostgreSQL on 5432, Docker PostgreSQL on 5561). When HTTPS is on, local curl/scripts hit the loopback-only HTTP mirror on `:5553` to skip the cert warning. Define ports in the top-level `PORTS` object in `ecosystem.config.cjs` (re-exported at `server/lib/ports.js`). Guide and diagram: `docs/PORTS.md`.+**Ports.** PortOS owns the 5553–5569 band (core services and the extension band; see `docs/PORTS.md`). System PostgreSQL is on 5432, Docker PostgreSQL on 5561. When HTTPS is on, local curl/scripts hit the loopback-only HTTP mirror on `:5553` to skip the cert warning. Define ports in the top-level `PORTS` object in `ecosystem.config.cjs` (re-exported at `server/lib/ports.js`). Guide and diagram: `docs/PORTS.md`.**Never run `npm ci` or `npm install` from inside an ordinary CoS worktree (`data/cos/worktrees/*`).** Ordinary worktrees get the primary checkout's `node_modules` (root, `client/`, `server/`) by symlink; npm follows the symlink and empties the PRIMARY checkout's real `node_modules`, which takes every agent spawn down with `posix_spawn failed: No such file or directory` until someone reinstalls. If an ordinary worktree is missing dependencies, use the linked workspace binaries directly (`server/node_modules/.bin/vitest run <files>`) — never install. **The `dependency-updates` scheduled task is the exception:** its CoS-managed worktree receives no dependency symlinks, so package-manager installs and updates stay inside that worktree. Do not use the source checkout's dependency paths for that task. Recovery and mechanism: `docs/TROUBLESHOOTING.md` ("Every Agent Spawn Fails…"); the runner names this fault in `server/lib/ptySpawnDiagnostics.js`.diff --git a/README.md b/README.mdindex cd3d5acbd6..09cc22049e 100644--- a/README.md+++ b/README.md@@ -353,7 +353,7 @@ PortOS binds to `0.0.0.0` so you can access it from any device on your Tailscale- Check logs and restart services from your phone- View dashboard on your tablet while coding on your laptop-> **Security Note**: PortOS is designed for private Tailscale networks. Do not expose ports 5553-5561 to the public internet. An optional instance password (*Settings → Security*) gates `/api/*` and `/data/*` if you want a second layer, but it is **off by default** — the tailnet is the trust boundary. See the Security Model in [AGENTS.md](./AGENTS.md#security-model) and the [Setup Guide](./docs/SETUP.md) for network and authentication details.+> **Security Note**: PortOS is designed for private Tailscale networks. Do not expose the PortOS port band (5553-5569, see [docs/PORTS.md](./docs/PORTS.md)) to the public internet. An optional instance password (*Settings → Security*) gates `/api/*` and `/data/*` if you want a second layer, but it is **off by default** — the tailnet is the trust boundary. See the Security Model in [AGENTS.md](./AGENTS.md#security-model) and the [Setup Guide](./docs/SETUP.md) for network and authentication details.## Tech Stack@@ -424,7 +424,7 @@ Full catalog (including design plans, ADRs, and research notes): [docs/README.md- [Federated Media Providers](./docs/FEDERATED_MEDIA_PROVIDERS.md) — Authenticated, capacity-aware peer audio provider wire contract and setup- [Storage Classification Contract](./docs/STORAGE.md) — when data belongs in PostgreSQL vs the filesystem, plus the new-data-store checklist- [Backup & Restore](./docs/BACKUP.md) — filesystem snapshots + mandatory PostgreSQL dumps and how to restore them-- [Port Allocation](./docs/PORTS.md) — Port conventions (5553-5561) and allocation guide+- [Port Allocation](./docs/PORTS.md) — Port conventions (5553-5569) and allocation guide- [PM2 Configuration](./docs/PM2.md) — PM2 patterns and best practices- [Quota Burn Automation](./docs/QUOTA-BURN.md) — Subscription quota spending loop and window rules- [Three.js Models](./docs/THREEJS_MODELS.md) — Procedural Three.js scene generation and trust boundarydiff --git a/docs/PORTS.md b/docs/PORTS.mdindex c622f09fea..aca8c879fb 100644--- a/docs/PORTS.md+++ b/docs/PORTS.md@@ -145,6 +145,7 @@ PortOS automatically detects ports from env vars:| 5553-5561 | PortOS core services (includes the `:5553` loopback mirror and the `portos-db` Docker container on `:5561`) || 5562-5569 | Reserved for PortOS extensions. Assigned: 5562 whisper, 5563 Eidoverse bridge (on demand), 5564 slotstream (on demand), 5565 Tailcat ingress (on demand), 5566 jev scorer (on demand), 5568 llama-server. Unassigned but still reserved: 5567, 5569 || 5570-5599 | User applications — **put managed apps here** |+| 6000-6099 | Outside the PortOS band. Used by `GET /api/ports/scan` and `POST /api/ports/allocate` (`server/services/ports.js`), and by the PM2 Standardizer when it reassigns a colliding port (`server/services/pm2Standardizer.js`). Scaffolded apps still get 5570-5599 |> **A collision inside `5553-5569` is silent, not loud.** The natural assumption is> that a second listener on a taken port fails with `EADDRINUSE`, so an accidentaldiff --git a/docs/README.md b/docs/README.mdindex 6e83fecf45..a45d80c31d 100644--- a/docs/README.md+++ b/docs/README.md@@ -22,7 +22,7 @@ Index of everything under `docs/`. Start with the [root README](../README.md) fo| [STORAGE.md](./STORAGE.md) | Storage classification contract — PostgreSQL vs filesystem, new-data-store checklist || [BACKUP.md](./BACKUP.md) | Filesystem snapshots + PostgreSQL dumps, restore semantics || [BACKUP_PUBLICATION_ADMISSION.md](./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](./PORTS.md) | Port allocation (5553–5561) and how 5555/5553/5554 relate |+| [PORTS.md](./PORTS.md) | Port allocation (5553–5569) and how 5555/5553/5554 relate || [ITERM.md](./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](./INSTANCE_FEATURES.md) | Optional per-install features — registry, client-side nav gating, feature groups, reconcile-at-toggle || [PM2.md](./PM2.md) | Recommended PM2 ecosystem patterns for sub-projects |diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex 9d4566d56e..2253f89a0d 100644--- a/docs/TROUBLESHOOTING.md+++ b/docs/TROUBLESHOOTING.md@@ -43,7 +43,7 @@ is probed independently and separately bounded, so one unreachable servicedegrades to a single line instead of hanging the report. It exits non-zero whena **required** prerequisite is unavailable; optional facts (TLS cert, `gh`,ffmpeg/python3/uv, the port block) are reported but never fail the run — a-running install legitimately occupies ports 5553–5561.+running install legitimately occupies ports in the PortOS band, 5553–5569.Details name no hostnames, usernames, IPs, or home-directory paths, so theoutput is safe to paste into a bug report as-is.diff --git a/scripts/ci-test-plan.js b/scripts/ci-test-plan.jsindex 8c74a58fe7..85441041fc 100644--- a/scripts/ci-test-plan.js+++ b/scripts/ci-test-plan.js@@ -293,6 +293,9 @@ export const ALWAYS_RUN_TESTS = ['scripts/ensure-deps.test.js','scripts/migrations/promptBumpMigrations.guard.test.js','scripts/node-version-drift.test.js',+ // Whole-tree markdown scanner: a docs-only PR can reintroduce the stale band+ // in prose with no import edge back to this test (#11851).+ 'scripts/port-band-docs.test.js','scripts/repo-scan-guards.test.js',// Whole-tree scanner: any server file can add an import of client source.'scripts/server-imports-no-client.test.js',diff --git a/scripts/port-band-docs.test.js b/scripts/port-band-docs.test.jsnew file mode 100644index 0000000000..b4651b2543--- /dev/null+++ b/scripts/port-band-docs.test.js@@ -0,0 +1,60 @@+/**+ * Port-band prose guard (#11851).+ *+ * PortOS owns the 5553–5569 band, documented once in `docs/PORTS.md`. Prose that+ * still says the band ends at 5561 hides the extension sidecars (whisper, the+ * Eidoverse bridge, llama-server) from operators and agents, and the README+ * security note then leaves the wildcard-bound :5563 bridge out of scope.+ *+ * The only tracked line allowed to spell out the old range is the core-services+ * row in `docs/PORTS.md`. Enumeration is a `git grep` over tracked markdown, so+ * the file that reintroduces the range is never imported by this test. That is+ * why it is registered in `ALWAYS_RUN_TESTS` rather than left to impact selection.+ */+import { describe, it, expect } from 'vitest';+import { execFileSync } from 'child_process';+import { dirname, join } from 'path';+import { fileURLToPath } from 'url';++const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');++const STALE_BAND = '5553[-–]5561';+// Historical records and the plan archive legitimately quote the old range.+const EXCLUDED_PATHSPECS = [':!.changelog', ':!docs/plans', ':!docs/research'];+const ALLOWED = [{ file: 'docs/PORTS.md', line: '| 5553-5561 | PortOS core services' }];++/** `git grep` exits 1 on zero matches; that is an empty result, not a failure. */+function gitGrep(pattern, pathspecs) {+ try {+ return execFileSync('git', ['grep', '-nE', pattern, '--', ...pathspecs], {+ cwd: REPO_ROOT,+ encoding: 'utf8',+ maxBuffer: 64 * 1024 * 1024,+ });+ } catch (err) {+ if (err.status === 1) return '';+ throw err;+ }+}++describe('PortOS port band in tracked markdown (#11851)', () => {+ it('no tracked markdown states the stale 5553-5561 band outside the PORTS.md core-services row', () => {+ const hits = gitGrep(STALE_BAND, ['*.md', ...EXCLUDED_PATHSPECS])+ .split('\n')+ .filter(Boolean)+ .map((line) => {+ const firstColon = line.indexOf(':');+ const secondColon = line.indexOf(':', firstColon + 1);+ return { file: line.slice(0, firstColon), text: line.slice(secondColon + 1) };+ })+ .filter(({ file, text }) => !ALLOWED.some((a) => a.file === file && text.includes(a.line)));++ expect(hits.map(({ file, text }) => `${file}: ${text.trim()}`)).toEqual([]);+ });++ it('the scan actually reads the tracked PORTS.md core row (detector self-check)', () => {+ // If the pathspec ever widened to nothing, the assertion above would pass vacuously.+ const scanned = gitGrep(STALE_BAND, ['docs/PORTS.md']);+ expect(scanned).toContain('| 5553-5561 | PortOS core services');+ });+});diff --git a/server/services/pm2Standardizer.js b/server/services/pm2Standardizer.jsindex c53edcadb2..0e79697449 100644--- a/server/services/pm2Standardizer.js+++ b/server/services/pm2Standardizer.js@@ -27,9 +27,8 @@ export const PORTOS_ECOSYSTEM_MARKER = 'Generated by PortOS PM2 Standardizer';// Common Vite dev defaults — always avoided, since a developer machine almost// always already has something on 5173 (and 5174 is Vite's auto-fallback).const VITE_DEFAULT_PORTS = [5173, 5174];-// New ports are reassigned from here up (PortOS's managed-app convention, see-// DEFAULT_PORT_RANGE_START in services/ports.js) — clear of PortOS's own-// 5553–5561 block and the Vite defaults.+// Collision reassignments start here, the same 6000–6099 range services/ports.js+// allocates from. Both sit outside the PortOS 5553–5569 band and the Vite defaults.const REASSIGN_FROM = 6000;/**