toolhome 0.5.0

package/dist/server/upstream/oauth-service.js

@@ -0,0 +1,217 @@
+import { assertSecureTokenEndpoint, auth, } from '@modelcontextprotocol/client';
+import { z } from 'zod';
+import { AppError } from '../domain/errors.js';
+import { StoredOAuthProvider } from './oauth-provider.js';
+const beginInputSchema = z.object({
+    serverId: z.uuid().optional(),
+    force: z.boolean().default(false),
+});
+export class UpstreamOAuthService {
+    #store;
+    #publicUrl;
+    #upstreams;
+    #logger;
+    #urlClientId;
+    constructor(store, publicUrl, upstreams, logger, urlClientId = true) {
+        this.#store = store;
+        this.#publicUrl = publicUrl;
+        this.#upstreams = upstreams;
+        this.#logger = logger;
+        this.#urlClientId = urlClientId;
+    }
+    #provider(credentialId, urlClientId = this.#urlClientId) {
+        return new StoredOAuthProvider(this.#store, credentialId, this.#publicUrl, {
+            urlClientId,
+        });
+    }
+    metadata(credentialId) {
+        return this.#provider(credentialId).clientMetadata;
+    }
+    async begin(credentialId, value = {}) {
+        const input = beginInputSchema.parse(value);
+        const server = this.#serverFor(credentialId, input.serverId);
+        const provider = this.#provider(credentialId, server.settings.urlClientId ?? this.#urlClientId);
+        const payload = this.#oauthPayload(credentialId);
+        if (input.force) {
+            // A forced flow starts over: discard any previously registered client so
+            // the next authorization re-registers under the current configuration
+            // (e.g. DCR instead of URL-based client metadata).
+            provider.invalidateCredentials('client');
+        }
+        const result = await auth(provider, {
+            serverUrl: server.transport.url,
+            ...(payload.scope === undefined ? {} : { scope: payload.scope }),
+            ...(input.force ? { forceReauthorization: true } : {}),
+        });
+        if (result === 'AUTHORIZED') {
+            const connection = await this.#reload(server);
+            return {
+                status: 'authorized',
+                credential: this.#store.getCredential(credentialId),
+                serverId: server.id,
+                connection,
+            };
+        }
+        const authorizationUrl = provider.authorizationUrl();
+        if (!authorizationUrl) {
+            throw new AppError('oauth_redirect_missing', 'Authorization server did not return a redirect', 502);
+        }
+        await this.#upstreams.invalidate(server.id);
+        this.#store.appendEvent({
+            level: 'info',
+            type: 'credential.authorization_started',
+            serverId: server.id,
+            message: `Started OAuth authorization for ${server.slug}`,
+            detail: { credentialId },
+        });
+        return {
+            status: 'authorization-required',
+            credential: this.#store.getCredential(credentialId),
+            serverId: server.id,
+            authorizationUrl,
+            callbackUrl: provider.redirectUrl.toString(),
+        };
+    }
+    async callback(credentialId, input) {
+        const server = this.#serverFor(credentialId);
+        const provider = this.#provider(credentialId, server.settings.urlClientId ?? this.#urlClientId);
+        provider.validateCallbackState(input.state);
+        const payload = this.#oauthPayload(credentialId);
+        const result = await auth(provider, {
+            serverUrl: server.transport.url,
+            authorizationCode: input.code,
+            ...(input.iss === undefined ? {} : { iss: input.iss }),
+            ...(payload.scope === undefined ? {} : { scope: payload.scope }),
+        });
+        if (result !== 'AUTHORIZED') {
+            throw new AppError('oauth_exchange_incomplete', 'OAuth authorization did not complete', 502);
+        }
+        const connection = await this.#reload(server);
+        this.#store.appendEvent({
+            level: 'info',
+            type: 'credential.authorized',
+            serverId: server.id,
+            message: `Authorized ${server.slug}`,
+            detail: { credentialId },
+        });
+        return {
+            status: 'authorized',
+            server,
+            credential: this.#store.getCredential(credentialId),
+            connection,
+        };
+    }
+    async revoke(credentialId) {
+        const server = this.#serverFor(credentialId);
+        const provider = this.#provider(credentialId, server.settings.urlClientId ?? this.#urlClientId);
+        const payload = this.#oauthPayload(credentialId);
+        const metadata = payload.discoveryState?.authorizationServerMetadata;
+        const endpointValue = metadata ? Reflect.get(metadata, 'revocation_endpoint') : undefined;
+        const endpoint = typeof endpointValue === 'string' ? endpointValue : undefined;
+        const clientInformation = provider.clientInformation();
+        const attempts = [];
+        if (endpoint) {
+            assertSecureTokenEndpoint(endpoint);
+            if (payload.refreshToken) {
+                attempts.push(await this.#revokeToken(endpoint, payload.refreshToken, 'refresh_token', clientInformation));
+            }
+            if (payload.accessToken) {
+                attempts.push(await this.#revokeToken(endpoint, payload.accessToken, 'access_token', clientInformation));
+            }
+        }
+        provider.invalidateCredentials('tokens');
+        provider.invalidateCredentials('verifier');
+        await this.#upstreams.invalidate(server.id);
+        this.#store.appendEvent({
+            level: attempts.some((attempt) => !attempt.ok) ? 'warn' : 'info',
+            type: 'credential.revoked',
+            serverId: server.id,
+            message: `Revoked OAuth credential for ${server.slug}`,
+            detail: { credentialId, remoteRevocationSupported: endpoint !== undefined, attempts },
+        });
+        return {
+            revoked: true,
+            remoteRevocationSupported: endpoint !== undefined,
+            remoteRevoked: attempts.length > 0 && attempts.every((attempt) => attempt.ok),
+            attempts,
+            credential: this.#store.getCredential(credentialId),
+        };
+    }
+    async #revokeToken(endpoint, token, tokenType, clientInformation) {
+        const body = new URLSearchParams({ token, token_type_hint: tokenType });
+        const headers = new Headers({ 'content-type': 'application/x-www-form-urlencoded' });
+        if (clientInformation?.client_secret) {
+            const user = formEncode(clientInformation.client_id);
+            const password = formEncode(clientInformation.client_secret);
+            headers.set('authorization', `Basic ${Buffer.from(`${user}:${password}`).toString('base64')}`);
+        }
+        else if (clientInformation) {
+            body.set('client_id', clientInformation.client_id);
+        }
+        try {
+            const response = await fetch(endpoint, {
+                method: 'POST',
+                headers,
+                body,
+                redirect: 'error',
+                signal: AbortSignal.timeout(10_000),
+            });
+            return { tokenType, ok: response.ok, status: response.status };
+        }
+        catch (error) {
+            this.#logger.warn('Remote OAuth token revocation failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return { tokenType, ok: false };
+        }
+    }
+    #serverFor(credentialId, serverId) {
+        const candidates = this.#store
+            .listServers()
+            .filter((server) => server.credentialId === credentialId);
+        const server = serverId
+            ? candidates.find((candidate) => candidate.id === serverId)
+            : candidates.length === 1
+                ? candidates[0]
+                : undefined;
+        if (!server) {
+            throw new AppError('oauth_server_required', candidates.length === 0
+                ? 'Attach the OAuth credential to a remote MCP server first'
+                : 'OAuth credential must be attached to exactly one remote MCP server', 400);
+        }
+        if (server.transport.type !== 'streamable-http') {
+            throw new AppError('oauth_remote_only', 'OAuth is only available for remote MCP servers', 400);
+        }
+        return { ...server, transport: server.transport };
+    }
+    #oauthPayload(credentialId) {
+        const payload = this.#store.getCredentialPayload(credentialId);
+        if (!payload || payload.type !== 'oauth') {
+            throw new AppError('oauth_credential_invalid', 'Credential is not OAuth', 400);
+        }
+        return payload;
+    }
+    async #reload(server) {
+        await this.#upstreams.remove(server.id);
+        if (!server.enabled)
+            return { refreshed: false, reason: 'server-disabled' };
+        try {
+            await this.#upstreams.refresh(server.id);
+            return { refreshed: true };
+        }
+        catch (error) {
+            this.#logger.warn('OAuth completed but the upstream MCP refresh failed', {
+                serverId: server.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return {
+                refreshed: false,
+                reason: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+}
+function formEncode(value) {
+    return new URLSearchParams({ value }).toString().slice('value='.length);
+}
+//# sourceMappingURL=oauth-service.js.map

package/dist/server/upstream/oauth-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-service.js","sourceRoot":"","sources":["../../../src/upstream/oauth-service.ts"],"names":[],"mappings":"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"}

package/dist/server/upstream/stable-json.d.ts

@@ -0,0 +1,3 @@
+export declare function stableJson(value: unknown): string;
+export declare function fingerprint(value: unknown): string;
+//# sourceMappingURL=stable-json.d.ts.map

package/dist/server/upstream/stable-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-json.d.ts","sourceRoot":"","sources":["../../../src/upstream/stable-json.ts"],"names":[],"mappings":"AAYA,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEjD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAElD"}

package/dist/server/upstream/stable-json.js

@@ -0,0 +1,17 @@
+import { createHash } from 'node:crypto';
+function normalize(value) {
+    if (Array.isArray(value))
+        return value.map(normalize);
+    if (value === null || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, normalize(item)]));
+}
+export function stableJson(value) {
+    return JSON.stringify(normalize(value));
+}
+export function fingerprint(value) {
+    return createHash('sha256').update(stableJson(value)).digest('hex');
+}
+//# sourceMappingURL=stable-json.js.map

