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.

Each successful install retains the verified binary by SHA-256 plus an owner-only receipt beneath <install-dir>/.labby-install/. At least the prior verified artifact remains available when distribution is unavailable. Restore it without downloading or changing $LABBY_HOME:

LABBY_INSTALL_ROLLBACK=1 sh ./labby-install.sh

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.

Release qualification can install an already-downloaded candidate without network or source fallback by setting LABBY_INSTALL_LOCAL_BINARY and its exact lowercase LABBY_INSTALL_LOCAL_SHA256. The installer copies that input once to private staging, verifies the staged bytes, and activates those same bytes. It also rehashes every existing cached artifact before reuse. Before changing the binary or either receipt, the installer writes a recovery journal beneath .labby-install/; a later invocation restores the complete pre-install snapshot when it finds an interrupted activation. If restoration fails, the installer stops and retains the journal for diagnosis. All Unix installer entry points share a process-level transaction lock and flush journal boundaries before advancing them. Successful activation retains only the current artifact and the immediately previous artifact required for offline rollback.

Automatic updates on macOS

For a persistent macOS server, enable daily updates in the existing server job:

LABBY_SERVICE_AUTO_UPDATE=1 bash scripts/install-macos-service.sh install

This runs labby serve --auto-update under launchd and removes the separate updater job after the server passes its health check. See the macOS setup instructions.

For an installation without a persistent server, use the standalone daily job:

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 host update --automatic --dry-run to check without installing.

Build From Source

Prerequisites:

• Rust 1.97.1 or newer. CI/release verifies with Rust 1.97.1.
• just for repo commands.
• cargo-nextest for the main test suite.
• pnpm 9.15.9 for the Labby web UI. The repo pins this in .mise.toml and apps/gateway-admin/package.json.
• openssl if you want to generate a bearer token manually.

git clone git@github.com:dinglebear-ai/labby.git
cd labby
just install
just web-build
labby serve --host 127.0.0.1 --port 8765

just install builds the all-features release binary and symlinks it to ~/.local/bin/labby.

On macOS, install the gateway as a persistent per-user service instead of running labby serve in a terminal:

just macos-service-install
just macos-service-status

This installs a launchd LaunchAgent that keeps Labby listening on 127.0.0.1:8765, restarts it after login or exit, and uses the stable absolute LABBY_HOME (default ~/.labby) as both working directory and durable configuration root. It never persists the directory from which installation was invoked. Logs default to the same root. Use just macos-service-restart after changing service settings or just macos-service-uninstall to remove it. The cross-platform just service-install, just service-status, just service-restart, and just service-uninstall bindings select launchd on macOS and systemd on Linux. This is suitable for a Tailscale Serve/Funnel route whose OAuth callback targets the local gateway.

When overriding the launchd paths, LABBY_SERVICE_BIN, LABBY_STATE_DIR, and LABBY_HOME must all be absolute; relative paths fail before the plist or service is changed.

First Run

For loopback development, labby serve can bootstrap a missing bearer token for you. If LABBY_MCP_HTTP_TOKEN is absent and LABBY_AUTH_MODE is not oauth, it generates a token, writes a minimal ~/.labby/.env, reloads it into the running process, prints the setup URL, and continues. The token itself is stored in ~/.labby/.env rather than printed.

Bootstrap writes these required setup keys if no env exists yet:

• LABBY_MCP_HTTP_TOKEN (generated random 64-character hex token)
• LABBY_MCP_TRANSPORT=http
• LABBY_MCP_HTTP_HOST=127.0.0.1
• LABBY_MCP_HTTP_PORT=8765
• LABBY_AUTH_MODE=bearer

It also enforces secure file creation via Labby's env_merge path (0600 perms on Unix) and then skips creating anything else until the web wizard runs.

For explicit setup:

mkdir -p ~/.labby
printf 'LABBY_AUTH_MODE=bearer\nLABBY_MCP_HTTP_TOKEN=%s\n' "$(openssl rand -hex 32)" > ~/.labby/.env
chmod 600 ~/.labby/.env
labby setup
labby serve --host 127.0.0.1 --port 8765

