feat(version): check for a newer release once a day

.env.template

@@ -87,6 +87,23 @@
 # (calls are team-gated by xAI), and Azure OpenAI (GA v1 surface).
 # REALTIME_ENABLED=true
 
+# Version awareness: check https://gomodel.enterpilot.io/version once a day, and
+# again the first time each browser opens the dashboard on a new day, so operators
+# learn that a newer release exists. The dashboard shows the result in Settings;
+# GET /version returns it as JSON.
+#
+# The check sends the running version, the distribution name (GoModel or GoModel
+# Pro), and a random per-deployment install id.
+#
+# It never sends API keys, provider credentials, model names, prompts, responses,
+# usage or cost data, client addresses, or the hostname the dashboard is served on.
+#
+# Set to false to stop all outbound traffic from this subsystem: no timer, no
+# request, no install id written to disk. /version still reports the local build.
+# GOMODEL_VERSION_CHECK_ENABLED=true
+# Point at an internal mirror serving core.txt / pro.txt for air-gapped networks.
+# GOMODEL_VERSION_CHECK_URL=https://gomodel.enterpilot.io/version
+
 # MCP gateway: aggregate upstream MCP (Model Context Protocol) servers behind the
 # authenticated /mcp endpoint (default: true; a no-op until servers are declared here,
 # in config.yaml under `mcp.servers`, or in the dashboard). Tools are namespaced as

.github/workflows/release.yml

@@ -204,6 +204,28 @@ jobs:
             -d "deploy ${GITHUB_REF_NAME}" \
             https://demo.enterpilot.io/hooks/update-demo
 
+  publish-version-manifest:
+    name: Publish version manifest
+    runs-on: ubuntu-latest
+    # Runs after the GitHub release exists: the website regenerates
+    # public/version/core.txt from the latest release, so dispatching earlier
+    # would republish the previous version.
+    needs: github-release
+    # Prereleases (v1.2.3-rc1) are not "latest" on GitHub, so the website
+    # would regenerate the same manifest it already serves.
+    if: ${{ !contains(github.ref_name, '-') }}
+    # Best-effort: running gateways keep working on a stale manifest, and the
+    # website's nightly deploy regenerates it anyway.
+    continue-on-error: true
+    steps:
+      - name: Dispatch website deploy
+        env:
+          GH_TOKEN: ${{ secrets.WEBSITE_DISPATCH_TOKEN }}
+        run: |
+          gh api repos/ENTERPILOT/gomodel.enterpilot.io/dispatches \
+            -f event_type=gomodel-release \
+            -f "client_payload[version]=${GITHUB_REF_NAME#v}"
+
   publish-mcp:
     name: Publish to MCP Registry
     runs-on: ubuntu-latest

config/config.example.yaml

@@ -612,3 +612,12 @@ providers:
 # extensions:
 #   example:
 #     enabled: true
+
+# Version awareness. Checks https://gomodel.enterpilot.io/version once a day —
+# and again on the first dashboard visit of each day — so operators learn that a
+# newer release exists. Sends the running version, the distribution name, a random
+# per-deployment install id, and the visiting browser's user agent and language.
+# Never sends API keys, model names, prompts, usage data, client addresses, or
+# the dashboard hostname. Set enabled: false to stop all outbound traffic.
+# version_check:
+#   enabled: true

config/config.go

@@ -39,6 +39,10 @@ type Config struct {
 	Session    SessionConfig    `yaml:"session"`
 	MCP        MCPConfig        `yaml:"mcp"`
 
+	// VersionCheck controls the daily update check against the public
+	// release manifest. See VersionCheckConfig for what it sends.
+	VersionCheck VersionCheckConfig `yaml:"version_check"`
+
 	// Extensions holds configuration owned by custom distributions. Core keeps
 	// the values opaque; an extension decodes its named section with
 	// LoadResult.DecodeExtension.
@@ -194,6 +198,13 @@ func buildDefaultConfig() *Config {
 		MCP: MCPConfig{
 			Enabled: true,
 		},
+		VersionCheck: VersionCheckConfig{
+			Enabled:        true,
+			URL:            DefaultVersionCheckURL,
+			IntervalHours:  24,
+			TimeoutSeconds: 5,
+			MaxDailyChecks: 500,
+		},
 	}
 }
 

config/versioncheck.go

