labby

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

The registered services on this branch are exactly `doctor`, `fs`, `gateway`,
`lab_admin`, `server_logs`, `setup`, and `snippets`. The older
`marketplace`/`stash`/`acp`/`nodes`/`deploy`/`logs`/`device` product services
were removed by the "Slim labby gateway host" pass; their domain types survive
in `labby-runtime`/`labby-apis` but are no longer registered services and have
no CLI commands. Use the generated catalogs below for the current surface
instead of copying command or action lists by hand.

## Quick Start

### Proxy One Stdio MCP Server

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

```bash
labby setup proxy
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:

```bash
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](./docs/guides/STDIO_MCP_PROXY.md).

### Install A Release

Linux/macOS:

```bash
curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/labby/main/scripts/install.sh | 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:

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

Windows PowerShell:

```powershell
irm https://raw.githubusercontent.com/dinglebear-ai/labby/main/scripts/install.ps1 | iex
labby setup
labby serve --host 127.0.0.1 --port 8765
```

The install scripts download the requested GitHub Release asset, 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`.

Override install behavior with `LABBY_INSTALL_DIR`, `LABBY_INSTALL_VERSION`, or
`LABBY_INSTALL_REPO`.

### 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](./.mise.toml) and
  [apps/gateway-admin/package.json](./apps/gateway-admin/package.json).
- `openssl` if you want to generate a bearer token manually.

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

### 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 Lab's `env_merge` path (`0600` perms on
Unix) and then skips creating anything else until the web wizard runs.

For explicit setup:

```bash
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 24.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.

```bash
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](./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

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

### Manage Upstream MCP Gateways

```bash
labby gateway add \
  --name github \
  --url https://example.com/mcp \
  --bearer-token-env GITHUB_MCP_TOKEN \
  -y

labby gateway reload
labby gateway list
```

Stdio upstreams execute local commands when tested or reconciled, so gateway
tests and config mutations use the shared destructive-action confirmation gate.
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`.

### 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'
```

MCP call shapes:

```json
{ "code": "async () => (await codemode.search(\"github issues\")).results" }
```

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

```json
{ "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

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

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 Lab
actions. The `snippets` service is gateway-gated: it is unavailable in builds
without the `gateway` feature.

### Audit Health And Logs

```bash
labby doctor            # audit every configured service
labby doctor system     # local env vars, Docker, 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