nkapp hub

Starts the Nanokit local bridge to connect your project workspace to the Nanokit Hub Dashboard.

Auto-Managed Bridge: In most cases, you do not need to run nkapp hub manually. When you execute nkapp up, Nanokit automatically spins up and manages the Bridge System Container (nk-<project>-<env>-bridge) in the background. Running nkapp hub is only required as a standalone fallback or for advanced debugging.

Usage


nkapp hub [options]

Options

Flag	Description	Default
`-p, --port <port>`	Specify the port for the bridge to listen on.	`3006` (or `$NANOKIT_BRIDGE_PORT`)
`-t, --target <url>`	Hub UI target URL to open.	auto-detected
`--open`	Open the Hub in the default browser (automatically disabled inside containers).	`true`
`--no-watch`	Disables monitoring file changes inside the workspace.	`false`
`--status`	Report whether a bridge is already running on the port, then exit.	—
`--stop`	Stop the bridge running on the port and exit (does not start a new one).	—
`--restart`	Stop a bridge already running on the port, then start a fresh one.	—

Bridge Lifecycle (`--status` / `--stop` / `--restart`)

The bridge that feeds the Hub is a long-running process. nkapp up and nkapp deploy do not recycle it, so after rebuilding the CLI you may need to recycle the bridge yourself to pick up new code:


nkapp hub --status    # is a bridge running on this port?
nkapp hub --stop      # shut it down
nkapp hub --restart   # stop the old one, then start fresh

These flags drive the bridge over loopback HTTP (POST /shutdown, loopback-only): the CLI pings http://127.0.0.1:<port>/health to detect a live bridge and posts to /shutdown to stop it, then waits for the port to free up. Working over loopback (instead of killing by PID) is what makes a restart succeed across the WSL ↔ Windows shared-localhost boundary, where the bridge process may not be reachable by PID from the side running the CLI.

Containerized bridge: for the managed local bridge container (nk-<project>-<env>-bridge), --restart recreates the container rather than issuing a plain docker restart. A bare restart keeps the stale dist bind-mount, so after a CLI rebuild the container would still run the old code; recreating it picks up the new build.

Description

The hub command launches a background bridge (WebSocket and HTTP server) that acts as a secure proxy between your local development workspace (including any remote VPS tunnels) and the browser-based Nanokit Hub UI.

The Hub connects only to your LOCAL bridge. Although the Hub UI is served over HTTPS from Nanokit’s servers (e.g. hub.nanokit.dev), it talks exclusively to the bridge running on your own machine at http://127.0.0.1:3006 (browsers treat http/ws to 127.0.0.1 as a secure exception, so loopback works from an HTTPS page). It never falls back to a remote/VPS bridge — that would show server-side data instead of your projects. When no local bridge is reachable (e.g. the Hub opened from a phone, or the bridge isn’t running), the Hub shows a clear “No local bridge detected” state with a Retry button, and suggests running nkapp up. The only surface that intentionally reads a remote bridge is the Status page (and the Caddy /_bridge endpoint), which reports the served cluster’s real system data.

Once running (either automatically via nkapp up or manually via nkapp hub), you can open the Nanokit Hub to:

Monitor System Metrics: View real-time container resource utilization (CPU and RAM).
Live Log Streaming: Stream real-time terminal outputs from all active microservices.
Database Branching: Perform physical actions like DB Fork, Reset, or Merge with a single click.
Container Controls: Start, stop, and restart individual services directly from the graphical interface.

The Auto-Bridge Lifecycle

When using standard project orchestration:

Running nkapp up automatically invokes ensureBridge().
This creates and launches the managed nk-<project>-<env>-bridge system container.
The bridge mounts your local workspace and starts listening on port 3006.
When you tear down your environment using nkapp destroy, the bridge container is automatically stopped and cleaned up along with the other project resources.