package/dist/server/upstream/stable-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-json.js","sourceRoot":"","sources":["../../../src/upstream/stable-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SAClB,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;SACpD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAChD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "toolhome",
+  "version": "0.5.0",
+  "description": "Self-hosted home for remote-native and home-hosted MCP servers and CLIs.",
+  "type": "module",
+  "bin": {
+    "toolhome": "./dist/server/cli/main.js",
+    "mcp-home": "./dist/server/cli/main.js"
+  },
+  "files": [
+    "dist",
+    "skills/toolhome"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "gateway",
+    "proxy",
+    "oauth",
+    "cli",
+    "self-hosted"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "allowScripts": {
+    "esbuild@0.28.2": true,
+    "fsevents": false
+  },
+  "scripts": {
+    "build": "npm run build:server && npm run build:web",
+    "build:server": "tsc -p tsconfig.build.json",
+    "build:web": "npm --prefix web run build",
+    "dev:web": "npm --prefix web run dev",
+    "prepublishOnly": "npm run build:server",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "dev": "tsx watch src/main.ts",
+    "start": "node dist/server/main.js",
+    "cli": "tsx src/cli/main.ts",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run --config vitest.config.ts",
+    "test:unit": "vitest run --config vitest.config.ts tests/unit",
+    "test:integration": "vitest run --config vitest.config.ts tests/integration",
+    "test:real": "tsx scripts/real-environment.ts",
+    "test:all": "npm run format:check && npm run build && npm run test && npm run test:real",
+    "smoke:market": "tsx scripts/smoke-market.ts"
+  },
+  "dependencies": {
+    "@hono/node-server": "2.1.0",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/core": "2.0.0",
+    "@modelcontextprotocol/hono": "2.0.0",
+    "@modelcontextprotocol/server": "2.0.0",
+    "commander": "15.0.0",
+    "hono": "4.13.1",
+    "jose": "6.2.8",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "26.2.0",
+    "prettier": "3.9.6",
+    "tsx": "4.23.11",
+    "typescript": "7.0.2",
+    "vite": "8.2.1",
+    "vitest": "4.1.10"
+  }
+}

