docs: clarify single-binary distribution (#3592)

2026-09-12 16:53:15 +01:00
parent 8892920514
commit 01afaf05b3
7 changed files with 58 additions and 12 deletions
@@ -21,6 +21,18 @@ Run it locally or self-host it on your own infrastructure. Use the [mobile remot

 Open source, multi-provider, no telemetry, not tied to any cloud.

+## Distribution
+
+Kandev is distributed as a native Go binary for each supported platform. The
+compiled web frontend is embedded in that binary. The binary serves the web UI
+and API, so the application server does not need Node.js, a separate web
+server, or a frontend build at runtime.
+
+Homebrew, Scoop, release archives, and the desktop app run this native binary
+directly. The npm/npx package adds a small Node.js platform selector, so Node.js
+is required to launch Kandev through npm/npx but not by the application server.
+Release bundles also include `agentctl` helpers for task environments.
+
 ## Vision

 > **Humans stay in control.** Define tasks, build agentic workflows with gates, review every change, decide what ships.
@@ -236,7 +248,7 @@ We also want to add support for this remote runtime:
 apps/
 ├── backend/    # Go backend (orchestrator, lifecycle, agentctl, WS gateway)
 ├── web/        # Vite/React frontend (SPA, Zustand, real-time subscriptions)
-├── cli/        # CLI tool (npx kandev launcher)
+├── cli/        # npm shim for the native Go runtime
 ├── desktop/    # Tauri desktop shell
 └── packages/   # Shared UI components & types
 ```
@@ -5,7 +5,7 @@ description: "Understand Kandev's process, code, runtime, persistence, event, pr

 # Architecture

-Kandev is a server-first development workbench. A Go backend owns durable product state and orchestration. The browser UI is a Vite-built React SPA. Agent processes run behind an `agentctl` sidecar in local, worktree, container, or remote task environments.
+Kandev is a server-first development workbench. The released application is a single native Go binary with the compiled web frontend embedded. It serves the web UI, HTTP API, WebSocket API, and MCP endpoint from one backend listener. Agent processes run behind an `agentctl` sidecar in local, worktree, container, or remote task environments.

 ## Read this page in order

@@ -34,7 +34,10 @@ These adjacent launch layers have different jobs:
 - The published `apps/cli/bin/` npm shim selects the matching `@kdlbs/runtime-*` package and starts its native `kandev` binary.
 - `apps/desktop/` is a Tauri shell. Rust starts its bundled `kandev --headless` on an owned loopback origin and owns native windows, external links, notifications, and updates. The product UI is still the backend-served SPA.

-The root build embeds generated web assets in the Go binary. `make dev` instead starts Vite and configures Go to proxy it, so HTTP, API, and WebSocket traffic still enters through Go.
+The release build embeds generated web assets in the Go binary. `make dev`
+instead starts Vite and configures Go to proxy it, so HTTP, API, and WebSocket
+traffic still enters through Go. Installed releases do not use a separate web
+server.

 ## Backend ownership

@@ -5,7 +5,9 @@ description: "Change Kandev's Go backend across domain, API, event, persistence,

 # Backend Development

-The Go module in `apps/backend/` builds both the unified `kandev` binary and the `agentctl` helper installed in task environments.
+The Go module in `apps/backend/` builds the native `kandev` application binary
+with the compiled web frontend embedded. It also builds the separate `agentctl`
+helper installed in task environments.

 ## Quick path

@@ -5,7 +5,7 @@ description: "Install, start, and operate Kandev from the command line."

 # Kandev CLI

-The `kandev` command starts a local Kandev backend, which serves the web UI, HTTP API, WebSocket API, and MCP endpoint. Use it when you want a browser-based installation or a headless/service process. For a packaged system WebView and desktop updates, use the [desktop app](desktop-app.md) instead.
+The packaged `kandev` executable is a single native Go binary with the compiled web frontend embedded. It starts the backend and serves the web UI, HTTP API, WebSocket API, and MCP endpoint from one listener. Use it for a browser-based installation or a headless/service process. For a packaged system WebView and desktop updates, use the [desktop app](desktop-app.md) instead.

 ## Quick path

@@ -22,9 +22,19 @@ The `kandev` command starts a local Kandev backend, which serves the web UI, HTT
 | Linux | `arm64`, `x64` | Homebrew, npm/npx |
 | Windows | `x64` | Scoop, npm/npx |

-The npm package is a small Node.js shim. It selects an exact, same-version native runtime package for `process.platform` and `process.arch`, then starts its `kandev` binary. npm 7 or later is required because the native packages are platform-specific optional dependencies. There is no native Windows ARM64 npm package; running the x64 package under Windows emulation is OS-dependent and is not a tested release target.
+The `kandev` binary contains the backend and compiled web application. A
+release bundle also contains the host `agentctl` and Linux/macOS remote
+`agentctl` helpers for task environments. These helpers support agent
+execution in SSH and container environments. They do not serve the Kandev web
+application.

-Every runtime bundle contains the backend, `agentctl`, the embedded web application, and Linux/macOS `agentctl` helpers used by supported remote executors. Node.js is used only to select the npm runtime; the application itself is native.
+The npm package is a small Node.js shim. It selects an exact, same-version
+native runtime package for `process.platform` and `process.arch`, then starts
+its `kandev` binary. npm 7 or later is required because the native packages are
+platform-specific optional dependencies. Node.js is not needed to serve the
+Kandev web application. There is no native Windows ARM64 npm package. Running
+the x64 package under Windows emulation is OS-dependent and is not a tested
+release target.

 ## Install

@@ -194,7 +204,10 @@ The old `--web-port` spelling has been removed, not retained as an alias. The la

 ### `start` is for a source build

-`kandev start` makes the executable invoke its own embedded backend instead of resolving an installed bundle. It is a contributor/local-production-build path, not a second installation channel. From a checkout, use the Make targets so the correct binary and embedded web assets are built:
+`kandev start` uses the embedded web assets and backend in the executable. It is
+a contributor/local-production-build path, not a second installation channel.
+From a checkout, run the Make targets to build the correct binary and embedded
+web assets:

 ```bash
 make build
@@ -5,7 +5,11 @@ description: "Set up Kandev, find the owning subsystem, run focused checks, upda

 # Contributing to Kandev

-Kandev combines a Go server and native launcher, a Vite/React web client, a TypeScript development supervisor and npm shim, a Tauri desktop shell, and task-environment helpers. Begin at the subsystem that owns the behavior; do not recreate its rules in a neighboring layer.
+Kandev ships the web client inside a native Go application binary. The source
+tree also contains the Vite/React web client, a TypeScript development
+supervisor and npm shim, a Tauri desktop shell, and task-environment helpers.
+Begin at the subsystem that owns the behavior. Do not recreate its rules in a
+neighboring layer.

 ## Quick path

@@ -76,7 +80,11 @@ KANDEV_HOME_DIR="$PWD/.kandev-dev" KANDEV_DEBUG_DEV_MODE=true make dev-backend

 One backend owns a Kandev home at a time. Raw backend commands use the normal home by default, so a second backend with that home stops before it changes shared state. For an intentional second backend, use a separate `KANDEV_HOME_DIR`, database, and port.

-Use `make build` for a production build. Use `make start` for a production-shaped local start; it installs dependencies, builds and synchronizes the embedded web application, then launches Kandev and writes `<resolved-home>/logs/backend-logs.log`.
+Use `make build` for a production build. It builds the web application, copies
+its assets into the Go embed tree, and builds the native `kandev` binary. Use
+`make start` for a production-shaped local start. It installs dependencies,
+builds and synchronizes the embedded web application, then launches Kandev and
+writes `<resolved-home>/logs/backend-logs.log`.

 ## Find the owner

@@ -5,7 +5,11 @@ description: "Run the Kandev control plane in Docker and understand Docker-based

 # Docker

-The published image runs the Kandev control plane: native backend, web UI, API, WebSocket endpoint, external MCP endpoint, and the host-side `agentctl`. This is different from the **Local Docker executor**, which creates a separate container for an agent.
+The published image runs the Kandev control plane from a native Go binary. The
+binary contains the compiled web UI and serves the API, WebSocket endpoint, and
+external MCP endpoint. The image also includes the host-side `agentctl`. This
+is different from the **Local Docker executor**, which creates a separate
+container for an agent.

 For Kubernetes, see [Kubernetes](k8s.md). For executor profiles, see [Executors](executors.md#local-docker).

@@ -11,6 +11,10 @@ GitHub Release, container images, Homebrew formula, and Scoop bucket.

 Kandev uses one semantic version across the Git tag, native runtime bundles, desktop app, npm packages, GitHub release, container images, Homebrew formula, and Scoop bucket. Publish through the manual **Release** GitHub Actions workflow; do not update channels independently.

+Each platform release contains a native Go `kandev` binary with the compiled
+web frontend embedded. Runtime archives also include `agentctl` binaries for
+task environments.
+
 ## Quick path

 1. Choose one workflow mode.
@@ -93,7 +97,7 @@ Normal mode performs these stages:

 1. **Preflight and prepare version.** Compute the next version from packages and tags, then verify that the committed public key matches the `release` environment fingerprint before changing release files. Update the CLI package/lock, desktop package and Tauri/Cargo manifests, and `CHANGELOG.md`.
 2. **Merge and tag.** Open a release branch and PR. Use the protected administrator token to squash-merge the exact head without queue or CI latency. Select GitHub's reported merge commit, then revalidate the public key before importing the protected signing key. Verify the signed `vX.Y.Z` tag locally before the push.
-3. **Build web and runtimes.** Build the SPA and five runtime targets: Linux x64/arm64, macOS x64/arm64, and Windows x64. Each archive contains `kandev`, the host `agentctl`, and required remote agentctl helpers; the workflow produces an adjacent checksum for each archive.
+3. **Build web and runtimes.** Build the SPA and five runtime targets: Linux x64/arm64, macOS x64/arm64, and Windows x64. Embed the SPA in each native Go `kandev` binary. Each archive contains `kandev`, the host `agentctl`, and required remote agentctl helpers. The workflow produces an adjacent checksum for each archive.
 4. **Build desktop.** Embed the matching runtime and package the same five platform/architecture targets into macOS, Linux, and Windows installer formats.
 5. **Build containers.** Publish amd64/arm64 base manifests, enforce the universal-image size gate, then publish multi-architecture universal images.
 6. **Publish GitHub Release.** Attach runtime archives, checksums, desktop artifacts, notes, and the updater feed when eligible.