From 7bd2f9e43cd2c0db06aae8ba8b21577ec16514de Mon Sep 17 00:00:00 2001 From: Peter Chanthamynavong Date: Sun, 4 Oct 2026 14:47:08 -0700 Subject: [PATCH] docs(daemon): describe daemon.http_addr and install-service PATH capture The docs still said the daemon serves HTTP only with --http-addr, and the install-service section listed only the XDG variables it captures. - server.md, cli.md: the address can also come from GORTEX_DAEMON_HTTP_ADDR or daemon.http_addr, with flag > env > config precedence, read at startup. - onboarding.md: install-service captures the installing shell's PATH, and the unit runs a bare `daemon start`, so daemon options belong in config. - server.md, onboarding.md: name the global config path, including $XDG_CONFIG_HOME/gortex/config.yaml when that variable is absolute. - multi-repo.md: a commented daemon.http_addr example in the sample config. --- docs/cli.md | 2 +- docs/multi-repo.md | 3 +++ docs/onboarding.md | 2 ++ docs/server.md | 7 ++++++- 4 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index c37814a64..a30687275 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -6,7 +6,7 @@ gortex init [path] Per-repo setup (.mcp.json, hooks, community routing gortex init --dry-run-intake Emit a privacy-safe intake manifest and exit before parsing/writes gortex doctor Zero-op state report: adapter drift, hook activity, adoption, savings (human or --json) gortex mcp [flags] Start the MCP stdio proxy (connects to or auto-starts the daemon; embedded fallback requires config opt-in; --server adds HTTP API) -gortex daemon start [flags] Start the daemon; --http-addr serves the HTTP/JSON API under /v1/* plus the MCP /mcp transport (--http-auth-token, --cors-origin) +gortex daemon start [flags] Start the daemon; --http-addr (or daemon.http_addr in config) serves the HTTP/JSON API under /v1/* plus the MCP /mcp transport (--http-auth-token, --cors-origin) gortex daemon start / stop / restart / reload / status / logs / install-service / service-status / uninstall-service / server (multi-server roster) gortex eval Retrieval + coverage benchmarks — recall / embedders / pack / swebench / stdbench / tokens / baselines / quality / parity (substrate; prefer `gortex bench` for the user-facing surface). `parity` measures per-language cross-file coverage against the committed baseline gortex eval-server [flags] HTTP server used by the swebench harness diff --git a/docs/multi-repo.md b/docs/multi-repo.md index b81f7d860..36df8495f 100644 --- a/docs/multi-repo.md +++ b/docs/multi-repo.md @@ -42,6 +42,9 @@ active_project: my-saas mcp: allow_embedded: false # Require the shared daemon (default) +# daemon: +# http_addr: 127.0.0.1:7411 # Opt in to /mcp + /v1 over HTTP (unset: socket only) + exclude: # Applies to every tracked repo - "**/*.generated.*" - "node_modules/" # Already in the builtin baseline diff --git a/docs/onboarding.md b/docs/onboarding.md index 49b692011..ac0e98297 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -238,6 +238,8 @@ On macOS the unit lands at `~/Library/LaunchAgents/com.zzet.gortex.plist`; on Li If you run an XDG layout (any absolute `XDG_CONFIG_HOME` / `XDG_DATA_HOME` / `XDG_CACHE_HOME`), `install-service` captures those values into the unit so the supervised daemon resolves the same paths as your shell — service supervisors otherwise start with a near-empty environment and the daemon would fall back to `~/.gortex`. Re-run `install-service` if you later change where those variables point. +`install-service` also captures the installing shell's `PATH` (absolute entries only), so the supervised daemon finds language servers installed outside the system directories, such as `~/go/bin` or `~/.cargo/bin`. Run it from the shell whose `PATH` you want the daemon to use, and re-run it after that `PATH` changes. The unit always runs a bare `gortex daemon start`, so set daemon options in config rather than as flags: for the HTTP surface, put `daemon.http_addr` in the global config, `~/.gortex/config.yaml` or its XDG location (see [server.md](server.md)). + ### How it works - `gortex mcp` (what Claude Code spawns via `.mcp.json`) connects to and may auto-start the daemon, then acts as a thin stdio ↔ socket proxy (~5 MB per client). If no compatible daemon can be reached, it exits by default with instructions to start one or enable `mcp.allow_embedded` in the user-level config. diff --git a/docs/server.md b/docs/server.md index 1dd6410e1..831ad3e95 100644 --- a/docs/server.md +++ b/docs/server.md @@ -8,7 +8,7 @@ Gortex exposes three transports — stdio MCP (the default `gortex mcp`), a Unix ## Server mode (`/v1/*` JSON API) -The daemon exposes all MCP tools as an HTTP/JSON API under versioned `/v1/*` routes once you give it an HTTP address with `--http-addr`. The daemon serves the repos you track, so add the repo first, then bring the HTTP surface up: +The daemon exposes all MCP tools as an HTTP/JSON API under versioned `/v1/*` routes once you give it an HTTP address: the `--http-addr` flag, the `GORTEX_DAEMON_HTTP_ADDR` env var, or `daemon.http_addr` in the global config (`~/.gortex/config.yaml`, or `$XDG_CONFIG_HOME/gortex/config.yaml` when `XDG_CONFIG_HOME` is an absolute path), in that order of precedence. The address is read at startup. A daemon run by `gortex daemon install-service` starts without flags, so use the config key there. The daemon serves the repos you track, so add the repo first, then bring the HTTP surface up: ```bash # Track the repo (or run from inside it — the cwd's repo auto-tracks), then start the HTTP backend @@ -18,6 +18,11 @@ gortex daemon start --http-addr 127.0.0.1:7411 # Non-localhost bind requires an auth token gortex daemon start --http-addr 0.0.0.0:7411 --http-auth-token "$(openssl rand -hex 32)" +# Or keep the address in config, e.g. for the install-service daemon: +# ~/.gortex/config.yaml (or $XDG_CONFIG_HOME/gortex/config.yaml) +# daemon: +# http_addr: 127.0.0.1:7411 + # Optional one-shot HTTP API alongside MCP stdio; first enable # mcp.allow_embedded in the user-level config. gortex mcp --index /path/to/repo --server --port 8765