Weik.io

Deploying Agents

Deploy additional agents to scale integration execution

Adding more agents is how you scale out your integration execution. You might need to handle a heavier workload, reach data sources sitting behind a corporate firewall, or keep your staging and production environments completely separate.

Prerequisites

  • You already have the central Weik.io platform 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

Most teams add remote agents for a few common reasons:

  • Scaling out: Your primary agent is maxing out its CPU, so you distribute the work.
  • Data gravity: If you’re moving a terabyte of data out of an on-prem database, you want the agent sitting right next to that database, not across the public internet.
  • Environment isolation: Keeping your development, staging, and production workloads from stepping on each other’s toes.
  • High availability: If an agent goes down, you want another one ready to pick up the slack.

Deploy an Agent

Basic Docker Compose Configuration

The easiest way to spin up an agent is with Docker Compose. 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:

Remember to replace backend.example.com and nats.example.com with your actual hostnames.

Start the Agent

docker-compose up -d

Verify the Agent

Check the container logs to make sure it started cleanly:

docker-compose ps

If everything is wired up correctly, you’ll see the new agent pop up in the Weik.io UI under the Agents tab.

Agent Capabilities

“Capabilities” are just tags that tell the central host what an agent is allowed to do, or where it lives. When you build an integration flow, you specify which capabilities it needs, 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 invent any capability dimension you want. There’s no hardcoded list.

Match Integrations to Agents

In your integration flow YAML, you just demand the capabilities you need:

requirements:
  Location: Remote-Office
  Environment: Production

The system will strictly route this integration to agents that have both of those tags.

Common Capability Dimensions

Even though you can make up your own, I see 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 talk to the central host via 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, just point it straight at the NATS server:

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

Using NATS Leaf Nodes

If your agent is sitting across the public internet, behind a strict firewall, or in a spotty network environment, deploy a NATS “leaf node” alongside the agent. Leaf nodes act as local relays—they buffer messages if the internet drops and handle the complex routing back to the mothership.

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

(Tip: If your firewall hates raw TCP traffic, you can configure the leaf node to connect back to the host using wss:// WebSockets instead.)

Complete Example with Leaf Node

Here is what a complete docker-compose.yml looks like 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 real deployments, pin a specific version tag so you don’t get surprise upgrades:

image: weikio/agent:2025.1

Use :dev only if you’re actively testing unreleased features.

Troubleshooting

Agent Not Connecting

Check the agent logs first. It usually tells you exactly what it can’t reach:

docker-compose logs agent

Drop into the container and see if it can actually ping the servers:

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

Agent Not Visible in UI

If the logs look okay but the agent isn’t in the UI, double-check your Weikio__Server__BaseAddress. If that URL is wrong, the agent might connect to NATS successfully but fail to register its presence with the web API.

Integrations Not Running on New Agent

If jobs are hanging in a “pending” state instead of running on your new agent, it’s almost always a capability mismatch. Check the exact spelling and casing of the capabilities requested in your integration flow versus what you set in the agent’s environment variables.

What’s Next