@dinglebear/labby 1.20.1 → 2.2.1

package/LICENSE

@@ -659,3 +659,36 @@ specific requirements.
 if any, to sign a "copyright disclaimer" for the program, if necessary.
 For more information on this, and how to apply and follow the GNU AGPL, see
 <http://www.gnu.org/licenses/>.
+
+-------------------------------------------------------------------------------
+LABBY PROJECT LICENSING NOTICE
+-------------------------------------------------------------------------------
+
+Except for third-party material and files carrying a separate license or
+copyright notice, the original software in Labby authored by Jacob Magar or
+Dinglebear AI is licensed under the GNU Affero General Public License version
+3.0 only (SPDX: AGPL-3.0-only), whose complete and unmodified text appears
+above.
+
+This grant applies to revisions containing this notice. Earlier revisions
+remain available under the licenses under which they were originally
+published; those earlier grants are not revoked.
+
+Dinglebear-owned portions are also available under separate written commercial
+terms for organizations that need terms outside AGPL-3.0-only. No commercial
+license is granted by this file. A commercial agreement covers only copyrights
+owned or controlled by Dinglebear AI; it does not relicense third-party code,
+dependencies, trademarks, data, artwork, or separately licensed material.
+
+Files and directories containing their own license, copyright notice, or
+upstream attribution remain under those original terms. Dependencies are
+licensed by their respective authors.
+
+External code contributions must not be merged until Dinglebear AI has a
+contributor agreement or another documented grant permitting both AGPL and
+commercial distribution. Issues, bug reports, and suggestions do not transfer
+copyright.
+
+To request separate commercial terms, contact Dinglebear AI through this
+repository's GitHub contact channels and identify the intended product,
+deployment model, distribution method, and support needs.

package/README.md

@@ -66,7 +66,7 @@ After installing Labby, configure proxy defaults once and launch a JavaScript
 stdio server without proxy flags:
 
 ```bash
-labby setup proxy
+labby config proxy set
 labby doctor proxy
 labby proxy /path/to/dist.js
 ```
@@ -85,10 +85,47 @@ development. Bearer and OAuth setup, exact-port resource audiences, safe Serve
 ownership, configuration precedence, output modes, and recovery are covered in
 the [stdio MCP proxy guide](./docs/guides/STDIO_MCP_PROXY.md).
 
