Weik.io

Deploying Agents

Deploy additional agents to scale integration execution

Deploy multiple agents to scale integration execution, distribute workload across locations, or run integrations in specific environments.

Prerequisites

  • Weik.io platform deployed (see Docker Compose Setup)
  • Docker installed on the agent machine
  • Network connectivity to the Weik.io backend and NATS server

Why Add More Agents

Add agents to:

  • Scale horizontally - Distribute integration workload across multiple machines
  • Deploy geographically - Run integrations closer to data sources and targets
  • Separate environments - Isolate development, staging, and production workloads
  • Ensure high availability - Deploy redundant agents with identical capabilities
  • Meet compliance requirements - Run integrations in specific security zones or regions

Deploy an Agent

Basic Docker Compose Configuration

Create a docker-compose.yml for your additional agent:

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 backend and NATS URLs.

Start the Agent

docker-compose up -d

Verify the Agent

Check the agent is running:

docker-compose ps

The agent should connect to the backend and appear in the UI under Agents.

Agent Capabilities

Capabilities define where and how integrations run. When you create an integration, specify required capabilities and Weik.io routes it to matching agents.

Define Capabilities

Set capabilities using environment variables:

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

You can define any custom capability dimension based on your requirements.

Match Integrations to Agents

Specify capabilities in your integration flow:

requirements:
  Location: Remote-Office
  Environment: Production

Weik.io routes the integration only to agents with matching capabilities.

Common Capability Dimensions

Use these standard dimensions or create custom ones:

  • Location - Physical or logical location (OnPremise, Cloud, Edge)
  • Environment - Environment type (Development, Staging, Production)
  • Region - Geographic region (EU-West, US-East, APAC)
  • SecurityZone - Security classification (Public, DMZ, Internal)
  • Compliance - Regulatory requirements (GDPR, HIPAA, SOC2)
  • DataCenter - Specific data center identifier

NATS Connectivity

Agents connect to NATS for communication with the backend. Choose the connection method based on your network architecture.

Direct Connection

Connect agents directly to the main NATS server:

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

Use direct connections when agents are on the same network as the NATS server.

Using NATS Leaf Nodes

For remote agents across different networks, deploy a local NATS leaf node. Leaf nodes provide:

  • Reduced network latency
  • Better resilience to network interruptions
  • Local message buffering during outages
  • Simplified firewall configuration

Deploy NATS Leaf Node:

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

Configure Leaf Node (leafnode.conf):

port: 4222

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

Connect Agent to Leaf Node:

Weikio__Nats__Url=nats://nats-leaf:4222

For WebSocket connections through firewalls, use wss:// URLs in the leaf node configuration.

Complete Example with Leaf Node

Deploy an agent with a local NATS 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__Agent__Capabilities__Region=EU-North'
      - '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 - Set to Development or Production
  • Weikio__Server__BaseAddress - Backend API URL (e.g., https://backend.example.com/)
  • Weikio__Nats__Url - NATS connection URL (e.g., nats://nats.example.com:4222)

Optional Environment Variables

  • Weikio__Agent__JbangFromPath - Use system JBang installation (true/false, default: false)
  • Weikio__Agent__Capabilities__<Name> - Define capabilities (e.g., Weikio__Agent__Capabilities__Location=Remote)

Image Tags

Use specific version tags for production deployments:

image: weikio/agent:2025.1  # Use specific version

For development and testing:

image: weikio/agent:dev  # Latest development version

Scaling Best Practices

Deploy agents strategically:

  • Geographic distribution - Place agents close to data sources to reduce latency
  • Environment isolation - Separate development, staging, and production workloads
  • High availability - Deploy multiple agents with identical capabilities for failover
  • Workload distribution - Add agents when CPU or memory utilization is consistently high
  • Security segmentation - Use capabilities to route integrations to appropriate security zones

Troubleshooting

Agent Not Connecting

Check the agent logs:

docker-compose logs agent

Verify network connectivity to backend and NATS:

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

Agent Not Visible in UI

Ensure the agent has successfully connected by checking:

  • Backend URL is correct and accessible
  • NATS URL is correct and accessible
  • No firewall blocking connections

Integrations Not Running on New Agent

Verify the agent capabilities match the integration requirements. Check the integration’s required capabilities in the UI or via CLI.

What’s Next