@x12i/ports-manager

@x12i/ports-manager

Admin-managed local port map for x12i and exellix repos.

Source of truth: port-map.json — edited by org admins only.

Use this package only when a process binds a local TCP port. Import the zone for your repo, take defaults (or env overrides), and never bind ports on the avoid list.

Install

npm install @x12i/ports-manager

Also published as JSON:

node -e "console.log(require.resolve('@x12i/ports-manager/port-map.json'))"

Rules

Rule	Detail
One zone per product repo	Contiguous 20 ports (min–max) from 5100 upward
Tools pool	Shared zone tools = 10101–10999 for platform kits / ephemeral binds
Neo proagentics	Zone neo-proagentics = 10000–10100 (services, UI, connectors)
Even / odd	Even = API, odd = UI
Defaults	Every zone has api + ui; some zones add named defaults (e.g. Memorix, api-simulator)
Avoid	Never bind ports listed in avoid (AirPlay 5000/7000, Postgres 5432, Sonar 9000, …)
Quarantine	Never place or bind in 5000–5099

Memorix (this mono-repo)

Zone id: memorix → 5100–5119

Default	Port	Env
service / api	5100	MEMORIX_SERVICE_PORT
studio / ui	5101	MEMORIX_STUDIO_PORT or VITE_DEV_PORT
opxSource	5102	OPX_SOURCE_PORT
statusHub	5103	STACK_STATUS_PORT
knowxSource	5104	KNOWX_SOURCE_PORT
jobsApp	5105	JOBS_APP_PORT
knowxWorker	5106	(worker)
knowxControlPlane	5110	KNOWX_PORT
knowxApp	5111	KNOWX_APP_PORT
apiPlayground	5113	WORK_APIS_PLAYGROUND_PORT / API_PLAYGROUND_PORT (Work APIs Playground UI)

Local wrapper: scripts/memorix-ports.mjs. Nexum zone wrapper: scripts/nexum-ports.mjs. Neo zone wrapper: scripts/neo-ports.mjs.

api-simulator

Zone id: api-simulator → 5520–5539

Default	Port
api / libraryDemo	5520
ui / studio	5521
flowstate	5522
playground	5523

Ephemeral / multi-API binds from package simulators should use the tools pool below, not invent ports outside these zones.

memorix-generic-connectors

Zone id: memorix-generic-connectors → 7480–7499 (repo x12i/memorix-generic-connectors, not the memorix mono-repo zone)

Default	Port
api / sourceService	7480
ui / sourceStudio	7481
sourceSimulator	7482
targetService	7484
targetStudio	7485
targetSimulator	7486

nexum

Zone id: nexum → 7500–7519 (repo x12i/nexum, not the memorix mono-repo zone). Alias: memorix-nexum.

Default	Port	Env
service / worker	7500	MEMORIX_NEXUM_WORKER_PORT
ui	7501
api / read	7502	MEMORIX_NEXUM_READ_PORT
compiler	7504	NEXUM_SERVICE_PORT

compiler is even (API). Remaining 7505–7519 are free inside the zone.

npx x12i-ports zone nexum

vulnerabilities-skills (cyber-skills)

Zone id: vulnerabilities-skills → 7520–7539 (repo neociso-skills/vulnerabilities-skills). Aliases: cyber-skills, vulnerability-skills.

There is no GitHub skill x12i/port-manager and no npm package @x12i/port-manager. Agents: install @x12i/ports-manager and read SKILL.md in the package.

Default	Port	Role	Do not keep
api / topology	7520	API (even)	9101
ui / statusUi	7521	UI (odd)	9100
vulnRisk	7522	API (even)	9102

Remaining 7523–7539 are free inside the zone.

npx x12i-ports zone vulnerabilities-skills
npx x12i-ports zone cyber-skills

neo-proagentics

Zone id: neo-proagentics → 10000–10100. Aliases: neo, neo-connectors, proagentics.

Default	Port	Role	Legacy (leave)
api	10000	API (even)	—
ui / statusUi	10001	UI (odd)	9001
firewall	10002	API (even)	9201
xdr	10004	API (even)	9501
nessus	10006	API (even)	9601
entra	10008	API (even)	9701
splunk	10010	API (even)	9801
crowdstrike	10012	API (even)	9901

Remaining 10013–10100 are free inside the zone for extra Neo / proagentics processes.

npx x12i-ports zone neo-proagentics
npx x12i-ports zone neo

Local wrapper: scripts/neo-ports.mjs.

Tools packages (shared pool after Neo)

Zone id: tools → 10101–10999

Use this for platform kits that bind only for demos, samples, or ephemeral processes:

• ports-manager
• core-service
• api-live-view
• x12i-docify (demos; product docs serve also has zone docify 7460–7479)

createZonePorts({ zoneId: "tools" });
// defaults.api = 10102, defaults.ui = 10103 — pick unused even/odd ports inside the pool

Do not use 9000–9999 as a tools band — 9000 is on the avoid list (Sonar / common PHP). Do not bind 10000–10100 from tools — that strip is neo-proagentics.

API

import {
  createZonePorts,
  loadPortMap,
  isApiPort,
  isUiPort,
} from "@x12i/ports-manager";

const p = createZonePorts({
  zoneId: "memorix", // or "narrix", "servix", "exellix-engine", …
  env: {
    service: "MEMORIX_SERVICE_PORT",
    studio: ["MEMORIX_STUDIO_PORT", "VITE_DEV_PORT"],
    opxSource: "OPX_SOURCE_PORT",
    statusHub: "STACK_STATUS_PORT",
    api: "MEMORIX_SERVICE_PORT",
    ui: "MEMORIX_STUDIO_PORT",
  },
});

p.ports.service; // 5100 unless env set
p.range; // { min: 5100, max: 5119, size: 20 }
p.assertInZone(5100); // throws if avoided / quarantined / outside zone
p.assertRole(5101, "ui"); // odd required
p.origin("127.0.0.1", p.ports.service); // http://127.0.0.1:5100/

Export	Role
loadPortMap()	Parse admin JSON
createZonePorts({ zoneId, env?, map? })	Resolve defaults + helpers for one zone
isApiPort / isUiPort	Even / odd checks

CLI

npx x12i-ports list              # all zones
npx x12i-ports zone memorix      # range + defaults
npx x12i-ports avoid             # never-bind list
npx x12i-ports check memorix 5100

Admins

Edit port-map.json only:

1. Add the product repo under zones with github, min, max, and defaults (api / ui minimum).
2. Keep 20-port product zones contiguous from 5100 upward (next free after vulnerabilities-skills is 7540).
3. Platform tools / ephemeral binds → zone tools (10101–10999); Neo proagentics → neo-proagentics (10000–10100); do not carve new 20-port strips for kit packages.
4. Extend avoid when a well-known OS/service port must never be bound.

Do not invent a second map. Historical pointer stub: archived/x12i-port-map/.

License

exellix-license