@@ -0,0 +1,41 @@
+package config
+
+import "github.com/enterpilot/gomodel/internal/versioncheck"
+
+// VersionCheckConfig controls the daily update check against the GoModel
+// release manifest.
+//
+// The check sends the running version, the distribution name, and an
+// anonymous install identifier. It never sends API keys, provider
+// credentials, model names, prompts, usage data, client addresses, or the
+// hostname the gateway is served on. Set Enabled to false to stop all
+// outbound traffic from this subsystem.
+type VersionCheckConfig struct {
+	// Enabled turns the daily update check on.
+	// Default: true
+	Enabled bool `yaml:"enabled" env:"GOMODEL_VERSION_CHECK_ENABLED"`
+
+	// URL is the base URL of the version manifest. The channel file
+	// ("core.txt" or "pro.txt") is appended to it.
+	// Default: https://gomodel.enterpilot.io/version
+	URL string `yaml:"url" env:"GOMODEL_VERSION_CHECK_URL"`
+
+	// IntervalHours is how often the background check runs. Each run is
+	// jittered so gateways started together do not query in lockstep.
+	// Default: 24
+	IntervalHours int `yaml:"interval_hours" env:"GOMODEL_VERSION_CHECK_INTERVAL_HOURS"`
+
+	// TimeoutSeconds bounds a single manifest request.
+	// Default: 5
+	TimeoutSeconds int `yaml:"timeout_seconds" env:"GOMODEL_VERSION_CHECK_TIMEOUT_SECONDS"`
+
+	// MaxDailyChecks caps how many manifest requests this gateway makes per
+	// day in total, so a hostile client cycling cookies cannot turn /version
+	// into an outbound request amplifier.
+	// Default: 500
+	MaxDailyChecks int `yaml:"max_daily_checks" env:"GOMODEL_VERSION_CHECK_MAX_DAILY"`
+}
+
+// DefaultVersionCheckURL is the public release manifest served by the GoModel
+// website. "/core.txt" or "/pro.txt" is appended per distribution.
+const DefaultVersionCheckURL = versioncheck.DefaultURL

docs/advanced/version-awareness.mdx

