Weik.io

Deploying Agents

Deploy additional agents to scale integration execution

Deploy additional agents to scale out integration execution. Common reasons include handling a heavier workload, reaching data sources behind a corporate firewall, or keeping staging and production environments separate.

Prerequisites

  • The central Weik.io platform is running (see Docker Compose Setup)
  • Docker is installed on the target machine
  • The machine can reach the Weik.io backend and NATS server over the network

Why add more agents

Teams typically add remote agents for these reasons:

  • Scaling out: Distribute work when the primary agent reaches its CPU limits.
  • Data gravity: When moving large amounts of data out of an on-premises database, run the agent next to that database instead of transferring the data across the public internet.
  • Environment isolation: Keep development, staging, and production workloads separate.
  • High availability: If an agent goes down, another agent can take over its work.

Deploy an agent

Basic Docker Compose configuration

Docker Compose is the simplest way to deploy an agent. Create a docker-compose.yml on the new machine:

services:
  agent:
    image: weikio/agent:dev
    restart: unless-stopped
    environment:
      - 'WEIKIO_HOME=/etc/weikio'
      - 'ASPNETCORE_ENVIRONMENT=Production'
      - 'Weikio__Server__BaseAddress=https://backend.example.com/'
      - 'Weikio__Agent__JbangFromPath=false'
      - 'Weikio__Agent__Capabilities__Location=Remote-Office'
      - 'Weikio__Agent__Capabilities__Environment=Production'
      - 'Weikio__Nats__Url=nats://nats.example.com:4222'
    volumes:
      - agent-data:/etc/weikio

volumes:
  agent-data:

Replace backend.example.com and nats.example.com with your actual hostnames.

Start the agent

docker-compose up -d

Verify the agent

Check that the container started correctly:

docker-compose ps

If the configuration is correct, the new agent appears in the Weik.io UI under the Agents tab.

Agent capabilities

Capabilities are tags that tell the central host what an agent is allowed to do, or where it runs. When you build an integration flow, you specify which capabilities it requires, and the host routes the job to a matching agent.

Define capabilities

You define capabilities using environment variables on the agent:

Weikio__Agent__Capabilities__Location=Remote-Office
Weikio__Agent__Capabilities__Environment=Production
Weikio__Agent__Capabilities__Region=EU-West

You can define any capability dimension you need; there is no fixed list.

Match integrations to agents

In your integration flow YAML, specify the capabilities the flow requires:

requirements:
  Location: Remote-Office
  Environment: Production

The system routes this integration only to agents that have both of those tags.

Common capability dimensions

Although you can define your own, teams commonly use these dimensions:

  • Location (OnPremise, Cloud, Edge)
  • Environment (Development, Staging, Production)
  • Region (EU-West, US-East, APAC)
  • SecurityZone (Public, DMZ, Internal)

NATS connectivity

Agents communicate with the central host over NATS. Depending on your network topology, you have two ways to connect.

Direct connection

If your agent is on the same local network or VPN as the central host, point it directly at the NATS server:

Weikio__Nats__Url=nats://nats.example.com:4222

Using NATS leaf nodes

If your agent runs across the public internet, behind a strict firewall, or in an unreliable network environment, deploy a NATS leaf node alongside the agent. Leaf nodes act as local relays: they buffer messages during network outages and handle the routing back to the central host.

Deploy the leaf node:

services:
  nats-leaf:
    image: nats:latest
    command: ["-c", "/config/leafnode.conf"]
    volumes:
      - ./leafnode.conf:/config/leafnode.conf
    ports:
      - "4222:4222"

Configure it (leafnode.conf):

port: 4222

leafnodes {
  remotes = [
    {
      url: "nats://nats.example.com:4222"
      # Optional: credentials: "/config/nats.creds"
    }
  ]
}

Connect your agent to the local leaf node:

Weikio__Nats__Url=nats://nats-leaf:4222

If your firewall blocks raw TCP traffic, you can configure the leaf node to connect to the host using wss:// WebSockets instead.

Complete example with leaf node

The following is a complete docker-compose.yml for a remote agent paired with its own leaf node:

services:
  nats-leaf:
    image: nats:latest
    command: ["-c", "/config/leafnode.conf"]
    volumes:
      - ./leafnode.conf:/config/leafnode.conf
      - leaf-data:/var/data
    networks:
      - agent-network

  agent:
    image: weikio/agent:dev
    restart: unless-stopped
    environment:
      - 'WEIKIO_HOME=/etc/weikio'
      - 'ASPNETCORE_ENVIRONMENT=Production'
      - 'Weikio__Server__BaseAddress=https://backend.example.com/'
      - 'Weikio__Agent__JbangFromPath=false'
      - 'Weikio__Agent__Capabilities__Location=Remote-Office'
      - 'Weikio__Agent__Capabilities__Environment=Production'
      - 'Weikio__Nats__Url=nats://nats-leaf:4222'
    depends_on:
      - nats-leaf
    volumes:
      - agent-data:/etc/weikio
    networks:
      - agent-network

networks:
  agent-network:

volumes:
  leaf-data:
  agent-data:

Configuration reference

Required environment variables

  • WEIKIO_HOME - Configuration and data directory (default: /etc/weikio)
  • ASPNETCORE_ENVIRONMENT - Usually Production
  • Weikio__Server__BaseAddress - Backend API URL
  • Weikio__Nats__Url - NATS connection URL

Image tags

For production deployments, pin a specific version tag to avoid unintended upgrades:

image: weikio/agent:2025.1

Use :dev only when testing unreleased features.

Troubleshooting

Agent not connecting

Check the agent logs first; they usually indicate what the agent cannot reach:

docker-compose logs agent

Verify network connectivity from inside the container:

docker-compose exec agent ping backend.example.com
docker-compose exec agent ping nats.example.com

Agent not visible in the UI

If the logs look correct but the agent does not appear in the UI, check your Weikio__Server__BaseAddress. If that URL is wrong, the agent can connect to NATS successfully but fail to register with the web API.

Integrations not running on the new agent

If jobs stay in a pending state instead of running on the new agent, the cause is usually a capability mismatch. Check the exact spelling and casing of the capabilities requested in your integration flow against the agent’s environment variables.

Next steps