[Bug][Windows/Docker Desktop] "Timeout waiting for Temporal" - gRPC health check fails on Windows/WSL2

[nlgbao1340]

Environment

• OS: Windows 11 with Docker Desktop (WSL2 backend)
• Shannon version: 1.2.0 (npx @keygraph/shannon)
• Docker Desktop version: [your version]

What happens

Running npx @keygraph/shannon start always ends with:
Waiting for Temporal to be ready...
Timeout waiting for Temporal

The shannon-temporal container starts and is running, but Shannon times out waiting for it.

Root cause

Shannon's readiness check (isTemporalReady() in index.mjs) runs:

docker exec shannon-temporal temporal operator cluster health --address localhost:7233

On Windows/Docker Desktop, this command always fails with: Error: failed reaching server: context deadline exceeded

This is a known issue with Temporal on Windows/WSL2 - the server binds to the container's internal IP, not 127.0.0.1, so the gRPC health check cannot connect via localhost inside the container.

Reference: temporalio/docker-compose#225

Verification

The Temporal HTTP interface (port 8233) works correctly:
curl http://localhost:8233/ → HTTP 200
Only the gRPC health check fails.

Suggested fix

Fall back to an HTTP check when the gRPC check fails:

  function isTemporalReady() {
    const grpc = runOutput("docker", [
      "exec", "shannon-temporal",
      "temporal", "operator", "cluster", "health", "--address", "localhost:7233"
    ]);
    if (grpc.includes("SERVING")) return true;

    // Fallback for Windows/Docker Desktop where gRPC health check fails
    const http = runOutput("docker", [
      "exec", "shannon-temporal",
      "sh", "-c", "wget -q -O /dev/null http://localhost:8233/ && echo SERVING"
    ]);
    return http.includes("SERVING");
}

[ezl-keygraph]

Thanks for the detailed write-up. Shannon doesn't officially support native Windows, only WSL2 (see the Platform-Specific Instructions section of the README). I tried testing on Windows 11 and it worked, so I couldn't reproduce the timeout. Could you retry by running Shannon from inside WSL and let us know if it still fails?

[ezl-keygraph]

Closing this as stale since there's been no further activity. Shannon only officially supports WSL2 on Windows, not native Windows/Docker Desktop, and I couldn't reproduce the timeout. Feel free to reopen if you're still hitting this after running Shannon from inside WSL. Thanks!