Open http://127.0.0.1:8765/. Build static Labby assets with just web-build first when running from a source checkout.

Self-Host The Gateway

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. Labby does not ship a Docker image or Compose deployment; stdio MCP servers and agent CLIs are installed and launched at runtime.

scripts/incus-bootstrap.sh --version vX.Y.Z
incus exec labby -- systemctl status labby --no-pager
incus exec labby -- curl -fsS http://127.0.0.1:8765/ready

See docs/runtime/INCUS.md for the full Incus runbook, bare-metal variant, /dev/net/tun Tailscale passthrough, manual claude/codex/gemini login checklist, and rollback commands.

Core Workflows

Start Labby

labby serve --host 127.0.0.1 --port 8765
labby mcp

labby serve starts the hosted HTTP runtime: /v1 product APIs, /mcp streamable HTTP MCP, auth routes, OAuth relay endpoints, and static Labby web assets when an export is available. labby mcp is the stdio MCP entrypoint for local MCP clients. A client configured to launch labby mcp does not need an HTTP URL: when a labby serve daemon is reachable, the stdio process becomes a transparent bridge to that daemon and uses its gateway configuration, upstream connections, and OAuth state. If no daemon is found and no explicit target is set, it starts a standalone local gateway instead. See the local bridge guide for client configuration and LABBY_SERVER_URL fail-closed behavior.

Discover Commands

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 and breaking migration map.

Select A Gateway

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

labby server add github \
  --url https://example.com/mcp \
  --bearer-token-env GITHUB_MCP_TOKEN

labby gateway reload
labby server list

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.

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.

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:

{ "code": "async () => (await codemode.search({\"query\":\"github issues\",\"limit\":5})).results" }

{ "code": "async () => callTool(\"github::search_issues\", {\"query\":\"repo:dinglebear-ai/labby gateway\"})" }

{ "code": "async () => codemode.run(\"gateway-summary\", {\"includeHealth\": true})" }

Code Mode can call exposed upstream MCP tools only. It cannot call Labby actions from inside the sandbox.

Work With Code Mode Snippets

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 gateway Code Mode runner, so they can reach exposed upstream tools but not Labby actions. The snippets service is gateway-gated: it is unavailable in builds without the gateway feature.

Audit Health And Logs

labby doctor            # audit every configured service
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 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. 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 Registry browser, and device/fleet runtimes. Those products have been deleted from source, manifests, packaging, and CI — not merely feature-gated. scripts/check-retired-features.sh guards against reintroduction, and the historical designs are archived under docs/archive/retired-labby. Plugin marketplace assets now live in the separate dendrite repo.

Drive The API

Generic action dispatch:

