Sites and agents

A site is a host at your location, in your cloud account or beside the hub, where integrations run. Its stack is a small message server, the leaf, which links out to the hub, and beside it the agent that runs integrations, a gateway that serves APIs at the site, or both. A site only connects out: it reaches the hub’s two names on TCP 443, and no port is opened towards it except the entrances of a gateway it runs.

Enrol an agent#

A platform administrator enrols the agent at the hub. The platform creates the agent’s identity and credentials and writes a one-time site bundle:

$ weikio agent enrol agent-fi-01 --host linux-compose \
  --capabilities os=linux,region=fi,environment=devtest,environment=production \
  --projects finance,hr \
  --out ./agent-fi-01/

The folder has everything the site needs and nothing else:

docker-compose.yaml     # agent + leaf node containers, pinned images
setup.sh                # installs the files with their owner and modes, starts the agent, waits until it is online
.env                    # the images docker-compose.yaml runs, which an upgrade replaces
agent.env               # agent id, local leaf URL, WEIKIO_HOME
agent.creds             # this agent's credential for the leaf's link to the hub
leaf.conf               # the leaf node: one remote to the hub, two local users
agent.nk                # the leaf-local agent user's nkey seed
runtime.creds           # the leaf-local runtime user's password, used by every Camel JVM

The command prints the next steps, numbered, and the bundle can’t be downloaded again. If you lose it, weikio agent credentials agent-fi-01 issues a new one and withdraws the old credential.

--via public, the default, links the site through the hub’s published address on port 443. --via hub-network is for a cloud agent inside the hub’s own network, which links to the hub’s leaf port 7422 and needs no public name. --runs integrations,gateway adds a gateway to the site, which Gateways at sites describes.

Install the bundle#

Copy the folder to the site’s host and run its setup script there as root:

$ scp -r agent-fi-01 site-host:
$ ssh -t site-host 'cd agent-fi-01 && sudo sh ./setup.sh'

The script places the files in /opt/weikio/agent-fi-01, or in the folder --dir gives, starts the stack and waits until the agent reports to the hub. Within seconds the agent says hello, shows as online and receives the deployments that already match it. Then delete the folder on both machines, because it contains the agent’s credential.

$ weikio get agents

NAME          ID                           HOST            RUNS           STATUS   CAPABILITIES                                PROJECTS      VERSION    BEHIND   LAST SYNC   RUNTIMES
agent-fi-01   01k5x765rwwyedaqwwb82pdvd1   linux-compose   integrations   online   os=linux region=fi env=devtest,production   finance, hr   2026.2.1   -        4s ago      4 running
agent-fi-02   01k5x9m2qv7r3t8wz4hc6yj0fd   linux-compose   integrations   online   os=linux region=fi env=production           finance       2026.2.1   -        12s ago     1 running

In the admin UI the agents are under Settings › Platform › Agents, with filters for Online, Offline, Never reported, Update available, Draining and Revoked, and the Enrol agent button. An agent’s own page has its Overview, Integrations, Activity, Logs and Placement.

/settings/agents/fi-01

What the host needs#

• A site is tested on Ubuntu 24.04 LTS with Linux kernel 6.8, on x86-64, with Docker 29.9.2 and Compose 5.6.1 from Docker’s own package repository. The agent’s image is built for x86-64, and a site runs no builds, because every version is built once at the hub.
• The agent uses about 110 MB of memory, and each integration it runs about 131 to 136 MiB, as measured with a timer integration that splits a list. An integration’s Java heap may grow to 256 MB unless its deployment gives it another size. Keep another 200 to 230 MiB for the telemetry the site keeps while the hub is out of reach.
• The images use about 0.9 GB of disk, and a gateway’s about 0.55 GB more. The site’s disk sits encrypted, as Encryption at rest says.
• The host reaches the hub’s two names on TCP 443, which the site’s own DNS resolves, and Docker Hub or the registry in the bundle’s .env at the install and at every upgrade.
• The host’s clock stays in sync, as Ubuntu keeps it by default with systemd-timesyncd, because the site checks the hub’s certificate against it.

When the site’s network already uses Docker’s default address ranges, an integration can’t reach a host there. Give Docker other pools in /etc/docker/daemon.json before the setup script runs, then restart Docker:

{ "log-driver": "json-file", "log-opts": { "max-size": "50m", "max-file": "3" },
  "default-address-pools": [ { "base": "10.240.0.0/16", "size": 24 } ] }

Capabilities and projects#

Capabilities are key and value pairs an administrator writes on the agent, such as os, region, site, datacenter or environment. An integration lists what it needs as requirements, and the deployment adds its environment:

spec:
  requirements: { os: linux, region: fi }

A deployment of this integration to production runs on every agent that has os=linux, region=fi and environment=production and whose projects include the integration’s project. Two matching agents run two copies, which is how an integration gets high availability. A numeric capability matches at least its value, so memoryGb: 8 matches an agent with memoryGb=16. Where an integration runs has the rest.

