pikasTech-unidesk/docs/reference/nc01.md

NC01 Reference

NC01 is the current host registered as a UniDesk provider-gateway node. Host maintenance uses trans NC01 ...; Kubernetes maintenance uses trans NC01:k3s ....

Source Of Truth

• Host k8s/provider config: config/unidesk-host-k8s.yaml.
• Host proxy config: config/platform-infra/host-proxy.yaml#targets.NC01; NC01 host-proxy uses /root/vpn-server as the VPN server source.
• HWLAB node/lane config: config/hwlab-node-lanes.yaml#lanes.v03.targets.NC01.
• HWLAB control-plane config: config/hwlab-node-control-plane.yaml#nodes.NC01.
• AgentRun config: config/agentrun.yaml, lane nc01-v02.
• NC01 host PostgreSQL config: config/platform-db/postgres-nc01.yaml.

UniDesk Server Runtime

NC01 runs the UniDesk server/backend-core on Kubernetes in namespace unidesk, with config/unidesk-host-k8s.yaml as the configuration authority. Recovery, validation and trans operations must target NC01:k3s and those Kubernetes objects. A Docker Compose project or a container named unidesk-backend-core is not the NC01 server runtime and must not be used as recovery evidence. Once the Kubernetes runtime is healthy, do not rebuild, restart or replace it unless the user or owning runbook explicitly requires that action.

Fixed Repos

• HWLAB v0.3 fixed repo: /root/hwlab-v03; branch and remote come from config/hwlab-node-lanes.yaml.
• AgentRun v0.2 fixed repo: /root/agentrun-v02; branch and remote come from config/agentrun.yaml.
• UniDesk source/config authority remains /root/unidesk.

Database Boundary

NC01 database placement is selected by each owning YAML, not by a host-wide assumption. config/unidesk-host-k8s.yaml, config/agentrun.yaml and config/hwlab-node-lanes.yaml independently declare whether their workloads consume host-native/external PostgreSQL or a lane-local Kubernetes PostgreSQL. Validation must report the selected mode and corresponding Service/SecretRef; it must not require objects belonging to an unselected mode.

For HWLAB v0.3, runtimeStore.postgres.mode in config/hwlab-node-lanes.yaml owns this choice. A platform-service mode uses the YAML-declared external PostgreSQL bridge such as nc01-host-postgres; a local-k3s mode uses its lane-local PostgreSQL objects and must report the external bridge as not required. Runtime database Secrets come only from the selected mode's YAML sourceRef, with local source material under /root/.unidesk/.state/secrets/hwlab/*, and may be reported as presence/fingerprint metadata, never as full values.

Decision Center

Decision Center production runs on NC01 k8s in namespace unidesk, not on a bare Docker/Compose runtime and not on the old D601 Decision Center path. Runtime objects are deployment/decision-center and service/decision-center; GitHub storage credentials are distributed through the decision-center-github-ssh Secret and must only be reported as object/key presence or fingerprint metadata.

The durable store is the GitHub repo pikasTech/decision-center-data on branch main, with base path data. PostgreSQL is the service index/cache, not the durable source of truth. After data migration or repair, validate both layers:

• service health shows storage.primary=github-repo, recordCount and diaryEntryCount;
• /api/storage/verify reports cache and repo index counts with zero deltas;
• the repo worktree HEAD and git ls-remote origin refs/heads/main match;
• bun scripts/cli.ts decision health, decision list and decision diary list succeed through the NC01 k8s entrypoint.

When exporting legacy PostgreSQL data, do not stream Markdown bodies as plain JSONL through terminal output. Use a single-line-safe encoding such as hex-encoded JSON per row, write a manifest with row counts and SHA-256, transfer the bundle through trans download/upload, then compare canonical source and target hashes before claiming migration complete.

GitHub Token

The local GitHub token source is /root/.unidesk/.env/gh_token.txt. It must be stored as a bare token and consumed through controlled YAML/sourceRef or temporary non-printing credential helpers. Do not place the token in command argv, logs, committed files, or rendered manifests. NC01 follows the canonical owner-level state and compatibility-symlink contract in Worktree-Independent Local State; worktrees consume /root/.unidesk/.env and /root/.unidesk/.state through fixed absolute paths instead of copied local trees.

Public Exposure

NC01 HWLAB v0.3 does not require publicExposure unless YAML explicitly declares it and a real FRP token source is available. When publicExposure is absent, control-plane public probe is skipped and must not block runtime readiness.

Web-probe sentinel deployments that need public ingress must declare their own YAML publicExposure and Secret sourceRef. Do not create placeholder FRP tokens; a missing platform-infra/pk01-frp.env token source is a deployment blocker for FRP-backed public exposure.

Validation Entrypoints

• Provider/trans: scripts/trans NC01 argv true.
• NC01 k8s route: scripts/trans NC01:k3s kubectl get nodes -o wide.
• Decision Center: bun scripts/cli.ts decision health; drill-down storage verification can be run inside the NC01 decision-center Pod against /api/storage/verify.
• HWLAB v0.3: bun scripts/cli.ts hwlab nodes control-plane status --node NC01 --lane v03 --full.
• AgentRun v0.2: bun scripts/cli.ts agentrun control-plane status --node NC01 --lane nc01-v02.