package/skills/toolhome/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: toolhome
+description: >
+  Deploy and manage a self-hosted ToolHome instance: an MCP and Hosted CLI
+  control plane that aggregates upstream capabilities and platform CLIs. Use
+  when the user wants to set up ToolHome, manage MCP servers or hosted CLIs,
+  reuse encrypted credentials, authorize OAuth upstreams, install from the
+  Market catalog, configure harnesses (Claude Code, Cursor, Codex, Grok), or
+  troubleshoot ToolHome. Covers CLI, web console, Docker deployment, and CI/CD.
+---
+
+# ToolHome
+
+ToolHome is a single-user, self-hosted control plane for MCP servers and Hosted platform CLIs. Manage upstream MCP servers, CLIs such as Azure `az`, GitHub `gh`, and Tailscale, and encrypted credentials in one place.
+
+## When to Use This Skill
+
+- User wants to deploy or manage the MCP or Hosted CLI plane
+- User wants to aggregate multiple MCP servers behind one URL
+- User wants to run platform CLIs such as Azure `az`, GitHub `gh`, Tailscale, Cloudflare `wrangler`, Vercel, Lark `lark-cli`, Firecrawl, or Aliyun `aliyun` remotely
+- User needs to authorize OAuth for MCP upstreams or reuse access tokens in a CLI
+- User wants to install MCP servers or hosted CLIs from the Market catalog
+- User wants to connect Claude Code, Cursor, Codex, or Grok to a self-hosted MCP gateway
+- User is troubleshooting ToolHome (status, OAuth, connectivity)
+
+## Installation
+
+ToolHome has three components. Install what you need:
+
+### 1. Deploy the server (Docker)
+
+```bash
+docker run -d \
+  --name toolhome \
+  -p 3344:3344 \
+  -v toolhome-data:/data \
+  -e TOOLHOME_MASTER_KEY="$(openssl rand -base64 48)" \
+  -e TOOLHOME_BOOTSTRAP_CONTROL_KEY="tch_ctl_$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')" \
+  -e TOOLHOME_PUBLIC_URL="https://tool.cyncyn.xyz" \
+  ghcr.io/crayonlu/toolhome:latest
+```
+
+Or with Docker Compose (see `references/deployment.md`). After startup, open the web console at `TOOLHOME_PUBLIC_URL` and sign in with the bootstrap Control Key.
+
+### 2. Install the CLI (npm)
+
+```bash
+npm install -g toolhome
+toolhome auth login --url https://tool.cyncyn.xyz --control-key "$TOOLHOME_CONTROL_KEY"
+```
+
+The CLI manages MCP servers and hosted CLIs as equal planes, plus shared credentials, OAuth, Market, and diagnostics. It requires Node.js 24 or later. The npm package also includes this skill under `skills/toolhome`.
+
+### 3. Install this skill (for AI agents)
+
+```bash
+npx skills add crayonlu/toolhome -g -y
+```
+
+Teaches the agent all CLI commands, OAuth flows, Market installation, and troubleshooting.
+
+## CLI Quick Reference
+
+```bash
+toolhome status                         # overview
+toolhome doctor                         # health check
+toolhome server list                    # list servers
+toolhome server add ./server.json       # add a server
+toolhome cli list                      # list hosted CLIs
+toolhome cli add ./cli.json             # register a hosted CLI
+toolhome cli status gh-cli              # probe a hosted CLI
+toolhome cli exec gh-cli -- --version   # run remotely, stream output
+toolhome credential list                # list credentials
+toolhome credential authorize <name>    # OAuth authorization (opens browser, waits)
+toolhome access-key create laptop       # create an MCP Access Key for harnesses
+toolhome endpoint aggregate             # show the aggregate endpoint URL
+toolhome market list                    # browse the Market catalog
+toolhome market install resend         # supply the secret at the one-time browser URL
+toolhome calls list --limit 10                              # recent tool calls
+toolhome calls stats                                        # call statistics
+```
+
+## Common Workflows
+
+### Deploy ToolHome
+
+1. Generate two random keys (master + bootstrap control, each 32+ chars)
+2. Start the Docker container with the keys and public URL
+3. Open the web console, sign in with the bootstrap key
+4. Create a new Control Key, revoke bootstrap
+5. Run `toolhome doctor` to verify health
+
+### Add an Upstream Server
+
+1. Create a credential:
+   ```bash
+   echo '{"name":"firecrawl","payload":{"type":"bearer","token":"fc-xxx"}}' | toolhome credential add -
+   ```
+2. Get the credential ID from `toolhome credential list`
+3. Create a server:
+   ```bash
+   echo '{"slug":"firecrawl","name":"Firecrawl","kind":"remote","transport":{"type":"streamable-http","url":"https://mcp.firecrawl.dev/v2/mcp"},"credentialId":"<id>","enabled":true}' | toolhome server add -
+   ```
+4. Verify: `toolhome doctor`
+
+### Install and Run a Hosted CLI
+
+```bash
+toolhome market install gh-cli
+toolhome cli status gh-cli
+toolhome cli exec gh-cli -- --version
+toolhome cli exec gh-cli --stdin $'\n' -- auth login --hostname github.com --git-protocol https --web
+toolhome cli exec gh-cli -- auth status
+toolhome cli exec gh-cli -- repo view crayonlu/toolhome
+```
+
+Give the user the device code and authorization URL for browser confirmation. Run the platform CLI only on the ToolHome server; the client needs only `toolhome`. Put platform arguments after `--`. Registry commands take the record ID; `exec` and `status` take its slug. Use `toolhome cli get <id>` to inspect allowed commands before execution. `host` runs installed binaries and `docker` runs sibling containers with explicit state volumes. Read `references/market-guide.md` for supported products and deployment prerequisites, and `references/cli-reference.md` for registry, stdin, timeout, and streaming options.
+
+### Authorize OAuth Upstream
+
+```bash
+toolhome credential authorize cloudflare
+```
+
+This resolves the credential by name, opens the browser, and waits until authorization succeeds, fails, or times out (default 600s). For force re-authorization:
+
+```bash
+toolhome credential authorize cloudflare --force
+```
+
+If OAuth fails with "Invalid client" or "Incompatible auth server", switch the registration method per-server:
+
+- URL-based (default): works for most providers
+- DCR: needed for Cloudflare, Notion, Linear (set `urlClientId: false` in server settings)
+
+See `references/oauth-guide.md` for per-provider compatibility.
+
+### Install from Market
+
+```bash
+toolhome market list                                    # browse MCP and CLI entries
+toolhome market install resend                          # home-stdio (npm); browser secret
+toolhome market install context7                        # remote (bearer); browser secret
+toolhome market install deepwiki                        # remote (no auth)
+toolhome market install fetch                           # uvx (Python, no config)
+toolhome market install markitdown                       # Docker-backed MCP
+toolhome market install gh-cli                             # Hosted GitHub CLI (no token; device-flow login after)
+toolhome market uninstall resend                        # remove
+```
+
+Market installs are async with progress: the CLI shows installer steps, the web console shows a live log. Packaged artifacts have version pins and installs write a persistent record (source, version, recipe revision). Remote services and the existing `/bin/sh` host-shell entry have no downloadable version pin. If required secrets are omitted, the CLI prints a one-time browser action URL. Use that flow for secrets; `--set` also accepts values, so reserve it for non-secret configuration.
+
+**Docker entries** (e.g. `markitdown`) run the image as a sibling container via `docker run --rm -i <image>`: the install pulls the image, or builds it from the entry's inline Dockerfile when not pullable. The gateway container must mount the host docker socket and its runtime user must be in the host docker group (compose `group_add`, default GID 999, override with `DOCKER_GROUP_ID`). Only needed when a package cannot run inside the Alpine gateway image (e.g. `markitdown` — its `onnxruntime` dependency ships no musl wheels).
+
+### Give an AI Agent Safe Management Access
+
+Create an **agent-scoped control key** (web console → Settings → Control Keys, or API):
+
+```bash
+echo '{"name":"agent-key","scope":"agent"}' | toolhome api POST /api/v1/control-keys --body -
+```
+
+Agent keys can read state and run safe operations (enable/disable/refresh/restart, market install, tool visibility) but are denied credentials, control/access keys, secret exports, and server deletion (HTTP 403). Existing keys keep full admin scope.
+
+Point an agent's management MCP at:
+
+```json
+{
+  "url": "https://tool.cyncyn.xyz/manage/mcp",
+  "headers": { "Authorization": "Bearer tch_ctl_agent..." }
+}
+```
+
+The management surface exposes `home_status`, `server_list`, `server_get`, `market_search`, `tool_list`, `calls_query`, and idempotent writes `server_set_enabled`, `server_refresh`, `server_restart`, `market_install`, `tool_set_visibility`. All writes are audited in the call log. The management endpoint never appears inside the `/mcp` aggregate.
+
+### Connect a Harness
+
+Create an MCP Access Key:
+
+```bash
+toolhome access-key create laptop
+# Returns: tch_mcp_xxx (shown once, copy it)
+```
+
+Configure the harness (aggregate endpoint):
+
+```json
+{
+  "url": "https://tool.cyncyn.xyz/mcp",
+  "headers": { "Authorization": "Bearer tch_mcp_xxx" }
+}
+```
+
+Or per-server (independent endpoint, original tool names):
+
+```json
+{
+  "url": "https://tool.cyncyn.xyz/mcp/firecrawl",
+  "headers": { "Authorization": "Bearer tch_mcp_xxx" }
+}
+```
+
+Aggregate tool names are `{server_slug}.{tool_name}`. Per-server preserves original names.
+
+### Diagnose Issues
+
+```bash
+toolhome doctor              # check all servers
+toolhome server status <id>  # detailed runtime state + last error
+toolhome server logs <id>    # recent log entries
+toolhome cli status <slug>  # hosted CLI probe
+toolhome events --limit 100 # recent events, including cli.exec
+```
+
+## Configuration
+
+| Env                               | Description                                        | Default                        |
+| --------------------------------- | -------------------------------------------------- | ------------------------------ |
+| `TOOLHOME_PUBLIC_URL`             | External HTTPS origin                              | required                       |
+| `TOOLHOME_MASTER_KEY`             | Secret encryption key (32+ chars)                  | required                       |
+| `TOOLHOME_BOOTSTRAP_CONTROL_KEY`  | First-boot Control Key                             | required on first boot         |
+| `TOOLHOME_HOST` / `TOOLHOME_PORT` | Listen address                                     | `127.0.0.1:3344`               |
+| `TOOLHOME_DATA_DIR`               | SQLite + market data                               | `/data`                        |
+| `TOOLHOME_MARKET_DIR`             | Market npm install dir                             | `<dataDir>/market`             |
+| `TOOLHOME_WEB_DIR`                | Web console static files                           | disabled (set in Docker image) |
+| `TOOLHOME_OAUTH_URL_CLIENT_ID`    | Global OAuth client registration                   | `true` (URL-based)             |
+| `TOOLHOME_UV_INDEX_URL`           | PyPI mirror for uvx Market installs                | unset (pypi.org)               |
+| `TOOLHOME_CALLS_RETENTION_DAYS`   | Tool call record retention in days (metadata only) | `30`                           |
+
+## Deep Dives
+
+For detailed information, read the reference files:
+
+- `references/cli-reference.md` — Full CLI command reference with all flags
+- `references/oauth-guide.md` — OAuth registration methods, per-provider compatibility, troubleshooting
+- `references/market-guide.md` — Market catalog entries, installation details
+- `references/deployment.md` — Docker Compose, CI/CD, reverse proxy, data persistence
+- `references/troubleshooting.md` — Common issues and solutions