Skip to content
Weik.ioDocs
2026.2
Try Weik.io

Gateways at sites

Weik.io 2026.2

Serve an API at a site to the machines on its network, and let partners reach it through a hub gateway without opening a port at the site.

On this page

Serve an API at a site when the machines that call it are on the site’s network. A gateway created with --served-by site runs at the site as an APIM instance beside the agent, so the machines call the APIs there directly. The gateway accepts calls only on the entrances you set when you enrol its agent, such as an address on the plant’s network. The site opens no port towards the hub or the internet.

A partner on the internet calls the hub's gateway partner, which admits the caller by its subscription and relays the call to the site. The relayed call crosses the site's link as one message of up to 1 MiB. The site opened that link itself, outbound on port 443, so the site opens no port towards the hub or the internet. At the factory site the gateway factory runs beside the agent and serves HTTPS on its entrance lan, 10.20.0.5:443, which is the only port the site's stack publishes. Machines on the plant network call it there directly. The gateway calls the integration on the same host at http://integrations:8080.

Machines at the site call the gateway factory on its entrance. A partner's call reaches it through the hub gateway partner and the site's link.

Create the gateway#

Terminal
$ weikio gateway create factory --env production --served-by site --hostname api.factory.corp.example --networks 10.20.0.0/16 --entrance lan

Enrol an agent to serve it#

Each agent that has the capability gateway=factory runs an APIM instance of the gateway on its Linux host. Enrol the agent with gateway=factory in --capabilities and gateway in --runs, and give the address its entrance listens on in --entrance:

Terminal
$ weikio agent enrol factory-1 --host linux-compose --capabilities os=linux,site=factory,environment=production,gateway=factory --projects finance --runs integrations,gateway --entrance lan=10.20.0.5:443 --out ./factory-1/

An enrolment that runs only a gateway has no agent program, and it still appears under Agents.

The entrance listens for HTTPS on that address only. The gateway terminates TLS itself, so it sees each caller’s address and client certificate. To change the entrances, issue a new bundle with weikio agent credentials factory-1 --entrance lan=....

To check the site gateway, run weikio describe agent factory-1. It prints:

  • The site’s entrances
  • The gateways it serves
  • The last report of its APIM instance

weikio get apim-instances lists every APIM instance at the hub and at the sites.

Where the upstream is#

An API at the site calls an integration on the same host at http://integrations:<port>. The port is Camel’s 8080, unless the integration sets camel.server.enabled=true with a different camel.server.port. Write that address as a value per environment, as for any upstream address:

clusters:
  - ClusterId: orders
    Destinations:
      orders: { Address: "{{orders-url}}" }    # orders-url = http://integrations:8080 in production

That address reaches only the integrations on the host the call arrives at, so the integration must run on every host that serves the gateway. Give the integration a requirement that matches those hosts, such as site: factory.

To call another system on the site’s network, use its address. The site’s operator allows that connection as for any other client.

Certificates#

Each APIM instance makes its key on its host and gets its certificate over the site’s link. Who signs the certificate depends on the name:

  • The platform’s own authority signs a name that no public authority signs, such as one under .internal.
  • The hub orders the certificate of a public name from Let’s Encrypt or from your own ACME server.
  • For an ACME server that only the site reaches, the APIM instance orders the certificate itself.

Machines that call a name the platform’s authority signs need to trust that authority once. Get it with weikio platform authority get.

Site certificates renew when half their lifetime has passed, so a site whose link is cut keeps a valid certificate for at least the other half.

The gateway keeps serving its APIs. Changes you make reach it when the link returns. When the hub hasn’t confirmed the gateway’s APIs for 24 hours, the gateway stops serving them until the site reaches the hub again. The gateway’s log at the site shows how long ago the hub last confirmed them. To change the 24 hours, set Weikio__Apim__OfflineStart__MaxAge in the site’s gateway.env.

Until the link returns, each APIM instance counts a subscription’s limit separately instead of once across all of them.

Partners through the hub#

When an API’s upstream is reachable only from the site, a partner on the internet calls the API through a hub gateway. The hub gateway relays each call to the site’s gateway, so no port is opened at the site.

  1. Add the hub gateway to the site gateway’s --relay-from.
  2. Deploy the version on both gateways.
  3. Relay the hub gateway to the site gateway with --via.
Terminal
$ weikio gateway set factory --relay-from partner
$ weikio api deploy finance/orders@v1 --env production --gateways partner,factory
$ weikio api set-gateways finance/orders@v1 --env production --via partner=factory

The hub gateway admits the caller by its subscription and its rules. The site gateway then calls the upstream. A relayed call’s body and headers together can be at most 1 MiB. An answer from the site over the same limit reaches the caller as 502.

What a site gateway doesn’t serve#

Only hub gateways serve webhook versions. To accept such calls at a site, put a proxy version in front of the integration’s HTTP endpoint.

Sign in to the live demo

Sign in with the shared viewer account. It can open every screen of the example projects but can't change anything.

E-mail
viewer@demo.weik.io
Password
try-weikio-live-demo
Open the live demo