Hub Local Coordination

This page targets integrators and contributors; most users never touch Hub directly. Hub is DotCraft's local runtime coordinator. It runs per OS user and discovers, starts, reuses, and stops the AppServer process for each workspace. Desktop / TUI use Hub by default.

NOTE

Remote, CI, bots, or explicit AppServer protocol debugging go through AppServer Mode.

Key Properties

• One Hub per OS user
• One AppServer per workspace
• Hub does not handle conversation traffic or proxy the AppServer protocol
• A client only asks Hub during bootstrap: "make sure this workspace's AppServer is available"
• After bootstrap, the client connects directly to the returned AppServer WebSocket URL

When to Start Manually

You usually do not need to run dotcraft hub manually. For coordination debugging:

dotcraft hub

Hub starts a loopback management API and writes discovery metadata to ~/.craft/hub/hub.lock. It allocates local ports automatically; if startup fails because a port is busy, a permission is denied, or security software blocks loopback, restart Hub or Desktop to reallocate.

Local State

~/.craft/hub/
├── hub.lock          # current Hub discovery: API URL, PID, start time, local token, binary path
└── appservers.json   # Hub-tracked AppServer state (display & recovery)

Each workspace also has:

<workspace>/.craft/appserver.lock

It records which AppServer process owns the workspace and prevents multiple local AppServers from running against the same workspace.

When Hub or AppServer finds a stale appserver.lock left by a dead process, it removes the lock and continues. If the lock points to a still-running AppServer with a healthy WebSocket endpoint, Hub reuses that endpoint instead of starting a duplicate process. When the lock points to a live AppServer that Hub cannot safely reuse, close the Desktop / TUI / CLI holding that workspace, or stop the workspace runtime from the tray, then reopen it.

Desktop and the Tray

Desktop is the visual layer; Hub itself is a headless background coordinator. Desktop can:

• Open or switch workspaces
• See recent and running workspaces
• Open Desktop or Dashboard
• Restart or stop Hub-managed workspace runtimes
• Receive system notifications forwarded through Hub (task completion, approvals, runtime state)

When the tray exits, Desktop can ask Hub to stop the workspace AppServers Hub manages.

For Desktop to open a workspace, dotcraft / dotcraft.exe must be on PATH, or the AppServer executable path must be set in Desktop settings.

Building a Client

Read Hub Protocol to discover Hub, call ensure, and subscribe to lifecycle events.

Related

• AppServer Mode — remote / multi-client / CI
• Hub Protocol — client protocol overview
• Unified Session Core — where Hub and AppServer sit in the bigger picture