feat: Add optional Docker extraHosts (part 2)

[MAHDTech]

Overview

NOTE: This is part 2/2 and cannot be merged without part 1 as it requires the package.json updated with the new @junobuild/config version to be completed.

This PR adds an additional configuration item to the Docker options called extraHosts

Use case

This is useful for making host-machine services reachable from within the container under a stable DNS name such as host.docker.internal.

There are many examples but the main use case for me is working with EVM chains.

If you are working with EVM chains and need Anvil running locally by default Canisters running within SkyLab cannot access localhost.

With this change you can deploy the dfinity evm-rpc-canister into the Juno Pocket IC and then make connections like this

# Inside Docker container
Satellite -> EVM RPC

# Leaving Docker container
EVM RPC (via the host.docker.internal:host-gateway trick) -> Anvil running on local host

You now have end-to-end IC-EVM development fully local 🥳

Example

Here is a snippet from an example juno.config.mjs

  emulator: {
    runner: {
      type: "docker",
      name: "juno-skylab",
      image: "junobuild/skylab:latest",
      volume: "juno-skylab",
      platform: "linux/amd64",
      // Allow the container to reach host-machine services (e.g. Anvil RPC)
      // via the stable hostname host.docker.internal.
      // Requires @junobuild/cli built from the local fork (packages/cli).
      extraHosts: ["host.docker.internal:host-gateway"],
    },
    skylab: {
      ports: {
        server: 5987,
        admin: 5999,
        console: 5866,
      },
    },
  },

How it works

When the container start the following container arguments can be seen by running docker inspect juno-skylab

"ExtraHosts": [
  "host.docker.internal:host-gateway"
],

How to test it

Let's say for example you have a web service running on localhost:8545 you can do a quick test like this;

docker exec juno-skylab curl --verbose http://host.docker.internal:8545

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0* Host host.docker.internal:8545
 was resolved.
* IPv6: (none)
* IPv4: 172.17.0.1
*   Trying 172.17.0.1:8545...
* Connected to host.docker.internal (172.17.0.1) port 8545
> GET / HTTP/1.1
> Host: host.docker.internal:8545
> User-Agent: curl/8.5.0
> Accept: */*
>
< HTTP/1.1 400 Bad Request
< content-type: text/plain; charset=utf-8
< vary: origin, access-control-request-method, access-control-request-headers
< access-control-allow-origin: *
< content-length: 43
< date: Mon, 16 Mar 2026 04:52:53 GMT
<
{ [43 bytes data]
100    43  100    43    0     0  54156      0 --:--:-- --:--:-- --:--:-- 43000
* Connection #0 to host host.docker.internal left intact
Connection header did not include 'upgrade'

This shows the connection can now hit local services via the Docker Gateway using the neat trick that Docker provides with host.docker.internal

Related

Part 1