Skip to content
Weik.ioDocs
2026.2
Try Weik.io

Agents and sites

Weik.io 2026.2

Enrol agents, decide what each one runs, compare what it runs with what it should, and drain or revoke it.

On this page

An agent runs integrations at a site, which can be a server in your own network, a virtual machine in your cloud or a server beside the hub. weikio agent enrol creates the agent and writes its one-time site bundle, which you copy to the site and install with sudo sh ./setup.sh.

The capabilities and projects you give an agent decide which deployments it runs. They’re also written into the agent’s credential, so a site reaches only the projects and environments it serves. A site connects to the hub with outbound connections on port 443 and opens no inbound port.

Commands on this page#

Command What it does
weikio agent enrol Enrol an agent and write its one-time site bundle.
weikio get agents List the agents with their status and last sync.
weikio describe agent Show an agent with what it should run and what it runs.
weikio agent desired Print the deployments the agent should run.
weikio agent status Print what the agent last reported.
weikio agent diff Compare what the agent runs with its deployments (exits 1 when out of sync).
weikio agent logs Show the agent’s own log lines.
weikio agent set-capabilities Replace an agent’s capabilities.
weikio agent set-projects Replace the projects an agent may run.
weikio agent drain Stop giving an agent new deployments while it keeps running what it has.
weikio agent undrain Stop draining an agent.
weikio agent credentials Issue a new site bundle for an agent (the previous one stops working).
weikio agent revoke Revoke an agent and stop everything its site runs.
weikio delete agent Delete a revoked agent’s record.

The flags every command accepts, such as --env, --project, -o and --context, are on the CLI reference page and are left out of the tables below.

weikio agent enrol#

Enrol an agent and write its one-time site bundle. At least one environment= capability is required for a site that runs integrations. The bundle is written once and has the agent’s credentials, so copy it to the site over a channel you trust.

Terminal
weikio agent enrol <name> --host linux-compose --capabilities k=v,... [--projects p1,p2] [--via public|hub-network] [--runs integrations|gateway|integrations,gateway] [--entrance NAME=ADDRESS:PORT ...] [--out DIR]
Argument or flag What it does
<name> The agent’s name.
--host <host> The kind of host: linux-compose.
--capabilities <capabilities> Capabilities as k=v, comma separated (environment= can repeat).
--projects <projects> Projects it may run, comma separated, by default any project.
--via <via> How the site connects to the hub: public or hub-network (inside the hub’s network), by default public when the installation has a public address for agents, otherwise hub-network.
--runs <runs> What the site runs: integrations, gateway, or integrations,gateway, by default integrations.
--entrance <entrance> An address the site’s gateway listens on, as NAME=ADDRESS:PORT, such as lan=0.0.0.0:8443, repeated for each entrance.
-d, --out, --out-dir <out-dir> Directory to write the files into.
--reason <reason> Reason for the change, stored with the audit record.

Who can run it: a platform administrator.

API: POST /api/v1/agents.

Also written as weikio agent enroll.

Terminal
$ weikio agent enrol agent-fi-02 --host linux-compose --capabilities os=linux,region=fi,environment=devtest,environment=production --projects finance,sandbox --out ./sites/fi-02
You see
Target: https://hub.example
agent agent-fi-02 enrolled (id 01k5x9m2qv7r3t8wz4hc6yj0fd; capabilities os=linux region=fi env=devtest,production; projects finance, sandbox)
Wrote ./sites/fi-02/agent.env, agent.creds, leaf.conf, agent.nk, runtime.creds, docker-compose.yaml, setup.sh, .env.

The bundle can't be downloaded again. If you lose it, issue a new one with:
  weikio agent credentials 01k5x9m2qv7r3t8wz4hc6yj0fd

Next steps:
  1. Copy the folder to the site host:
       scp -r ./sites/fi-02 site-host:
  2. On the site host, run the setup script to install and start the agent:
       cd fi-02 && sudo sh ./setup.sh
  3. Check that the agent is online:
       weikio get agents
  4. Delete the folder on both machines once the agent is online: it contains the agent's credential.
  5. To upgrade the site to a later release, run in the agent's installation folder:
       sudo sh ./setup.sh --upgrade <the release's images.env>

weikio get agents#

