ai-workspace-lab/xworkspace-console
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
515f2a35e5
xworkspace-console/docs/operations/service-port-plan.md
Haitao Pan 4723d19b2c Rebuild console with React Vite and Go
2026-06-07 13:01:06 +08:00

3.4 KiB
Raw Blame History

XWorkspace Console Service Port Plan

Date: 2026-06-07

This plan is based on the live host inspection of ubuntu@xworkmate-bridge.svc.plus (jp-xhttp-contabo.svc.plus) and the local XWorkspace Console repository state.

Canonical Endpoint Map

Component Bind Port URL Owner Notes
XWorkspace Console 127.0.0.1 17000 http://127.0.0.1:17000 xworkspace-console.service Canonical dashboard endpoint. Avoids macOS ControlCenter conflicts on 7000.
XWorkspace Status API 127.0.0.1 8788 http://127.0.0.1:8788 xworkspace-api.service Go API for /health, /services, /metrics/simple.
XWorkmate Bridge 127.0.0.1 8787 http://127.0.0.1:8787 xworkspace-bridge.service / live xworkmate-bridge.service Keep reserved for bridge control plane. Do not reuse for dashboard.
OpenClaw Gateway 127.0.0.1 18789 http://127.0.0.1:18789/channels xworkspace-openclaw.service / live openclaw-gateway.service OpenClaw UI and gateway entry.
LiteLLM 127.0.0.1 4000 http://127.0.0.1:4000/ui xworkspace-litellm.service Live host returns HTTP 200 after redirect.
Vault 0.0.0.0 or 127.0.0.1 8200 http://127.0.0.1:8200 xworkspace-vault.service / system Vault Live host exposes Vault on 0.0.0.0:8200; tighten to loopback later if no remote clients need it.
Embedded Terminal 127.0.0.1 7681 http://127.0.0.1:7681 ttyd.service or xworkspace-ttyd.service Use only one owner. Live host already has system ttyd.service; user xworkspace-ttyd.service fails due port conflict.
Legacy Portal 0.0.0.0 7000 http://127.0.0.1:7000 xworkspace-portal.service Deprecated. Replace with Console on 17000.

Live Host Findings

  • xworkspace-portal.service is active on 0.0.0.0:7000 using python3 -m http.server 7000.
  • xworkspace-chrome.service currently opens --app=http://localhost:7000.
  • xworkspace-console.service exists but is inactive and still points to the old script model.
  • xworkmate-bridge.service is active on 127.0.0.1:8787.
  • openclaw-gateway.service is active on 127.0.0.1:18789.
  • xworkspace-litellm.service is active on 127.0.0.1:4000.
  • Vault is active on 0.0.0.0:8200.
  • System ttyd.service is active on 127.0.0.1:7681.
  • User xworkspace-ttyd.service is auto-restarting because 7681 is already occupied.

Migration Order

  1. Deploy the React Console to ~/xworkspace-console/dashboard.
  2. Replace xworkspace-console.service with a long-running service on 127.0.0.1:17000.
  3. Change Chrome app mode to http://127.0.0.1:17000 and depend on xworkspace-console.service.
  4. Disable xworkspace-portal.service after Console passes health checks.
  5. Keep xworkmate-bridge.service on 127.0.0.1:8787.
  6. Keep ttyd on 127.0.0.1:7681; do not start xworkspace-ttyd.service when system ttyd.service is already active.
  7. Keep LiteLLM, Vault, and OpenClaw on their existing live ports.

Collision Rules

  • Never assign Console to 7000; macOS may reserve it and the live host already uses it for the deprecated portal.
  • Never assign Console to 8787; that is the bridge control-plane port.
  • Treat 7681 as singleton terminal ownership; system ttyd.service wins if present.
  • Prefer loopback binds for all control-plane services unless a reverse proxy explicitly exposes them.