# @x12i/ports-manager

> x12i org local port map — zones per mono-repo, avoid lists, default port resolution.

Latest version **1.0.9** (published 2026-09-23) · exellix-license license · 0 weekly downloads

## Install

```sh
npm install @x12i/ports-manager
pnpm add @x12i/ports-manager
yarn add @x12i/ports-manager
bun add @x12i/ports-manager
```

Provides the command `x12i-ports`.

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.9 |
| Published | 2026-09-23 |
| First published | 2026-07-23 |
| Weekly downloads | 0 |
| License | exellix-license |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 0 |
| Unpacked size | 81.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |
| Keywords | x12i, ports, zones, local-dev |

## Links

- npm: https://www.npmjs.com/package/@x12i/ports-manager
- Repository: https://github.com/x12i/memorix-mono-repo
- Homepage: https://github.com/x12i/memorix-mono-repo#readme
- Issues: https://github.com/x12i/memorix-mono-repo/issues
- npm.io page: https://npm.io/package/@x12i/ports-manager

## Recent versions

- 1.0.9 (latest) — 2026-09-23
- 1.0.6 — 2026-08-16
- 1.0.5 — 2026-08-05
- 1.0.4 — 2026-08-05
- 1.0.3 — 2026-07-25
- 1.0.2 — 2026-07-23
- 1.0.1 — 2026-07-23
- 1.0.0 — 2026-07-23

## README

# `@x12i/ports-manager`

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

**Source of truth:** [`port-map.json`](./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

```bash
npm install @x12i/ports-manager
```

Also published as JSON:

```bash
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`](../scripts/memorix-ports.mjs). Nexum zone wrapper: [`scripts/nexum-ports.mjs`](../scripts/nexum-ports.mjs). Neo zone wrapper: [`scripts/neo-ports.mjs`](../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.

```bash
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.

```bash
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.

```bash
npx x12i-ports zone neo-proagentics
npx x12i-ports zone neo
```

Local wrapper: [`scripts/neo-ports.mjs`](../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**)

```ts
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

```ts
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

```bash
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`](./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/`](../archived/x12i-port-map/).

## License

`exellix-license`

---
_Source: https://npm.io/package/@x12i/ports-manager · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._