curl -s -X POST http://127.0.0.1:8765/v1/gateway \
  -H "Authorization: Bearer $LABBY_MCP_HTTP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"gateway.list","params":{}}'

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.json, interactive API docs at /v1/docs, and the browser session routes under /auth/*. See generated API routes and OpenAPI.

Runtime Surfaces

MCP service tools use the shared action shape:

{
  "action": "mcp.list",
  "params": { "search": "postgres", "limit": 10 }
}

Every service tool also supports help and schema through the shared dispatcher. Destructive MCP actions use elicitation when the client supports it; headless clients pass "confirm": true inside params.

Configuration

Configuration is split deliberately:

LABBY_HOME selects the one authoritative configuration and durable-state root and must be absolute. It defaults to ~/.labby; Labby does not implicitly read CWD or XDG fallback files. Existing process environment values win over values loaded from the selected .env. Runtime precedence is:

1. CLI flags
2. Environment variables
3. config.toml
4. Built-in defaults

Useful environment variables:

Bearer auth is an operator/admin shortcut for Labby routes. Public protected MCP routes validate route-scoped Labby OAuth JWTs; do not treat LABBY_MCP_HTTP_TOKEN as a public resource credential.

When driving the web UI with automation while OAuth is enabled, pass the bearer token as a same-origin header. /auth/session recognizes that token and returns a synthetic admin session:

TOKEN=$(awk -F= '/^LABBY_MCP_HTTP_TOKEN=/{print $2}' ~/.labby/.env)
agent-browser open http://127.0.0.1:8765/gateways \
  --headers "{\"Authorization\":\"Bearer $TOKEN\"}"

See runtime configuration, environment variables, and OAuth.

Current Catalogs

Do not maintain action, feature, env, or coverage inventories by hand in this README. The generated artifacts are authoritative for the current branch:

Refresh and verify them with:

just docs-generate
just docs-check

docs-check verifies generated-artifact freshness and invariants. It is not a Markdown link checker, live health check, or onboarding policy audit.

Architecture

The workspace has 11 members and uses Rust 2024, resolver 3, a single [workspace.package] version, shared [workspace.dependencies], and shared [workspace.lints] (unsafe_code = "forbid", mod_module_files = "deny", disallowed_macros = "deny"). The MCP SDK is pinned exactly as rmcp = "=3.1.0".

Shared behavior belongs in the shared execution layer. Upstream/domain logic belongs in labby-apis; reusable gateway/runtime/code-mode behavior belongs in the extracted labby-* crates; product dispatch belongs in crates/labby/src/dispatch; CLI, MCP, HTTP, and web adapters stay thin. See Architecture and Dispatch.

Development

Prefer the just aliases:

just check            # cargo check --workspace --all-features
just test             # cargo nextest run --workspace --all-features
just test-integration # cargo nextest run --workspace --all-features --run-ignored ignored-only
just lint             # skill drift + cargo wrapper smoke + clippy -D warnings + fmt check
just deny             # cargo deny check
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 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 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 install          # build-release + symlink ~/.local/bin/labby
just mcp-token        # rotate LABBY_MCP_HTTP_TOKEN in .env

Authoritative Rust verification is all-features:

cargo check --workspace --all-features
cargo clippy --workspace --all-features -- -D warnings
cargo nextest run --workspace --all-features
cargo build --workspace --all-features

CI uses the same posture and runs nextest with its CI profile. Use cargo test only for narrow local slices or when a tool specifically requires it.

Frontend changes should also run the relevant pnpm scripts under apps/gateway-admin, and just web-build when exported assets matter.

Host Gateway Runtime

The recommended self-hosted gateway runtime is the Incus system container provisioned by scripts/incus-bootstrap.sh --version vX.Y.Z and converged 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.

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 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.

Plugin Setup

The plugins/labby plugin ships skills, an MCP config, and userConfig — not a labby binary, and no Claude Code hooks. The former plugins/labby/hooks/hooks.json (SessionStart / ConfigChange shims) has been 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.

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

• soma - RMCP runtime for provider-backed MCP servers.
• unifi-rmcp - UniFi controller REST API bridge.
• tailscale-rmcp - Tailscale API bridge for devices, users, and tailnet operations.
• unraid - Unraid monorepo; the Rust GraphQL bridge (runraid) lives in unraid-rs/.
• apprise-rmcp - Apprise notification fan-out bridge for many delivery backends.
• gotify-rmcp - Gotify push notification bridge for sends, messages, apps, and clients.
• arcane-rmcp - Arcane Docker management bridge for containers and related resources.
• ytdl-rmcp - Media download and metadata workflow server.
• synapse-rmcp - Local Synapse workflow server for scout and flux actions.
• cortex - Syslog and homelab log aggregation MCP server.
• axon - RAG, crawl, scrape, extract, and semantic search project.

Documentation

Start at docs/README.md. High-value entrypoints:

• Architecture
• Configuration
• Environment
• OAuth
• Transport
• Gateway
• Setup
• Server Logs
• Testing
• Operations

License

Original Dinglebear-authored portions of this project are licensed under AGPL-3.0-only. The same file records the project-specific scope, third-party treatment, contribution policy, and availability of separately negotiated commercial terms.