-### Install A Release
+### Install Labby with `$install-labby`
+
+The first-class guided install path is the checked-in `install-labby` Agent Skill. Install that one skill, then ask a skill-aware agent to run it:
+
+```bash
+npx skills add https://github.com/dinglebear-ai/labby --skill install-labby
+```
+
+```text
+$install-labby
+```
+
+The skill inspects the machine, asks for authentication/listener/deployment choices, drives the verified release installer plus `labby setup`, configures supported persistence and HTTPS exposure, helps register Labby in installed agents, and does not declare success until `labby doctor` plus a live MCP smoke pass. Security-sensitive durable writes remain owned by the Labby binary rather than duplicated in skill prose.
+
+See [`plugins/labby/skills/install-labby/SKILL.md`](./plugins/labby/skills/install-labby/SKILL.md) for the orchestration contract and [`docs/adr/0001-install-labby-first-class-install-orchestrator.md`](./docs/adr/0001-install-labby-first-class-install-orchestrator.md) for the architecture decision.
+
+#### Install through APM
+
+Teams that standardize on the [Agent Package Manager](https://microsoft.github.io/apm/)
+get the skills and the MCP registration in one step:
+
+```bash
+apm install -g dinglebear-ai/labby
+```
+
+That deploys `install-labby`, `using-labby`, and `creating-snippets` into
+`~/.claude/skills` and `~/.agents/skills` and registers the `labby` stdio MCP
+server (`npx -y @dinglebear/labby mcp`) for Claude Code and Codex; `apm.yml` at
+the repository root is the manifest and `apm outdated -g` reports new
+releases. APM does not install the `labby` binary or provision a gateway host:
+run `$install-labby` (or the verified release installer below) and
+`labby setup` for that.
+
+#### Manual Verified Release
+
+Prerequisites for the verified release path are `curl`, `tar`, a SHA-256 tool (`sha256sum` or `shasum`), and an authenticated GitHub CLI (`gh`) build that supports `gh attestation verify`. The installer checks all of these before resolving or downloading any Labby release, so a fresh machine fails fast with an actionable dependency message rather than downloading an artifact it cannot verify (the `gh auth status` probe itself contacts GitHub, so the guarantee is about release downloads, not all network use). Ubuntu 26.04's distro package currently ships `gh 2.46.0`, which is too old for this trust path; install or upgrade GitHub CLI from GitHub's current official packages/releases, verify `gh attestation verify --help`, then run `gh auth login` (or provide `GH_TOKEN` for headless automation).
 
 Linux/macOS:
 
+> **Release compatibility gate:** select a release that publishes `labby-install.sh` and contains the documented first-run `labby setup --role ...` interface. Confirm the selected tag exposes the installer and checksum before continuing; do not assume an older release matches the current setup contract.
+
 ```bash
 version=vX.Y.Z
 base="https://github.com/dinglebear-ai/labby/releases/download/$version"
@@ -101,8 +138,6 @@ gh attestation verify labby-install.sh \
   --deny-self-hosted-runners
 shasum -a 256 -c labby-install.sh.sha256
 LABBY_INSTALL_VERSION="$version" sh ./labby-install.sh
-labby setup
-labby serve --host 127.0.0.1 --port 8765
 ```
 
 MCP clients that prefer npm launchers can run Labby through the Node wrapper:
@@ -111,33 +146,34 @@ MCP clients that prefer npm launchers can run Labby through the Node wrapper:
 npx -y @dinglebear/labby mcp
 ```
 
-Windows PowerShell:
-
-```powershell
-$Version = "vX.Y.Z"
-$Base = "https://github.com/dinglebear-ai/labby/releases/download/$Version"
-Invoke-WebRequest "$Base/labby-install.ps1" -OutFile labby-install.ps1
-Invoke-WebRequest "$Base/labby-install.ps1.sha256" -OutFile labby-install.ps1.sha256
-gh attestation verify labby-install.ps1 `
-  --repo dinglebear-ai/labby `
-  --signer-workflow dinglebear-ai/labby/.github/workflows/release.yml `
-  --source-ref "refs/tags/$Version" `
-  --deny-self-hosted-runners
-$Expected = ((Get-Content labby-install.ps1.sha256) -split '\s+')[0]
-if ((Get-FileHash labby-install.ps1 -Algorithm SHA256).Hash.ToLower() -ne $Expected) { throw "installer digest mismatch" }
-$env:LABBY_INSTALL_VERSION = $Version
-& ./labby-install.ps1
-labby setup
-labby serve --host 127.0.0.1 --port 8765
-```
+The npm launcher is a weaker trust path than the installer scripts. It
+downloads the release archive for the current platform and verifies only the
+`.sha256` sidecar (or the `SHA256SUMS` manifest) published next to it on the
+same release; it does not require `gh` and does not verify GitHub build
+provenance. Use `labby-install.sh` on Linux or macOS when provenance
+verification matters. Current releases do not publish Windows binaries or
+installers.
 
 The separately downloaded and attested install scripts resolve an immutable GitHub Release containing the current
 platform asset, require `gh`, verify the archive's attestation against the
 Labby repository, `release.yml`, exact tag, and hosted-runner policy, verify its checksum, and install `labby` onto the
-user PATH. They do **not** perform
-operator provisioning or environment setup. The scripts only install the binary
-(from a release or fallback source build); all first-run provisioning is handled
-inside `labby` via `labby serve` bootstrap and `labby setup`.
+user PATH. The shell installer then runs `labby setup`, which
+asks whether this machine should run a server or connect to an existing one.
+Server setup configures authentication and a managed native service, or an Incus
+container on supported Linux hosts. Client setup saves the explicit gateway URL
+and configures browser sign-in or a bearer token. Desktop installation is optional
+and off by default; if the published desktop package is unavailable, setup reports
+that and still completes.
+For Labby's supported ChatGPT web connection, configure the server in OAuth mode
+and expose it through a publicly reachable HTTPS `LABBY_PUBLIC_URL`; bearer-only
+mode is for local/CLI clients and is not the supported ChatGPT web path. The web
+UI offers bearer token sign-in only over HTTPS or a direct loopback connection;
+behind a TLS-terminating proxy, set `LABBY_PUBLIC_URL=https://...` to unlock it.
+
+For unattended shell installs, set `LABBY_SETUP_ROLE=server` or `client` and the
+corresponding `LABBY_SETUP_*` options. For a binary-only install, set
+`LABBY_INSTALL_NO_SETUP=1`. Manual and automatic `labby host update` operations always
+skip first-run setup. See the [setup guide](./docs/services/SETUP.md) for examples.
 
 Override install behavior with `LABBY_INSTALL_DIR`, `LABBY_INSTALL_VERSION`, or
 `LABBY_INSTALL_REPO`. Source fallback is off by default. Opt in with
@@ -153,15 +189,9 @@ it without downloading or changing `$LABBY_HOME`:
 LABBY_INSTALL_ROLLBACK=1 sh ./labby-install.sh
 ```
 
-```powershell
-$env:LABBY_INSTALL_ROLLBACK = '1'
-& .\labby-install.ps1
-```
-
 Rollback switches only the installed executable and receipt. It does not
 downgrade or delete configuration, credentials, databases, or other durable
-state. Inspect the receipt at `<install-dir>/.labby-install/receipt` on Unix or
-`receipt.json` on Windows.
+state. Inspect the receipt at `<install-dir>/.labby-install/receipt`.
 
 Release qualification can install an already-downloaded candidate without
 network or source fallback by setting `LABBY_INSTALL_LOCAL_BINARY` and its exact
@@ -192,16 +222,16 @@ updater job after the server passes its health check. See the
 For an installation without a persistent server, use the standalone daily job:
 
 ```bash
-labby update --auto-update enable
-labby update --auto-update status
-labby update --auto-update disable
+labby host update auto enable
+labby host update auto status
+labby host update auto disable
 ```
 
 Both modes require Apple Silicon and GitHub CLI (`gh`) for release attestation
 verification. They skip drafts, prereleases, missing platform assets, and versions
 equal to or older than the installed binary. The installer verifies attestations
 and checksums before atomic replacement. No separate language runtime is required.
-Use `labby update --automatic --dry-run` to check without installing.
+Use `labby host update --automatic --dry-run` to check without installing.
 
 ### Build From Source
 
@@ -287,9 +317,8 @@ checkout.
 
 The recommended self-hosted gateway substrate is an amd64 Ubuntu 26.04 Incus
 system container. Bare metal is the secondary supported shape for a dedicated
-gateway host or VM. Docker is retained for explicit development/image smoke,
-but it is not the recommended production boundary for Labby because stdio MCP
-servers and agent CLIs are installed and launched at runtime.
+gateway host or VM. Labby does not ship a Docker image or Compose deployment;
+stdio MCP servers and agent CLIs are installed and launched at runtime.
 
 ```bash
 scripts/incus-bootstrap.sh --version vX.Y.Z
@@ -321,40 +350,85 @@ set, it starts a standalone local gateway instead. See the
 [local bridge guide](./docs/surfaces/TRANSPORT.md#local-bridge-to-the-running-daemon)
 for client configuration and `LABBY_SERVER_URL` fail-closed behavior.
 
-### Manage Upstream MCP Gateways
+### Discover Commands
+
+```bash
+labby --help
+labby help --all
+labby help server --all
+labby help --search oauth
+labby help --all --json
+```
+
+Public command names use separate words without hyphens. Flags and resource
+names retain normal syntax. Help and completion work offline, even with broken
+configuration. See the [CLI guide](./docs/surfaces/CLI.md) and
+[breaking migration map](./docs/generated/cli-migration.md).
+
+### Select A Gateway
 
 ```bash
-labby gateway add \
-  --name github \
+labby context add homelab --server https://example.invalid --use
+labby auth login --context homelab
+labby --context homelab server list
+labby config check
+```
+
+Contexts save non-secret destinations in the existing host configuration.
+Explicit `--server` or `--context` never borrows an unrelated environment token
+and never falls back to local execution. Host-local commands remain local.
+
+### Manage Upstream MCP Servers
+
+```bash
+labby server add github \
   --url https://example.com/mcp \
-  --bearer-token-env GITHUB_MCP_TOKEN \
-  -y
+  --bearer-token-env GITHUB_MCP_TOKEN
 
 labby gateway reload
-labby gateway list
+labby server list
 ```
 
-Stdio upstreams execute local commands when tested or reconciled, so gateway
-tests and config mutations use the shared destructive-action confirmation gate.
+Stdio upstreams can execute local commands when tested or reconciled. Review
+configuration before adding or testing them; the CLI retains each operation's
+existing authorization and confirmation requirements.
 The stdio spawn guard allows known runtimes such as `npx`, `uvx`, `docker`,
 `node`, `python`, `python3`, `deno`, `pipx`, and `dnx`; customize it in
 `[gateway]` inside `config.toml`.
 
+Missing creation arguments can be filled by `labby server add` in an interactive
+terminal. Scripts should use complete arguments and `--no-input --json`.
+Timeouts use explicit units, such as `30s` or `2m`.
+
+```bash
+labby server restart alpha beta --timeout 30s
+labby server restart --all --dry-run
+labby --context homelab completions refresh
+labby completions zsh --resources
+```
+
+Restart waits for observed completion and a connected replacement unless
+`--no-wait` is explicit. Bulk operations report every target and return a failing
+exit status when any target fails; uncertain operations are never replayed.
+Optional cached completion is authority-scoped and offline on every Tab key.
+
 ### Use Code Mode
 
 When `[code_mode].enabled = true`, Labby hides raw proxied upstream tools from MCP
 `list_tools()` and exposes the canonical synthetic `codemode` tool.
 
 ```bash
-labby gateway code status
-labby gateway code enable
-labby gateway code exec --code 'async () => tools.length'
+labby code status
+labby code enable
+labby code search 'github issues' --limit 5
+labby code describe github.search_issues
+labby code run --file ./task.js
 ```
 
 MCP call shapes:
 
 ```json
-{ "code": "async () => (await codemode.search(\"github issues\")).results" }
+{ "code": "async () => (await codemode.search({\"query\":\"github issues\",\"limit\":5})).results" }
 ```
 
 ```json
@@ -371,12 +445,12 @@ from inside the sandbox.
 ### Work With Code Mode Snippets
 
 ```bash
-labby snippets list
-labby snippets get gateway-summary
-labby snippets create --name my-snippet --file ./my-snippet.js
-labby snippets validate my-snippet
-labby snippets exec my-snippet
-labby snippets test my-snippet
+labby snippet list
+labby snippet get gateway-summary
+labby snippet add my-snippet --file ./my-snippet.js
+labby snippet validate my-snippet
+labby snippet run my-snippet
+labby snippet test my-snippet
 ```
 
 Snippets are stored per-user under `$LABBY_HOME` and executed through the
@@ -388,18 +462,23 @@ without the `gateway` feature.
 
 ```bash
 labby doctor            # audit every configured service
-labby doctor system     # local env vars, Docker, disk, toolchain
+labby doctor system     # local env vars, disk, toolchain
 labby doctor auth       # auth/OAuth env vars, files, permissions
 labby doctor proxy      # zero-route stdio-proxy config/dependency preflight
 labby doctor proxy --app-url URL --mcp-url URL --route /path
                         # routed public reverse-proxy checks remain available
-labby doctor oauth-relay
-labby health            # lightweight liveness/readiness probe
-labby logs              # tail the active deployment's service journal
+labby doctor relay
+labby gateway status    # query the selected daemon and its upstream state
+labby logs --lines 50    # bounded local rolling logs, without systemd
+labby logs --level error --query REQUEST_ID --json
+labby logs journal --follow  # explicitly stream the deployment journal
 ```
 
 `labby doctor --json` is the CI-friendly form; the exit code reflects the worst
-severity found.
+severity found. Runtime errors include their command, origin, side-effect
+classification, recovery guidance, and a request ID. `--json` errors remain one
+JSON envelope on stderr; command results stay on stdout. Use `-v` or `-vv` for
+diagnostics. `--quiet` suppresses console logs but never hides the actual error.
 
 > **Removed surfaces.** Earlier releases documented `labby marketplace`,
 > `labby stash`, `labby nodes`, and `labby deploy`, along with ACP chat, the MCP
@@ -425,7 +504,7 @@ curl -s -X POST http://127.0.0.1:8765/v1/gateway \
 Dedicated product routes also exist for catalog discovery (`/v1/{service}/actions`),
 setup, doctor, snippets, filesystem, server logs, gateway OAuth
 (`/v1/gateway/oauth/*`), OAuth relay, auth allowlists (`/v1/auth/allowed-emails`),
-`/v1/openapi`, and the browser session routes under `/auth/*`. See
+`/v1/openapi.json`, interactive API docs at `/v1/docs`, and the browser session routes under `/auth/*`. See
 [generated API routes](./docs/generated/api-routes.md) and
 [OpenAPI](./docs/generated/openapi.json).
 
@@ -580,21 +659,15 @@ just build            # cargo build --workspace --all-features
 just build-release    # release build, bin/labby install, ~/.local/bin symlink
 just service-install  # build and install the native persistent gateway service
 just service-status   # inspect the native service manager state
-labby setup host-service install --install-self -y # install current binary + start system service
-labby setup host-service restart --install-self -y # reinstall current binary + restart service
-labby setup host-service status --json # inspect the host Labby gateway service
+labby host service install --install-self -y # install current binary + start system service
+labby host service restart --install-self -y # reinstall current binary + restart service
+labby host service status --json # inspect the host Labby gateway service
 just host-sync        # repo dev shortcut: rebuild + install binary + restart host service
-just dev-container    # explicit Docker compatibility/prod-like smoke path
-just dev-container-debug # explicit Docker debug binary path
 just web-build        # cd apps/gateway-admin && pnpm build
 just web-watch        # rebuild web assets when frontend files change
 just run -- help      # cargo run --all-features -- <args>
 just chat-local       # local Labby admin UI workflow with browser auth disabled
-just dev-up           # start the explicit Docker compatibility stack
-just dev              # alias for just dev-container
-just dev-debug        # alias for just dev-container-debug
 just install          # build-release + symlink ~/.local/bin/labby
-just prod-run         # local prod-like image smoke on port 18765
 just mcp-token        # rotate LABBY_MCP_HTTP_TOKEN in .env
 ```
 
@@ -621,31 +694,14 @@ in-box with `labby setup --provision`. Bare metal uses the same provisioner and
 system unit when the host or VM is dedicated to Labby. The default service is
 `/etc/systemd/system/labby.service`, running as `User=labby`, `Group=labby`, with
 `ExecStart=/usr/local/bin/labby serve`. From a source checkout, `just host-sync`
-remains the rebuild-and-restart developer shortcut. Docker remains available
-for prod-like image smoke and adapter-container work, but it is no longer the
-recommended agent gateway runtime.
-
-### Dev Container
-
-The development Compose stack mirrors the production process controls: a
-read-only root filesystem, dropped capabilities, `no-new-privileges`, loopback
-port binding, bounded logs, and named volumes for durable state and data. It
-also bind-mounts the source repository read-only so locally built web assets are
-visible without rebuilding the image. The clean-checkout defaults mount the
-tracked, non-secret `config/config.example.toml` and `config/.env.example`.
-Set `LABBY_CONFIG_FILE` and `LABBY_ENV_FILE` to select local runtime files;
-Compose mounts both read-only at their canonical paths beneath `$LABBY_HOME`. Labby-owned runtime
-state remains writable in the surrounding `labby-home` named volume. Startup logs and the
-setup settings state report `/home/labby/.labby/config.toml` as the effective
-source. The image installs pinned Claude,
-Codex, and Gemini CLIs for stdio upstreams that invoke provider tools.
+remains the rebuild-and-restart developer shortcut.
 
 ### Releases
 
 Release Please maintains the version/changelog pull request and creates the
 stable tag plus draft GitHub release when that pull request merges. The stable
-tag triggers the heavy GitHub-hosted candidate workflow. It builds Linux,
-macOS, and Windows archives with checksums, builds and smokes the Incus image,
+tag triggers the heavy GitHub-hosted candidate workflow. It builds Linux and
+macOS archives with checksums, builds and smokes the Incus image,
 publishes the npm launcher, and publishes Labby's
 `server.json` metadata to the official MCP Registry. Only after qualification
 and publication succeed does the workflow promote the draft GitHub release.
@@ -659,8 +715,9 @@ removed; operators run `labby setup` themselves. Do not reintroduce a `hooks/`
 directory, bundle a binary under `plugins/labby/bin/`, or add
 Docker/systemd bootstrap logic to plugin assets.
 
-`labby setup plugin-hook` remains a CLI command for on-demand audit and settings
-sync (`--no-repair` for read-only), exercised by `just validate-plugin`.
+`just validate-plugin` runs the supported read-only `labby setup check` flow
+against an isolated Labby home. Plugin lifecycle hooks and per-service plugin
+mutation commands remain retired.
 
 ## Related Servers
 
@@ -675,7 +732,6 @@ sync (`--no-repair` for read-only), exercised by `just validate-plugin`.
 - [synapse-rmcp](https://github.com/dinglebear-ai/synapse) - Local Synapse workflow server for scout and flux actions.
 - [cortex](https://github.com/dinglebear-ai/cortex) - Syslog and homelab log aggregation MCP server.
 - [axon](https://github.com/dinglebear-ai/axon) - RAG, crawl, scrape, extract, and semantic search project.
-- [lumen](https://github.com/dinglebear-ai/lumen) - Local semantic code search MCP server.
 
 ## Documentation
 
@@ -694,4 +750,4 @@ Start at [docs/README.md](./docs/README.md). High-value entrypoints:
 
 ## License
 
-Original Dinglebear-authored portions of this project are licensed under [AGPL-3.0-only](LICENSE). Separate commercial licensing is available for organizations that need terms outside the AGPL. Third-party material remains under its original license. See [LICENSING.md](https://github.com/dinglebear-ai/labby/blob/main/LICENSING.md).
+Original Dinglebear-authored portions of this project are licensed under [AGPL-3.0-only](LICENSE). The same file records the project-specific scope, third-party treatment, contribution policy, and availability of separately negotiated commercial terms.

package/lib/platform.js

@@ -15,14 +15,6 @@ function targetFor(platform = process.platform, arch = process.arch) {
     };
   }
 
-  if (platform === "win32" && arch === "x64") {
-    return {
-      asset: "lab-x86_64-pc-windows-msvc.zip",
-      binary: "labby.exe",
-      archiveType: "zip",
-    };
-  }
-
   if (platform === "darwin" && arch === "arm64") {
     return {
       asset: "lab-aarch64-apple-darwin.tar.gz",
@@ -32,7 +24,7 @@ function targetFor(platform = process.platform, arch = process.arch) {
   }
 
   throw new Error(
-    `Unsupported platform ${platform}/${arch}. Supported targets: linux/x64, darwin/arm64, win32/x64.`,
+    `Unsupported platform ${platform}/${arch}. Supported targets: linux/x64, darwin/arm64.`,
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dinglebear/labby",
-  "version": "1.20.1",
+  "version": "2.2.1",
   "license": "AGPL-3.0-only",
   "description": "Rust MCP gateway with Code Mode, authentication, setup, logs, CLI, HTTP API, and operator web UI.",
   "homepage": "https://github.com/dinglebear-ai/labby#readme",