Agents

Weik.io 2026.2

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

Watch: Sites and agents, 4:25

The video enrols an agent, runs its bundle on a host and sees the agent come online.

On this page

Commands on this page
weikio agent enrol
weikio get agents
weikio describe agent
weikio agent desired
weikio agent status
weikio agent diff
weikio agent logs
weikio agent set-capabilities
weikio agent set-projects
weikio agent drain
weikio agent undrain
weikio agent credentials
weikio agent revoke
weikio delete agent
Exit codes
See also

An agent runs your integrations on 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 bundle, which you copy to the agent’s host 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 an agent reaches only the projects and environments it serves. An agent connects to Weik.io 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 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 environments, gateways or other capabilities with the pairs given.
`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 bundle for an agent (the previous one stops working).
`weikio agent revoke`	Revoke an agent and stop everything it 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 bundle. At least one environment= capability is required for an agent that runs integrations. The bundle is written once and has the agent’s credentials, so copy it to the agent’s host over a channel you trust.

Terminal

weikio agent enrol <name> --host linux-compose|windows --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 or windows.
`--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 agent 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 it 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 environment=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 environment=devtest                        any                2026.2.2   -        4s ago      3 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
agent-hq-01   01k5w2ge6vqn51cpkajev491zq   linux-compose   integrations   offline   os=linux environment=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 environment=production   finance    2026.2.2   -        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 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       -

`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. The command exits 1 when the agent runs something other 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 environments, gateways or other capabilities with the pairs given. A list you give no pair for stays as it is, and the CLI says which lists it kept.

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. The environment= pairs replace the agent’s environments, the gateway= pairs its gateways and the other pairs its other capabilities. A key with no value, such as gateway=, empties its list.
`-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 environment=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 bundle for an agent (the previous one stops working). Use it for a lost bundle, or to change with --runs and --entrance what the agent 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 agent connects to the hub: public or hub-network (inside the hub’s network), by default how the agent connects now.
`--runs <runs>`	What it runs: integrations, gateway, or integrations,gateway, by default what it 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 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 Weik.io 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 Weik.io can’t be reached and 8 when a document isn’t valid. weikio agent diff exits 1 when the agent runs something other than its deployments ask for.

Agents

Commands on this page#

`weikio agent enrol`#

`weikio get agents`#

`weikio describe agent`#

`weikio agent desired`#

`weikio agent status`#

`weikio agent diff`#

`weikio agent logs`#

`weikio agent set-capabilities`#

`weikio agent set-projects`#

`weikio agent drain`#

`weikio agent undrain`#

`weikio agent credentials`#

`weikio agent revoke`#

`weikio delete agent`#

Exit codes#

See also#

Sign in to the live demo

Agents

Commands on this page#

weikio agent enrol#

weikio get agents#

weikio describe agent#

weikio agent desired#

weikio agent status#

weikio agent diff#

weikio agent logs#

weikio agent set-capabilities#

weikio agent set-projects#

weikio agent drain#

weikio agent undrain#

weikio agent credentials#

weikio agent revoke#

weikio delete agent#

Exit codes#

See also#

`weikio agent enrol`#

`weikio get agents`#

`weikio describe agent`#

`weikio agent desired`#

`weikio agent status`#

`weikio agent diff`#

`weikio agent logs`#

`weikio agent set-capabilities`#

`weikio agent set-projects`#

`weikio agent drain`#

`weikio agent undrain`#

`weikio agent credentials`#

`weikio agent revoke`#

`weikio delete agent`#