List the agents with their status and last sync.

Terminal
weikio get agents [--env E] [--online|--offline] [--behind] [--draining]
Argument or flag What it does
--online Show only online agents.
--offline Show only offline agents.
--behind Show only agents whose image or bundle is behind the hub’s release.
--draining Show only draining agents.

Who can run it: a platform administrator.

API: GET /api/v1/agents?environment=.

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 env=devtest                        any                2026.2.1   -        4s ago      3 running
agent-fi-02   01k5x9m2qv7r3t8wz4hc6yj0fd   linux-compose   integrations   online    os=linux region=fi env=devtest,production   finance, sandbox   2026.2.1   -        12s ago     2 running
agent-hq-01   01k5w2ge6vqn51cpkajev491zq   linux-compose   integrations   offline   os=linux env=production                     finance            2026.2.0   image    3d ago      0 running
Terminal
$ weikio get agents --draining
You see
NAME          ID                           HOST            RUNS           STATUS             CAPABILITIES                        PROJECTS   VERSION    BEHIND   LAST SYNC   RUNTIMES
agent-fi-02   01k5x9m2qv7r3t8wz4hc6yj0fd   linux-compose   integrations   online, draining   os=linux region=fi env=production   finance    2026.2.1   -        8s ago      1 running

weikio describe agent#

Show an agent with what it should run and what it runs.

Terminal
weikio describe agent <id|name>
Argument or flag What it does
<agent> Agent name or ID.

Who can run it: a platform administrator.

API: GET /api/v1/agents/{id}, GET /api/v1/agents/{id}/desired, GET /api/v1/agents/{id}/status, GET /api/v1/agents/{id}/diff, GET /api/v1/apim/instances.

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 env=devtest,production
Projects:             finance, sandbox
Last sync:            12s ago
Version:              2026.2.1
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       -

weikio agent desired#

Print the deployments the agent should run.

Terminal
weikio agent desired <id|name>
Argument or flag What it does
<agent> Agent name or ID.

Who can run it: a platform administrator.

API: GET /api/v1/agents/{id}/desired.

weikio agent status#

Print what the agent last reported.

Terminal
weikio agent status <id|name>
Argument or flag What it does
<agent> Agent name or ID.

Who can run it: a platform administrator.

API: GET /api/v1/agents/{id}/status.

weikio agent diff#

Compare what the agent runs with its deployments (exits 1 when out of sync). The command exits 1 when the agent runs something else than its deployments ask for.

Terminal
weikio agent diff <id|name>
Argument or flag What it does
<agent> Agent name or ID.

Who can run it: a platform administrator.

API: GET /api/v1/agents/{id}/diff.

weikio agent logs#

Show the agent’s own log lines.

Terminal
weikio agent logs <id|name> [-f|--follow] [--since] [--level] [--query Q] [--limit N] [--before ID | --after ID]
Argument or flag What it does
<agent> Agent name or ID.
-f, --follow Print new lines as they arrive, until Ctrl-C.
--since <since> How far back to read, such as 10m.
--level <level> Show only lines at this level or above: trace, debug, info, warn, error or fatal.
--query <query> Full-text query over the lines, in the log store’s query language.
--limit <limit> Number of lines to read, at most 5,000.
--before <before> Read lines older than the one with this _id.
--after <after> Read lines newer than the one with this _id.

Who can run it: a platform administrator.

API: GET /api/v1/logs, GET /api/v1/logs/tail.

weikio agent set-capabilities#

Replace an agent’s capabilities.

Terminal
weikio agent set-capabilities <id|name> k=v ...
Argument or flag What it does
<agent> Agent name or ID.
<capabilities> Capabilities as k=v (environment= can repeat).
-y, --yes Don’t ask for confirmation.
--reason <reason> Reason for the change, stored with the audit record.

Who can run it: a platform administrator.

API: PATCH /api/v1/agents/{id}.

Terminal
$ weikio agent set-capabilities agent-fi-02 os=linux region=fi environment=production
You see
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)

weikio agent set-projects#

Replace the projects an agent may run.

Terminal
weikio agent set-projects <id|name> p1,p2
Argument or flag What it does
<agent> Agent name or ID.
<projects> The projects, comma separated, or “” for any project.
-y, --yes Don’t ask for confirmation.
--reason <reason> Reason for the change, stored with the audit record.

