Install an agent

An agent runs your integrations on an on-premise host, in your cloud account or beside the hub. It comes with a small message server, the leaf node, which links out to your Weik.io installation. The same install can add a gateway that serves APIs on that host, or run the gateway alone. The host only connects out: it reaches the installation’s two names on TCP 443, and no port is opened towards it except the entrances of a gateway it runs. The central part of your installation is called the hub, and you see that word in setup.sh, in Health and on the sign-in page if it can’t be reached. The CLI and the admin UI call this stack a site, as in site bundle.

This page installs an agent on a Linux host, and Agents on Windows has the steps for Windows Server 2022 and 2025.

Enrol an agent#

Installing an agent has two steps: you enrol it with weikio agent enrol or Settings, Agents, Enrol agent, and then you run its setup script on the host.

A platform administrator enrols the agent. Weik.io creates the agent’s identity and credentials and writes the agent’s bundle, a folder you get once:

$ 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 goes to the agent’s host. The CLI and the admin UI call this folder the site bundle and this machine the site host. It has everything the agent 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 agent 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 on the agent’s host, which Gateways at sites describes.

Install the agent#

Copy the folder to the agent’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 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 environment=devtest,production   finance, hr   2026.2.2   -        4s ago      4 running
agent-fi-02   01k5x9m2qv7r3t8wz4hc6yj0fd   linux-compose   integrations   online   os=linux region=fi environment=production           finance       2026.2.2   -        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

Show full size

What the host needs#

• An agent’s host 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 the host 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 agent 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 host’s disk is encrypted, as Encryption at rest says.
• The host reaches the two names of your Weik.io installation on TCP 443, which the network’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 agent checks the hub’s certificate against it.

When the host’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:

name: erp-invoice-export
version: 1.0.0
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. An agent reaches only what an administrator allowed it, and nothing that runs on its host can widen that. The agent reports its os and arch when it connects. Weik.io 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 environment=production, revision 4201)

The agent fetches its new credential itself, Weik.io withdraws the old one, and the leaf links again with the new one at once. The link goes down once and no integration stops.

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 environment=devtest,production
Projects:             finance, hr
Last sync:            4s ago
Version:              2026.2.2
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 integration 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 Weik.io refuses the agent’s link from that moment. To take an agent out of use, drain it, move what’s left, then revoke it and delete its record.

Behind a proxy#

An agent 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 installation’s two names on the host’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 Weik.io issues for the agent 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 installation’s two names alone, or its authority goes into the bundle’s hub-ca.crt.

While the hub is away#

An agent keeps working while it can’t reach the hub. It keeps running its integrations 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 agent’s host 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 an agent’s host discards a batch answered with any other status.

Upgrade an agent#

Upgrade each agent 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 agent’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.