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/ 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
• Quick Start
• Core Workflows
• Runtime Surfaces
• Configuration
• Current Catalogs
• Architecture
• Development
• 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.

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 Stash products remain retired; bounded provider-backed discovery through the artifacts control-plane service does not restore those products.

Quick Start

Proxy One Stdio MCP Server

After installing Labby, configure proxy defaults once and launch a JavaScript stdio server without proxy flags:

labby config proxy set
labby doctor proxy
labby proxy /path/to/dist.js

The built-in zero-flag policy is Tailscale Serve plus tailnet authorization on a random high port. Child flags follow the first child token unchanged, and an explicit separator is available for unusual commands:

labby proxy /path/to/dist.js --workspace /srv/data --read-only
labby proxy -- npx -y @modelcontextprotocol/server-filesystem /srv/data

Use labby proxy --local --auth none ... for explicit loopback-only 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.

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:

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

$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 for the orchestration contract and 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 get the skills and the MCP registration in one step:

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.

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"
gh attestation verify labby-install.sh \
  --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:

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 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. 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 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 LABBY_ALLOW_SOURCE_FALLBACK=1; a pinned LABBY_INSTALL_VERSION is passed to Cargo as the exact tag instead of silently building the default branch.