From c144d34e4ed3ab689f893865e4474e5185f87ccc Mon Sep 17 00:00:00 2001 From: Ben Date: Wed, 13 May 2026 12:59:01 -0400 Subject: [PATCH 1/2] docs: add HINDSIGHT_API_WORKER_ID tip to API quickstart Mirrors the tip already present in installation.md so users who follow the API quickstart's Docker tab see the same guidance about pinning a stable worker ID. Closes #1616. --- hindsight-docs/docs/developer/api/quickstart.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/hindsight-docs/docs/developer/api/quickstart.mdx b/hindsight-docs/docs/developer/api/quickstart.mdx index 01b872433..5707ccbd4 100644 --- a/hindsight-docs/docs/developer/api/quickstart.mdx +++ b/hindsight-docs/docs/developer/api/quickstart.mdx @@ -52,6 +52,12 @@ docker run --rm -it --pull always -p 8888:8888 -p 9999:9999 \ - **API**: http://localhost:8888 - **Control Plane** (Web UI): http://localhost:9999 +:::tip Set a stable `HINDSIGHT_API_WORKER_ID` in production +The worker uses the container hostname as its identity, which Docker sets to the container ID by default. That value changes on every restart, so any task that was being processed when the container went down stays parked under the old ID with no way for the new container to recognize it as its own. + +Set `HINDSIGHT_API_WORKER_ID` to a stable value (e.g., `-e HINDSIGHT_API_WORKER_ID=hindsight-prod`) so the worker keeps the same identity across restarts. This is recommended even for single-container deployments. For diagnosis and recovery commands, see [Admin CLI - Recovering stuck operations](/developer/admin-cli#recovering-stuck-or-zombie-operations). +::: + From 16bd2dc581ed5e8335dfc561721afd0e2cc3b8e0 Mon Sep 17 00:00:00 2001 From: Ben Date: Tue, 19 May 2026 14:53:35 -0400 Subject: [PATCH 2/2] docs: mirror WORKER_ID tip to versioned_docs v0.6 (from #1648) Folding in xmh1011's strict-improvement hunk from #1648: the versioned snapshot for v0.6 should carry the same production tip as the live doc. Same prose, same `:::tip` block. Includes the auto-regenerated skills/ reference. --- .../versioned_docs/version-0.6/developer/api/quickstart.mdx | 6 ++++++ .../hindsight-docs/references/developer/api/quickstart.md | 5 +++++ 2 files changed, 11 insertions(+) diff --git a/hindsight-docs/versioned_docs/version-0.6/developer/api/quickstart.mdx b/hindsight-docs/versioned_docs/version-0.6/developer/api/quickstart.mdx index 01b872433..5707ccbd4 100644 --- a/hindsight-docs/versioned_docs/version-0.6/developer/api/quickstart.mdx +++ b/hindsight-docs/versioned_docs/version-0.6/developer/api/quickstart.mdx @@ -52,6 +52,12 @@ docker run --rm -it --pull always -p 8888:8888 -p 9999:9999 \ - **API**: http://localhost:8888 - **Control Plane** (Web UI): http://localhost:9999 +:::tip Set a stable `HINDSIGHT_API_WORKER_ID` in production +The worker uses the container hostname as its identity, which Docker sets to the container ID by default. That value changes on every restart, so any task that was being processed when the container went down stays parked under the old ID with no way for the new container to recognize it as its own. + +Set `HINDSIGHT_API_WORKER_ID` to a stable value (e.g., `-e HINDSIGHT_API_WORKER_ID=hindsight-prod`) so the worker keeps the same identity across restarts. This is recommended even for single-container deployments. For diagnosis and recovery commands, see [Admin CLI - Recovering stuck operations](/developer/admin-cli#recovering-stuck-or-zombie-operations). +::: + diff --git a/skills/hindsight-docs/references/developer/api/quickstart.md b/skills/hindsight-docs/references/developer/api/quickstart.md index 603a8dea5..3ce0372c2 100644 --- a/skills/hindsight-docs/references/developer/api/quickstart.md +++ b/skills/hindsight-docs/references/developer/api/quickstart.md @@ -38,6 +38,11 @@ docker run --rm -it --pull always -p 8888:8888 -p 9999:9999 \ - **API**: http://localhost:8888 - **Control Plane** (Web UI): http://localhost:9999 +> **💡 Set a stable `HINDSIGHT_API_WORKER_ID` in production** +> +The worker uses the container hostname as its identity, which Docker sets to the container ID by default. That value changes on every restart, so any task that was being processed when the container went down stays parked under the old ID with no way for the new container to recognize it as its own. + +Set `HINDSIGHT_API_WORKER_ID` to a stable value (e.g., `-e HINDSIGHT_API_WORKER_ID=hindsight-prod`) so the worker keeps the same identity across restarts. This is recommended even for single-container deployments. For diagnosis and recovery commands, see [Admin CLI - Recovering stuck operations](../admin-cli.md#recovering-stuck-or-zombie-operations). > **💡 LLM Provider** > Hindsight requires an LLM with structured output support. Recommended: **Groq** with `gpt-oss-20b` for fast, cost-effective inference.