docker --add-host host-gateway is not supported on Rancher Desktop

[joebowbeer]

The --add-host=host.docker.internal:host-gateway solution does not work on Rancher Desktop with Moby docker runtime.

Can I map host.docker.internal or host.rancher-desktop.internal to host-gateway with the flag --add-host?

A: No, the special value host-gateway is specific to Docker Desktop and is not yet supported in Rancher Desktop. However, you can access services running on the host machine from within a container using host.docker.internal or host.rancher-desktop.internal without passing the --add-host flag.

Relates: #281

The Moby docs for --add-host also mention that host-gateway is (only) a Docker Desktop thing:

Docker Desktop automatically resolves this hostname

Given that there are several ways to install docker locally, including WSL, Colima, Podman, and Rancher Desktop (Moby), I think the documentation may need further revision.

---

By the way, even without adding host-gateway, I am currently receiving an error when trying to add a deployment:

error when calling 'http://host.docker.internal:9080/': client error (SendRequest), http2 error
    restate.error.code: META0003

This is happening with Rancher Desktop (moby) on both Mac and Windows.

[gvdongen]

Hi @joebowbeer,
Thanks for letting us know about the issue you are having.

I remember we had difficulty finding a single command which works across all OSs and Docker installation. For me this works with Docker Engine on Ubuntu, and also for my colleagues on Mac, and using Podman.

Does using docker run --name restate_dev --rm -p 8080:8080 -p 9070:9070 -p 9071:9071 --network=host docker.restate.dev/restatedev/restate:1.3 work for you? In that case you can just register with restate dp add localhost:9080

Although, I know this doesn't work for everyone either. Not sure if there is a one command fits all solution here.

[joebowbeer]

Moby and Rancher Desktop (which uses Moby), don't understand the host-gateway value but they do by default have a built-in assignment forhost.docker.internal

In other words, IIUC, there should be no need to add-host when using Rancher Desktop or Moby. You can just use the hostname host.docker.internal.

I think the same is true for Podman, but it does also understand host-gateway.

The problem I'm still having is that the registration is still not working...

[tillrohrmann]

Thanks for reporting this issue @joebowbeer. I could reproduce the issue using Rancher Desktop 1.18.2 on my Mac. The detailed error I could retrieve was

Discovery(Client(Http(http://host.docker.internal:9080/, Hyper(hyper_util::client::legacy::Error(SendRequest, hyper::Error(Http2, Error { kind: GoAway(b"", FRAME_SIZE_ERROR, Library) }))))))

when the discovery failed. Interestingly, I wasn't able to curl into the service endpoint using http2. It always failed with an empty reply from the server. When configuring the endpoint to use http1.1 (restatedev/sdk-typescript#489 (comment)) and using restate dp reg host.docker.internal:9080 --use-http1.1, I was able to complete the discovery successfully. This makes me think that there is some kind of problem with http2 and Rancher/software underneath. Hard to tell what it exactly is but I found that curling with --http2-prior-knowledge from within Rancher desktop returned Empty reply from server.

With orbstack things are working on my Mac. Did you have the chance to try out Docker desktop?

[tillrohrmann]

Asking the Rancher community whether this is a known limitation/issue: rancher-sandbox/rancher-desktop#8517.

[joebowbeer]

Note: I didn't need to change the app for http1.1 because NodeJS 22 provides fetch().

With Rancher Desktop on both Windows and Mac, trying to register in UI with http1.1 gets me a little farther:

Cannot reach the service endpoint to execute discovery:
[META0003] bad status code '302 Found'.
Response headers: {
  "content-type": "text/html; charset=utf-8",
  "location": "https://host.docker.internal:9443/discover",
  "date": "Tue, 15 Apr 2025 20:48:08 GMT",
  "content-length": "65"
}.
Body: <a href="https://host.docker.internal:9443/discover">Found</a>.

---

By the way, I verified on Mac that podman has host.docker.internal baked in.

On Mac, I can run restate via:

podman run --name restate_dev --rm -p 8080:8080 -p 9070:9070 -p 9071:9071 \
    --network=host docker.restate.dev/restatedev/restate:1.3

And then register via restate dp reg host.docker.internal:9080 or in the UI.

At the moment, however, nothing is working for me on Windows, and I was using docker because I wanted to see if I could run on Windows.

[joebowbeer]

@tillrohrmann the Rancher community has some questions for you, too

[tillrohrmann]

Thanks for letting me know. I'll try to provide them with a reproducible setup.

[tillrohrmann]

The problem turned out to be an auxiliary service that rancher starts and which binds to port 9080 (https://github.com/rancher/steve). Somehow TS does not fail when the port is already taken and therefore one thinks that the Restate service endpoint would listen on port 9080. However, it was all the time steve which was listening on this port. If you change the port of the Restate service endpoint, then you should be able to register a service endpoint when running the server on Rancher desktop @joebowbeer.

[joebowbeer]

@gvdongen @tillrohrmann Thanks!

I can now run on Windows using Rancher Desktop if I avoid port 9080.

docker run --name restate_dev --rm -p 8080:8080 -p 9070:9070 -p 9071:9071 \
    --network=host docker.restate.dev/restatedev/restate:1.3.1

docker run -it --network=host docker.restate.dev/restatedev/restate-cli:1.3.1 \
    dp reg http://host.docker.internal:9081

Notes for documentation:

1. The host-gateway value is a Docker Desktop thing
2. Moby, Rancher Desktop w/Moby and Podman already have host.docker.internal mapped; there is no need for host-gateway
3. Podman is not broken by the unnecessary --add-host=host.docker.internal:host-gateway
4. Rancher Desktop is broken by --add-host=host.docker.internal:host-gateway because host-gateway is undefined
5. Rancher Desktop may already be using port 9080 for its dashboard

@tillrohrmann please upvote rancher-sandbox/rancher-desktop#1890

[tillrohrmann]

Thanks for the summary @joebowbeer.

@gvdongen are you gonna update the Docker documentation accordingly?