On-Premises Agent Setup¶

This guide covers installing EasyTask worker agents on your on-premises Linux hosts. Agents are the distributed workers that execute your task workflows. You can install them on the same host as the infrastructure or on separate remote hosts.

Prerequisites¶

Requirement	Details
Operating System	Linux (Ubuntu 22.04 or later)
Network	Access to the EasyTask message broker (KeyDB) and secrets store (OpenBao)
License Certificates	Valid license files for the host
Infrastructure Running	PostgreSQL, KeyDB, Keycloak, and OpenBao must be accessible

Same host vs. remote host

If you are installing the agent on the same host as the infrastructure (completed via Host Setup), all prerequisites are already met. For remote hosts, ensure network connectivity to the infrastructure host on the broker (6379) and vault (8200) ports.

Step 1 — Get the Installer¶

On the infrastructure host¶

If you already ran the full installer on this host, the agent installer is already available:

cd ~/easytask
./easytask_installer.bin

On a remote host¶

Log in to the EasyTask Web Console, navigate to the Client Portal dashboard, and copy the on-prem download command. Run it on your target host:

curl -sL -o /tmp/install.sh "https://<your-easytask-host>/run_easytask_installer?client_identifier=<your-token>" && bash /tmp/install.sh

Use the on-prem command

Make sure you use the on-prem installer command (which uses /run_easytask_installer), not the cloud agent command (which uses /run_easytask_agent_installer). The on-prem installer provides access to the full interactive menu.

Step 2 — License Verification (First Run Only)¶

On a new host, the installer prompts for a one-time password (OTP) to download your license certificates:

  An OTP has been sent to your registered email.
  Enter OTP: 123456

  License files saved successfully.

Enter the 6-digit OTP sent to your registered email. This step is skipped on subsequent runs.

Step 3 — Select "Install Agent"¶

The installer presents the interactive menu:

============================================================
   EasyTask Installer V2
============================================================

  What would you like to do?

    1. Setup EasyTask Host (Infrastructure)
    2. Install Scheduler Instance
    3. Install Agent
    4. Install Integration Server
    5. Install EasyTask CLI
    6. Uninstall EasyTask (Full)
    7. Uninstall Scheduler Instance
    8. Uninstall Agent
    9. Uninstall Integration Server
    0. Exit

  Enter choice [0-9]: 3

Step 4 — Provide Agent Node Names¶

The installer prompts for agent node names:

  Enter agent node names (comma-separated): prod-worker-01
  Installing agent(s): prod-worker-01

Installing Multiple Agents¶

You can install multiple agent nodes in a single pass by providing comma-separated names:

  Enter agent node names (comma-separated): agent-01, agent-02, agent-03
  Installing agent(s): agent-01, agent-02, agent-03

Each agent node gets its own systemd service: easytask-agent@<node_name>

Choosing agent names

Pick descriptive names that are easy to identify — for example, based on the hostname, environment, or workload type (e.g., prod-etl-worker, uat-sftp-agent). Names must be unique across your EasyTask deployment.

Step 5 — Installation Process¶

The installer performs the following steps automatically:

5.1 — Prerequisites Check¶

Validates connectivity to the message broker and secrets store:

  Checking prerequisites...
    Broker      (127.0.0.1:6379) ... OK
    Vault       (http://127.0.0.1:8200/v1/sys/health) ... OK

5.2 — Fetch Image Manifest¶

Retrieves the latest agent binary version from the registry:

  Fetching image manifest from backend...
  [OK] Image manifest loaded.

5.3 — Download Agent Binary¶

Downloads the worker agent binary from the EasyTask registry:

  [1/4] Downloading worker_agent v0.0.2 from registry.example.com...
  Download complete.

5.4 — Install Systemd Service¶

Creates the systemd service template that manages all agent nodes:

  [2/4] Installing systemd service template...
  Template installed: ~/.config/systemd/user/easytask-agent@.service

5.5 — Create Node Configuration¶

For each agent node, creates an environment file and starts the service:

  [3/4] Setting up 2 node(s)...
    [1/2] Node 'agent-01'...
    Service active (started): easytask-agent@agent-01
    [2/2] Node 'agent-02'...
    Service active (started): easytask-agent@agent-02

5.6 — Enable Lingering¶

Ensures agent services survive user logout:

  [4/4] Enable lingering... OK

Step 6 — Verify¶

Check Agent Status¶

systemctl --user status easytask-agent@prod-worker-01

You should see active (running):

● easytask-agent@prod-worker-01.service - EasyTask Worker Agent (prod-worker-01)
     Loaded: loaded (~/.config/systemd/user/easytask-agent@.service; enabled)
     Active: active (running)

View Agent Logs¶

tail -f ~/easytask/worker_agent/worker_prod-worker-01.log

Or via journalctl:

journalctl --user -u easytask-agent@prod-worker-01 -f

Verify in the Web Console¶

Log in to the web console at http://<your-host-ip>:8002 and navigate to Agents. Your newly installed agents should appear as online.

Installing Agents on Multiple Hosts¶

For distributed deployments, install agents on each host using the same process:

Download the installer on each host using the download command from the Client Portal
Complete the OTP license verification
Select Option 3 and provide unique node names for each host
Verify each agent appears online in the web console

Unique node names

Each agent node name must be globally unique across your entire EasyTask deployment. Use a naming convention that includes the hostname or location, such as db-host-01-worker or us-east-agent-01.

Uninstalling an Agent¶

To remove specific agent nodes, use the installer menu:

  Enter choice [0-9]: 8

  Installed agents: agent-01, agent-02
  Enter agent node names to uninstall (comma-separated): agent-02

  Stopping easytask-agent@agent-02...
  Removed: ~/easytask/config/agents/env_agent-02
  Uninstalled: agent-02
  Agent uninstall complete.

Next Steps¶

With your agents installed and running:

Install Integration Server — Set up system integrations: Host Setup → Step 4
Configure Workflows — Start creating tasks and schedules in the web console
Configure Autostart — Ensure agents start on boot: Post-Installation Setup

Frequently Asked Questions¶

Can I install agents without the full infrastructure? No. Agents require access to the message broker (KeyDB) and secrets store (OpenBao) to function. Install the infrastructure first via Host Setup.

Does the agent require Podman? No. The agent runs as a native binary managed by systemd. Podman is only needed for container-based components like the Integration Server.

Can I install agents on the same host as the infrastructure? Yes. The agent binary runs independently from the infrastructure containers and does not conflict.

How do I update an agent? Re-run Option 3 with the same node name. The installer will download the latest binary and restart the service.