Who can run it: a platform administrator.

API: PATCH /api/v1/agents/{id}.

Terminal
$ weikio agent set-projects agent-fi-02 finance
You see
Target: https://hub.example
agent agent-fi-02 updated (projects finance, revision 4202)

weikio agent drain#

Stop giving an agent new deployments while it keeps running what it has. Every integration the agent runs keeps running until you move or stop it, and the command prints the commands that do that.

Terminal
weikio agent drain <id|name> [-y]
Argument or flag What it does
<agent> Agent name or ID.
-y, --yes Don’t ask for confirmation.
--reason <reason> Reason for the change, stored with the audit record.

Who can run it: a platform administrator.

API: POST /api/v1/agents/{id}/drain.

Terminal
$ weikio agent drain agent-fi-02
You see
Target: https://hub.example
Agent 'agent-fi-02' runs deployments in production environment 'production', which keep running while nothing new is placed on it.
Drain it? [y/N] y
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)   no other online agent can run it: a move stops it until one connects
    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
  production   finance/nightly-payroll      (stopped)         no other online agent can run it: a move stops it until one connects
    To move it, run:
      weikio deploy finance/nightly-payroll --env production --version 1.0.0 --stopped
    To stop it instead, run:
      weikio undeploy finance/nightly-payroll --env production

weikio agent undrain#

Stop draining an agent.

Terminal
weikio agent undrain <id|name>
Argument or flag What it does
<agent> Agent name or ID.
--reason <reason> Reason for the change, stored with the audit record.

Who can run it: a platform administrator.

API: POST /api/v1/agents/{id}/undrain.

Terminal
$ weikio agent undrain agent-fi-02
You see
Target: https://hub.example
agent agent-fi-02 updated (draining cleared, revision 4206)

weikio agent credentials#

Issue a new site bundle for an agent (the previous one stops working). Use it for a lost bundle, or to change with --runs and --entrance what the site runs. The agent is offline until you install the new bundle with its setup.sh.

Terminal
weikio agent credentials <id|name> [--via public|hub-network] [--runs integrations|gateway|integrations,gateway] [--entrance NAME=ADDRESS:PORT ...] [--out DIR] [-y]
Argument or flag What it does
<agent> Agent name or ID.
--via <via> How the site connects to the hub: public or hub-network (inside the hub’s network), by default how the agent connects now.
--runs <runs> What the site runs: integrations, gateway, or integrations,gateway, by default what the site runs now.
--entrance <entrance> An address the site’s gateway listens on, as NAME=ADDRESS:PORT, such as lan=0.0.0.0:8443, repeated for each entrance.
-d, --out, --out-dir <out-dir> Directory to write the files into.
-y, --yes Don’t ask for confirmation.
--reason <reason> Reason for the change, stored with the audit record.

Who can run it: a platform administrator.

API: POST /api/v1/agents/{id}/credentials.

weikio agent revoke#

Revoke an agent and stop everything its site runs. The agent stops everything it runs, its link to the hub is refused and the record stays as revoked. A revoked agent can’t be brought back, so enrol a new one for the host.

Terminal
weikio agent revoke <id|name> [-y]
Argument or flag What it does
<agent> Agent name or ID.
-y, --yes Don’t ask for confirmation.
--reason <reason> Reason for the change, stored with the audit record.

Who can run it: a platform administrator.

API: POST /api/v1/agents/{id}/revoke.

weikio delete agent#

Delete a revoked agent’s record.

Terminal
weikio delete agent <id|name> [-y]
Argument or flag What it does
<agent> Agent name or ID.
-y, --yes Don’t ask for confirmation.
--reason <reason> Reason for the change, stored with the audit record.

Who can run it: a platform administrator.

API: DELETE /api/v1/agents/{id}.

Exit codes#

The commands on this page exit with the codes in the exit code table: 0 on success, 1 when the hub refuses a change, 2 for a usage error, 3 when the key is missing or not allowed, 4 when something isn’t found, 5 for a conflicting change, 6 when the hub can’t be reached and 8 when a document isn’t valid. weikio agent diff exits 1 when the agent runs something else than its deployments ask for.

See also#