Skip to content

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

docs: port band is 5553-5569 and the 6000-6099 allocator range is documented (#11851)

Adam Eivy0e835b037fdc
diff --git a/AGENTS.md b/AGENTS.md
index 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 avail
The 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.md
index 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 boundary
diff --git a/docs/PORTS.md b/docs/PORTS.md
index 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 accidental
diff --git a/docs/README.md b/docs/README.md
index 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.md
index 9d4566d56e..2253f89a0d 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -43,7 +43,7 @@ is probed independently and separately bounded, so one unreachable service
degrades to a single line instead of hanging the report. It exits non-zero when
a **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 the
output is safe to paste into a bug report as-is.
diff --git a/scripts/ci-test-plan.js b/scripts/ci-test-plan.js
index 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.js
new file mode 100644
index 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.js
index 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;
/**