The environments and projects are written into the agent’s credential. A site reaches only what an administrator allowed it, and nothing that runs at the site can widen that. The agent reports its os and arch when it connects. The platform records them but doesn’t turn them into capabilities, so a requirement matches only what an administrator wrote.

Change an agent#

Changing capabilities or projects takes effect in placement at once. Deployments that no longer match leave the agent at its next sync:

$ weikio agent set-capabilities agent-fi-02 os=linux region=fi environment=production

Target: https://hub.example
1 deployment leaves the agent at its next sync: devtest/finance/erp-invoice-export.
Continue? [y/N] y
agent agent-fi-02 updated (capabilities os=linux region=fi env=production, revision 4201)

The agent fetches its new credential itself, the platform withdraws the old one, and the leaf links again with the new one at once. The link goes down once, no flow stops, and nobody visits the site.

weikio describe agent shows what each deployment should run on the agent beside what it runs:

$ weikio describe agent agent-fi-01

Agent:                agent-fi-01
ID:                   01k5x765rwwyedaqwwb82pdvd1
Host:                 linux-compose
Status:               online
Environments:         devtest, production
Capabilities:         os=linux region=fi env=devtest,production
Projects:             finance, hr
Last sync:            4s ago
Version:              2026.2.1
Reaches the hub via:  public
Hub addresses:        wss://nats.acme.example:443

DEPLOYMENT                              DESIRED         ACTUAL                     DIFF                         STOP DEADLINE
devtest/finance/erp-invoice-export      1.1.0 started   1.1.0 running (pid 4121)   in sync                      70s (shutdownTimeout 45, extraShutdownTimeout 15 (Camel's defaults))
production/finance/erp-invoice-export   1.1.0 started   1.0.0 running (pid 3980)   version behind: restarting   70s (shutdownTimeout 45, extraShutdownTimeout 15 (Camel's defaults))
production/finance/nightly-payroll      stopped         stopped                    in sync                      -
devtest/sandbox/hello                   0.1.0 started   absent                     bundle not yet fetched       -

Drain and revoke#

Drain an agent before maintenance. Placement gives it nothing new while every flow it already runs carries on, so you empty the machine one deployment at a time:

$ weikio agent drain agent-fi-02

Target: https://hub.example
agent agent-fi-02 draining (since 2026-09-22 15:02 UTC, revision 4203)
New deployments aren't placed on it.
2 deployments keep running until you move or stop them:
  production   finance/erp-invoice-export   (running 1.1.0)
  production   finance/nightly-payroll      (stopped)
    To move it, run:
      weikio deploy finance/erp-invoice-export --env production --version 1.1.0
    To stop it instead, run:
      weikio undeploy finance/erp-invoice-export --env production

weikio agent undrain agent-fi-02 lets it take work again. weikio agent revoke agent-fi-02 stops everything on the agent at once: the agent stops its deployments as soon as the revocation reaches it, and the hub refuses the site’s link from that moment. To take a site out of use, drain it, move what’s left, then revoke it and delete its record.

Behind a proxy#

A site that reaches the hub only through an HTTP proxy needs four settings before the setup script runs:

• Docker’s own proxy in /etc/docker/daemon.json, for the image pulls
• root’s Docker client proxy in /root/.docker/config.json, which the agent passes on to its integrations
• a proxy block in the remote of the bundle’s leaf.conf
• DNS for the hub’s two names on the site’s own network

With the proxy block, the link’s line in leaf.conf looks like this:

{ urls: ["wss://nats.acme.example:443"], no_randomize: true, credentials: "/etc/nats/agent.creds", deny_exports: ["weikio.out.>"], account: SITE, proxy: { url: "http://proxy.corp.example:3128" } }

Make the same edit in every bundle the hub issues for the site later. An integration’s own calls go through the proxy with Java’s proxy properties, which the agent sets from HTTP_PROXY, HTTPS_PROXY and NO_PROXY. A proxy that inspects TLS either leaves the hub’s two names alone, or its authority goes into the bundle’s hub-ca.crt.

While the hub is away#

A site keeps running while it can’t reach the hub. The agent runs its integrations on and tries the hub again until the hub hasn’t replied for longer than the environment’s offline limit, 24 hours unless --offline-start-max-age on the environment says otherwise. Past that limit it stops them and keeps their files, and starts them again when the hub replies. Restarted while the link is cut, it starts them from its stored copy only within that limit.

The site keeps the log lines, metrics and spans of its integrations, its agent and its gateway on its own disk, up to 4 GiB per agent and per gateway or a tenth of the free disk when that’s less, and sends them with their original times once the hub accepts them again. A proxy or CDN in front of the hub must answer 502, 503 or 504 while the hub is out of reach, because a site discards a batch answered with any other status.

Upgrade a site#

Upgrade each site with the same release’s images.env the hub took. In the folder the setup script installed the agent in, run:

$ sudo sh ./setup.sh --upgrade <images.env>

It pulls the images the file lists, replaces the site’s .env with the file, recreates what changed and waits until the agent is online again. An agent on an older release keeps working and shows as behind, and weikio problems lists it with the release to upgrade to. A deploy of a version that needs a newer agent says which version that is.