labby

<!-- Absolute raw URL, not relative: unraid/ca/labby.xml points Community Applications at this file's raw URL, and CA renders the markdown outside any repo context where a relative path would 404. Markdown image syntax, not <img>: the fleet repository contract's readme_lead() skips lines starting with '![' when locating the lead paragraph, but not raw HTML tags. Keep this comment on ONE line for the same reason -- only a comment's first line is skipped. -->
![Labby](https://raw.githubusercontent.com/dinglebear-ai/labby/main/docs/assets/brand/labby-banner.png)

# Labby

Rust MCP gateway with Code Mode, authentication, setup, logs, CLI, HTTP API, and operator web UI.

Canonical remote: `git@github.com:dinglebear-ai/labby.git`.

The root README is the public entrypoint. The topic docs in
[docs/](./docs/README.md) own the detailed contracts; when this file and a topic
doc disagree, fix the topic doc first and then refresh this summary.

## Contents

- [What Labby Does](#what-labby-does)
- [Quick Start](#quick-start)
- [Core Workflows](#core-workflows)
- [Runtime Surfaces](#runtime-surfaces)
- [Configuration](#configuration)
- [Current Catalogs](#current-catalogs)
- [Architecture](#architecture)
- [Development](#development)
- [Documentation](#documentation)

## What Labby Does

Labby is centered on the current gateway/operator surface:

- **MCP gateway** - connect HTTP and stdio upstream MCP servers, inspect their
  tools/resources/prompts, apply exposure filters, publish protected MCP routes,
  and optionally collapse the upstream catalog into Code Mode `search` and
  `execute`.
- **Direct stdio proxy** - launch one stdio MCP server with
  `labby proxy /path/to/dist.js` and expose its unmodified MCP surface over
  loopback or an owned Tailscale Serve HTTPS port with tailnet, bearer, OAuth,
  or explicit no-auth policy.
- **Authentication and protected routes** - run bearer or OAuth authentication,
  manage route-scoped access, authorize upstream OAuth connections, and publish
  protected MCP endpoints.
- **Code Mode snippets** - author, store, and run reusable JavaScript snippets
  against the upstream catalog, with artifacts persisted under `$LABBY_HOME`.
- **Setup and doctor** - bootstrap `~/.labby`, provision the host service, and
  run a health audit across env, reachability, auth, and versions.
- **Filesystem service** - scoped, path-safety-checked file operations exposed
  through the same action dispatch as every other service.
- **Server logs** - search and tail the local `labby serve` log stream.
- **Incus and bare-metal setup** - provision and operate a dedicated Labby
  gateway host without introducing a separate fleet or deployment product.
- **Generated discovery** - publish code-owned service, action, environment,
  proxy configuration, API route, OpenAPI, MCP help, CLI help, and
  feature-matrix artifacts under
  [docs/generated](./docs/generated/README.md).

Use the generated service, action, and CLI catalogs below for the complete
current product surface instead of copying inventories into hand-written
documentation. Standalone ACP chat, Marketplace/MCP Registry browser, Fleet,
Deploy, and the old Agent Artifact Manager (Stash) remain retired; current Linux principal-scoped File Stash is a separate contract. Bounded provider-backed discovery
through the `artifacts` control-plane service does not restore those products.

## Quick Start

### Install Labby

Download the reviewed installer snapshot over canonical HTTPS, then run it locally:

```bash
curl --proto '=https' --proto-redir '=https' --tlsv1.2 -fSLo labby-install.sh \
  https://raw.githubusercontent.com/dinglebear-ai/labby/5ee609bb255bebfbd9eef4d805998ac1e084b878/scripts/install.sh
sh labby-install.sh
```

This initial script is trusted through canonical HTTPS delivery and the explicitly reviewed commit snapshot above; the download does not follow a mutable branch. Its reviewed, embedded SHA-256 pins authenticate the verifier bootstrap; the installer never downloads a replacement checksum to decide which verifier to trust. It uses an installed GitHub CLI **2.102.0 or newer**, or downloads and verifies pinned 2.102.0 into a private temporary directory. It does not change your PATH or install that helper globally. Required system tools are `curl`, `tar`, and `sha256sum` or `shasum`; macOS bootstrap also uses `unzip`.

Labby release archives still require checksum and provenance verification against the exact repository, release workflow, immutable tag and hosted-runner policy. Releases with `<archive>.sigstore.jsonl` bundles need no GitHub account: verification runs without tokens and with an empty credential store. Older releases without bundles require your own GitHub authentication; the installer stops before downloading their archive if authentication is unavailable. No privileged credential is supplied or shared. Installing a binary does not establish complete onboarding; the subsequent product-owned setup checks remain required.

The recommended local setup uses a native service, loopback listener, generated protected credentials, and a short-lived browser handoff. In Settings, connect your Agent provider, choose a discovered model and complete a starter Agent test, register selected supported clients, then use Discover to add and verify an MCP server. Required failures remain visible and resumable; installation alone is not full readiness. No manual configuration-file edits are needed on this path.

#### Optional agent-assisted guidance

The checked-in `install-labby` skill helps with guided installation, advanced deployments, and repair. It is optional. To add it to a skill-aware agent:

```bash
npx skills add https://github.com/dinglebear-ai/labby --skill install-labby
```

```text
$install-labby
```

The skill inspects the selected host, follows binary-owned setup operations, helps with explicitly requested advanced deployment choices, and verifies the same required first-use checks. Built-in Agent configuration and external-client registration are separate steps. Security-sensitive durable writes remain owned by the Labby binary.

See [`skills/install-labby/SKILL.md`](./skills/install-labby/SKILL.md) for the canonical APM orchestration skill 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`, `using-codemode`, and `using-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:
use the standalone installer above and `labby setup` for that. The optional
`$install-labby` skill can guide those steps.

#### Manual Verified Release

For independent verification of the installer itself, use GitHub CLI **2.102.0 or newer**. Older versions are rejected by Labby's installer and release gates because they lack the corrected signer and source-ref verification policy. Public provenance bundles allow this verification without GitHub login; legacy attestation lookup requires your own `gh auth login` or `GH_TOKEN`.

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"
curl -fSLO "$base/labby-install.sh"
curl -fSLO "$base/labby-install.sh.sha256"
# For releases publishing bundles; older releases require authenticated verification.
curl -fSLO "$base/labby-install.sh.sigstore.jsonl"
gh attestation verify labby-install.sh \
  --bundle labby-install.sh.sigstore.jsonl \
  --repo dinglebear-ai/labby \
  --signer-workflow dinglebear-ai/labby/.github/workflows/release.yml \
  --source-ref "refs/tags/$version" \
  --deny-self-hosted-runners
shasum -a 256 -c labby-install.sh.sha256
LABBY_INSTALL_VERSION="$version" sh ./labby-install.sh
```

MCP clients that prefer npm launchers can run Labby through the Node wrapper:

```bash
npx -y @dinglebear/labby mcp
```

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 Windows installer source uses the same reviewed verifier pins,
protected temporary extraction, and account-free bundle policy; Windows runtime
qualification is still required before a Windows release claim.

The separately downloaded and attested install scripts resolve an immutable GitHub Release containing the current
platform asset, prepare a verified GitHub CLI, 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. 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 to