@@ -0,0 +1,152 @@
+---
+title: "Version Awareness"
+description: "How GoModel checks for a newer release, exactly what the check sends, and how to turn it off."
+icon: "arrow-up-circle"
+keywords: ["version", "update", "upgrade", "telemetry", "privacy", "air-gapped"]
+---
+
+GoModel checks once a day whether a newer release exists, so you find out about
+an upgrade without watching the repository. The result appears at the top of the
+dashboard's **Settings** page and is available as JSON from `GET /version`.
+
+## Why we ask for this
+
+We use it to see how many deployments are running which version of GoModel.
+
+That matters most when a vulnerability is found. It tells us how many people are
+affected and how many are still on a release that needs patching, so we know how
+urgently to push a fix and how loudly to warn. Without it we would be guessing.
+
+**We recommend leaving it on.** It sends no API keys, no prompts, no model names
+and no usage data — see [What the check sends](#what-the-check-sends) for the
+exact list, and turn it off with one environment variable if you prefer.
+
+If you have any concerns about this data, please tell us: open an issue on
+[GitHub](https://github.com/ENTERPILOT/GoModel/issues) or find us on
+[Discord](https://discord.gg/gaEB9BQSPH). For anything security-sensitive, use
+the contact in [SECURITY.md](https://github.com/ENTERPILOT/GoModel/blob/main/SECURITY.md).
+
+The check reads one plain-text file:
+
+| Distribution | URL                              | Contents    |
+| ------------ | -------------------------------- | ----------- |
+| GoModel      | `(thiswebsite)/version/core.txt` | `X.Y.Z`     |
+| GoModel Pro  | `(thiswebsite)/version/pro.txt`  | `X.Y.Z-pro` |
+
+## When it runs
+
+Two triggers, both throttled:
+
+- **A daily timer**, so a headless gateway nobody opens a dashboard on still
+  notices releases. The first check waits a random few minutes after startup and
+  the interval carries ±10% jitter, so a fleet restarted together does not check
+  in lockstep.
+- **The first dashboard visit of each day**, per browser. A cookie named
+  `gomodel_version_check` holds `YYYY-MM-DD-{id}` — the day this browser last
+  checked plus a random id minted on its first visit. On every page load after
+  the first one each day, the dashboard reads that date and makes no request at
+  all.
+
+A failed or unreachable check is never an error. The gateway serves its cached
+result and tries again later.
+
+## What the check sends
+
+<Note>
+  Nothing about your traffic is ever sent: no model names, no provider names, no
+  prompts or responses, no usage or cost data, no user paths.
+</Note>
+
+Every check carries:
+
+| Header              | Example     | Meaning                             |
+| ------------------- | ----------- | ----------------------------------- |
+| `X-GoModel-Version` | `0.1.81`    | the release you are running         |
+| `X-GoModel-App`     | `GoModel`   | `GoModel` or `GoModel Pro`          |
+| `X-GoModel-Install` | a UUID      | random per-deployment id, see below |
+| `X-GoModel-Source`  | `scheduled` | `scheduled` or `dashboard`          |
+
+A check triggered by a dashboard visit also forwards an **allowlisted** slice of
+that visit: the browser's `User-Agent`, `Accept-Language`, `Sec-CH-UA*` client
+hints, and the visit cookie value (`X-GoModel-Date`).
+
+Because it is an allowlist, anything not on it is dropped — including `Cookie`,
+`Authorization`, `X-API-Key`, and `Referer`. A dashboard session credential or
+master key cannot leave your deployment through this path.
+
+Two things are withheld on purpose: **the hostname your dashboard is served on**,
+which would identify your organization, and **client IP addresses**, which are
+personal data. Neither is ever sent.
+
+### The install identifier
+
+A random UUID stored in `install-id` in the gateway's data directory, created on
+first use. It encodes nothing about your host, your organization, or your
+configuration; it exists only so repeated checks from one deployment count as
+one deployment. Disabling the check means it is never created.
+
+## Turning it off if you don't want to get the updates
+
+```bash
+GOMODEL_VERSION_CHECK_ENABLED=false
+```
+
+This stops everything: no timer, no outbound request, no install id on disk.
+`GET /version` still reports your local build with `"enabled": false`, and the
+dashboard simply shows no update notice.
+
+## Air-gapped and mirrored deployments
+
+Point the check at your own host and serve `core.txt` (or `pro.txt`) from it:
+
+```bash
+GOMODEL_VERSION_CHECK_URL=https://releases.internal.example.com/version
+```
+
+The gateway appends `/core.txt` or `/pro.txt` based on its distribution, and
+expects a bare version string with no leading `v`.
+
+## Configuration
+
+| Setting                           | Environment variable                      | Default                                 |
+| --------------------------------- | ----------------------------------------- | --------------------------------------- |
+| `version_check.enabled`           | `GOMODEL_VERSION_CHECK_ENABLED`           | `true`                                  |
+| `version_check.url`               | `GOMODEL_VERSION_CHECK_URL`               | `https://gomodel.enterpilot.io/version` |
+| `version_check.interval_hours`    | `GOMODEL_VERSION_CHECK_INTERVAL_HOURS`    | `24`                                    |
+| `version_check.timeout_seconds`   | `GOMODEL_VERSION_CHECK_TIMEOUT_SECONDS`   | `5`                                     |
+| `version_check.max_daily_checks`  | `GOMODEL_VERSION_CHECK_MAX_DAILY`         | `500`                                   |
+
+`max_daily_checks` caps the gateway's total outbound checks per day, so
+`/version` cannot be used as an outbound request amplifier.
+
+```yaml config.yaml
+version_check:
+  enabled: true
+  interval_hours: 24
+```
+
+## The `/version` endpoint
+
+Public and unauthenticated, alongside `/health`. It answers from the cache and
+never blocks on the network — a due check runs in the background, so an
+unreachable release host never slows the dashboard down:
+
+```bash
+curl -s http://localhost:8080/version
+```
+
+```json
+{
+  "app": "GoModel",
+  "version": "0.1.81",
+  "latest": "0.1.82",
+  "update_available": true,
+  "checked_at": "2026-08-26T09:12:44Z",
+  "enabled": true
+}
+```
+
+`update_available` is conservative: build metadata is ignored, prereleases are
+compared the way semantic versioning specifies (`1.0.0-rc1` < `1.0.0-rc2` <
+`1.0.0`), and a development build (`dev`, a bare commit) never reports an
+update.

docs/docs.json

@@ -119,6 +119,7 @@
                             "advanced/cli",
                             "advanced/api-endpoints",
                             "advanced/resilience",
+                            "advanced/version-awareness",
                             "advanced/responses-api",
                             "advanced/responses-compatibility",
                             "advanced/conversations-api",

internal/app/app.go

@@ -46,6 +46,7 @@ import (
 	"github.com/enterpilot/gomodel/internal/storage"
 	"github.com/enterpilot/gomodel/internal/tagging"
 	"github.com/enterpilot/gomodel/internal/usage"
+	"github.com/enterpilot/gomodel/internal/versioncheck"
 	"github.com/enterpilot/gomodel/internal/virtualmodels"
 	"github.com/enterpilot/gomodel/internal/workflows"
 )
@@ -76,6 +77,7 @@ type App struct {
 	server              *server.Server
 	storage             storage.Storage
 	runtimeSettings     *runtimesettings.Service
+	versionCheck        *versioncheck.Checker
 	extensionAuth       bool
 
 	// registered records every successfully initialized subsystem in
@@ -727,6 +729,12 @@ func New(ctx context.Context, cfg Config) (*App, error) {
 		}
 	}
 
+	// The update check owns the only outbound connection core makes that is
+	// not a provider call. It is constructed even when disabled so GET
+	// /version keeps reporting the local build.
+	versionChecker := newVersionChecker(appCfg.VersionCheck)
+	app.versionCheck = versionChecker
+
 	serverCfg := &server.Config{
 		BasePath:                        appCfg.Server.BasePath,
 		MasterKey:                       appCfg.Server.MasterKey,
@@ -762,6 +770,7 @@ func New(ctx context.Context, cfg Config) (*App, error) {
 		Tagging:                         taggingResult.Service,
 		SessionDetector:                 session.NewDetectorFromConfig(appCfg.Session),
 		MCPEnabled:                      appCfg.MCP.Enabled,
+		VersionChecker:                  versionChecker,
 	}
 	if mcpResult != nil {
 		serverCfg.MCPGateway = mcpResult.Service
@@ -987,6 +996,10 @@ func (a *App) startServer(ctx context.Context, address string, start func(contex
 		return fmt.Errorf("server is already running")
 	}
 	serverCtx, cancel := context.WithCancel(ctx)
+	// Cancelled on every exit path, not just Shutdown: the server can also
+	// stop by returning an error, and background workers started on this
+	// context (the update check) would otherwise outlive it.
+	defer cancel()
 	done := make(chan error, 1)
 	a.serverStop = cancel
 	a.serverDone = done
@@ -995,6 +1008,9 @@ func (a *App) startServer(ctx context.Context, address string, start func(contex
 	if a.rateLimits != nil && a.rateLimits.Service != nil {
 		a.rateLimits.Service.Start(ctx)
 	}
+	if a.versionCheck.Enabled() {
+		go a.versionCheck.Run(serverCtx)
+	}
 
 	slog.Info("starting server", "address", address)
 	err := start(serverCtx)

internal/app/versioncheck.go

@@ -0,0 +1,33 @@
+package app
+
+import (
+	"log/slog"
+	"time"
+
+	"github.com/enterpilot/gomodel/config"
+	"github.com/enterpilot/gomodel/internal/version"
+	"github.com/enterpilot/gomodel/internal/versioncheck"
+)
+
+// newVersionChecker builds the update checker from configuration. The install
+// identifier is only materialized when checks are enabled, so a deployment
+// that opted out never writes one.
+func newVersionChecker(cfg config.VersionCheckConfig) *versioncheck.Checker {
+	checkerCfg := versioncheck.Config{
+		Enabled:        cfg.Enabled,
+		URL:            cfg.URL,
+		App:            version.App,
+		Version:        version.Version,
+		Interval:       time.Duration(cfg.IntervalHours) * time.Hour,
+		Timeout:        time.Duration(cfg.TimeoutSeconds) * time.Second,
+		MaxDailyChecks: cfg.MaxDailyChecks,
+	}
+	if cfg.Enabled {
+		checkerCfg.InstallID = versioncheck.InstallID()
+		if versioncheck.LeaksQueryInCleartext(cfg.URL) {
+			slog.Warn("version check URL sends its query string unencrypted; use https if it carries a credential",
+				"host", versioncheck.SafeURL(cfg.URL))
+		}
+	}
+	return versioncheck.New(checkerCfg)
+}