Skip to content
Weik.ioDocs
2026.2
Try Weik.io

Where an integration runs

Weik.io 2026.2

A deployment runs on every agent whose capabilities match the integration's requirements. Video

Watch: What runs where, 3:42

The video shows where the hub and the agents run and the two outbound connections an agent makes on port 443.

On this page

A deployment runs on every agent whose capabilities match the integration’s requirements and the deployment’s environment, and whose allowed projects include the integration’s project. Two matching agents run two copies of the integration.

Capabilities#

An administrator gives each agent its capabilities when enrolling it, as key and value pairs such as os=linux and region=fi. You can use any other key your organisation needs to say where work may run, such as site or datacenter. An agent can’t give itself a capability.

The environment capability sets which environments’ deployments the agent may run, and limits its secrets and events to those environments. A separate list of projects sets which projects’ work it may run.

Terminal
$ weikio get agents
You see
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=devtest,production   finance, sandbox   2026.2.2   -        12s ago     2 running
/settings/agents/fi-01
The page of the agent fi-01 on Linux with Docker Compose. It serves production and runs three integrations that are all in sync. None of them is failing.The page of the agent fi-01 on Linux with Docker Compose. It serves production and runs three integrations that are all in sync. None of them is failing.The page of the agent fi-01 on Linux with Docker Compose. It serves production and runs three integrations that are all in sync. None of them is failing.The page of the agent fi-01 on Linux with Docker Compose. It serves production and runs three integrations that are all in sync. None of them is failing.
On an agent's page, you see what runs on the agent in the environments it serves and whether its deployments are in sync.

An agent can never reach more environments or projects than an administrator allowed it. Install an agent has the enrolment and the commands that change them.

Requirements#

An integration lists what it needs as a map of requirements, in integration.yaml or under spec of its document:

erp-invoice-export/integration.yaml
name: erp-invoice-export
version: 1.0.0
requirements: { os: linux, region: fi }

Deployed to production, this integration runs on every agent that may run project finance and has the matching capabilities:

  • os=linux
  • region=fi
  • environment=production

With the agents above, that’s both of them. An integration with no requirements runs on every agent that serves its environment and project.

A numeric capability matches when the agent’s value is at least the requirement’s, so memoryGb: 8 on an integration matches an agent with memoryGb=16.

Check where it runs#

Terminal
$ weikio describe agent agent-fi-02
You see
Agent:                agent-fi-02
ID:                   01k5x9m2qv7r3t8wz4hc6yj0fd
Host:                 linux-compose
Status:               online
Environments:         devtest, production
Capabilities:         os=linux region=fi environment=devtest,production
Projects:             finance, sandbox
Last sync:            12s ago
Version:              2026.2.2
Reaches the hub via:  public
Hub addresses:        wss://nats.hub.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       -

DIFF says whether what the agent reports under ACTUAL matches what it should run under DESIRED.

weikio status finance/erp-invoice-export shows the same for each environment and agent of the integration, and says why a deployment is waiting for an agent.

When no agent serves the environment, weikio deploy changes nothing and fails. To fix it, run the command in the error message.

Two copies, or one#

Two copies keep an integration that serves traffic running when one agent’s host goes down. Some kinds, such as transfers and schedules, still do their work once, because they run one copy at a time by default.

When capabilities change#

Weik.io applies a change of an agent’s capabilities or projects as soon as you make it. At its next sync, the agent stops the deployments that no longer match and starts the new matches.

Terminal
$ weikio agent set-capabilities agent-fi-02 os=linux region=fi environment=production
You see
Target: https://hub.example
2 deployments leave the agent at its next sync: devtest/finance/erp-invoice-export, devtest/sandbox/hello.
Continue? [y/N] y
agent agent-fi-02 updated (capabilities os=linux region=fi environment=production, revision 4201)

Run integrations that must not see each other’s data, such as those of two suppliers or two customers, on agents with different allowed projects. Code in one integration runs as the agent’s user and could read its neighbours’ files. Keeping integrations apart explains the rule.

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