Exekra Platform Documentation

Exekra is an on-premise robotic process automation (RPA) platform for building, deploying, and managing automated workflows across an organization. It provides a centralized orchestration server, distributed execution agents, and a visual workflow designer for defining automation processes without writing code.

Exekra automates repetitive tasks involving desktop applications, web browsers, files, databases, APIs, and email systems. It enables organizations to define structured workflows, schedule their execution, and monitor results from a single management interface.

All data (workflow definitions, execution logs, credentials, and configuration) remains on-premise. The platform does not require internet access for day-to-day operation. License validation occurs once during activation; subsequent operation is fully offline.

Hub vs. Runner

Architecture Overview

System Diagram

                    +------------------------------------------+
                    |           Exekra Hub          |
                    |              (Windows Service)            |
                    |                                          |
                    |  +----------------+  +----------------+  |
                    |  |   Frontend     |  |    Backend     |  |
                    |  |   (Next.js)    |  |   (Fastify)    |  |
                    |  |   HTTPS:4545   |  |   HTTP:5000    |  |
                    |  +-------+--------+  +-------+--------+  |
                    |          |    API proxy /api/  |          |
                    |          +--------------------+          |
                    +------------|----------------------------|+
                                 |                            |
                    +------------v---+              +---------v------+
                    |  PostgreSQL    |              |     Redis      |
                    |  (Database)    |              |   (Queue)      |
                    +----------------+              +----------------+

     +-------------------+-------------------+-------------------+
     |                   |                   |                   |
+----v-----+       +----v-----+       +----v-----+       +----v-----+
|  Runner  |       |  Runner  |       |  Runner  |       |  Runner  |
|    #1    |       |    #2    |       |    #3    |       |    #4    |
+----------+       +----------+       +----------+       +----------+

Component Responsibilities

Hub

The hub is the central management server. It provides the web interface (dashboard, workflow management, runner monitoring), REST API, workflow storage, execution scheduling via cron and webhooks, runner management (registration, authentication, health monitoring, work assignment), license enforcement, and audit logging.

Runner

The runner is an Electron-based desktop agent that executes workflows on Windows machines. It authenticates with the Hub, sends heartbeats every 30 seconds, polls for assigned work every 5 seconds, and reports execution results including logs and performance metrics.

Database (PostgreSQL)

Stores all persistent state: users, workflows, versions, executions, runners, triggers, license data (encrypted), and audit logs.

Redis

Provides the execution queue via BullMQ. Decouples execution creation from runner assignment with 5 concurrent workers, exponential backoff retry (3 attempts), and automatic fallback to direct assignment if Redis is unavailable.

Execution Modes

Execution Flow Summary

1. A user, schedule, or webhook creates an execution request
2. The Hub validates the license and retrieves the published workflow version
3. The execution is placed in the BullMQ queue with status QUEUED
4. A queue worker finds an available runner and assigns the execution
5. The runner picks up the assignment on its next poll cycle (every 5 seconds)
6. The runner executes the workflow graph node-by-node, buffering logs
7. On completion, the runner sends the final status, logs, and metrics to the Hub

Core Concepts

Workflow

A named automation process composed of a directed graph of activities. Workflows are versioned. Each version holds the graph definition.

Draft

An unpublished workflow version. Users can continue editing and saving drafts. Multiple drafts may exist, but only the latest is editable. Drafts cannot be executed by triggers.

Version

A numbered snapshot of a workflow's graph definition. Each save creates a new version with an auto-incrementing number. All versions are retained for audit.

Release (Publishing)

Publishing promotes the latest draft to a published version. Only one version per workflow can be published at any time. Published versions are immutable.

Environment

Deployment stages for workflow promotion (Development, Staging, Production). Achieved by deploying separate hub instances or by runner labeling.

Execution

A single run of a published workflow version on a specific runner. Statuses: QUEUED, ASSIGNED, RUNNING, COMPLETED, FAILED, STOPPED.

Trigger

Defines how a workflow execution is initiated: Manual (user/API), Schedule (cron expression), or Webhook (external HTTP POST).

Runner

A registered execution agent. Statuses: ONLINE (available), BUSY (executing), OFFLINE (no heartbeat for 120 seconds).

Execution Modes

Runners can execute workflows interactively (user clicks Run in Studio) or in the background via scheduled triggers, webhooks, or API calls. The license enforces a total runner limit for the organization.

Installation Guide

This guide walks you through setting up the complete Exekra platform, from installing prerequisites to connecting your first runner. Follow the steps in order.

Prerequisites

Before installing the Hub, you need two services running and accessible on your network. These can be on the same server as the Hub or on separate machines.

1. PostgreSQL Database

PostgreSQL stores all Hub data including workflows, executions, users, licenses, and audit logs. Version 14 or later is required.

Installation on Windows:

• Download from postgresql.org/download/windows
• Run the installer and follow the wizard
• Choose a password for the postgres superuser
• Keep the default port (5432) and select UTF-8 encoding

After installation, create the database:

psql -U postgres
CREATE DATABASE exekra_hub;
\q

Your connection string will look like: postgresql://postgres:yourpassword@localhost:5432/exekra_hub

2. Redis

Redis powers the job queue (BullMQ) used for scheduling triggers and assigning workflow executions to runners. Version 6 or later is required.

Installation on Windows (choose one):

Option A: Memurai (recommended for Windows)

• Download from memurai.com/get-memurai
• Run the installer. Memurai runs as a Windows service automatically

Option B: Redis via WSL2

wsl --install
sudo apt update && sudo apt install redis-server
sudo service redis-server start

Option C: Docker

docker run -d --name redis -p 6379:6379 redis:7-alpine

Your connection string will look like: redis://localhost:6379

Verify Prerequisites

Before proceeding, confirm both services are running:

PostgreSQL:

psql -U postgres -h localhost -d exekra_hub -c "SELECT 1;"

Redis:

redis-cli ping

Expected output: PONG

Hub Installation

System Requirements

Step-by-Step Installation

Step 1: Download the Hub installer from the Exekra License Portal (Downloads page) or from the link provided by your administrator.

Step 2: Right-click the installer and select Run as Administrator.

Step 3: Accept the license agreement and choose the installation directory. The default is C:\Program Files\Exekra\Hub.

Step 4: Enter your database and Redis connection details:

Step 5: The installer will automatically:

• Generate TLS certificates for HTTPS
• Generate encryption keys for secure data storage
• Run database migrations to create the required tables
• Install and start the Hub as a Windows service (ExekraHubService)

Step 6: Open your browser and navigate to https://localhost:4545 (or the custom port you chose).

First-Time Activation

When you first open the Hub, you'll see the activation screen. Upload your .lic license file (downloaded from the License Portal). After activation, create your admin account password and sign in.

Service Management

Common commands for managing the Hub Windows service:

sc query ExekraHubService
nssm stop ExekraHubService
nssm start ExekraHubService
nssm restart ExekraHubService

Logs are stored in the installation directory under the logs/ folder.

Runner Installation

System Requirements

Step-by-Step Installation

Step 1: Download the Runner installer from the License Portal (Downloads page) or the Hub dashboard.

Step 2: Run the installer and follow the setup wizard. The default install directory is C:\Program Files\Exekra\Runner.

Step 3: Launch Exekra Runner from the Start Menu or Desktop shortcut.

Connecting to the Hub

Step 4: In the Hub dashboard, go to Runners > Register Runner.

Step 5: Enter a name for the runner and click Register. The Hub will generate a Machine Key and Machine Secret.

Step 6: In the Runner application, enter:

Step 7: Click Connect. The runner should show as Online in the Hub's Runners page within a few seconds.

Running as a Background Service

For unattended automation, you can configure the Runner to start automatically with Windows. The Runner tray icon stays in the system tray and maintains the connection to the Hub. Workflows assigned to this runner will execute automatically without user interaction.

Browser Extension (Optional)

The browser extension enables element selection and recording for web automation activities. It is only needed on machines where you design workflows, not on runner-only machines.

Installation:

• Open Chrome and navigate to chrome://extensions
• Enable "Developer mode" in the top right
• Click "Load unpacked" and select the extension folder from the Hub installation directory
• The Exekra icon should appear in the browser toolbar

License Renewal

When your license expires, the Hub will display a banner and workflow executions will be disabled. To renew:

• Contact Exekra sales or your account manager to request a renewal
• Once renewed, download the new .lic file from the License Portal
• In the Hub, go to the License page and upload the new file
• The Hub will reactivate immediately. No restart required

Upgrading

To upgrade the Hub or Runner to a new version, download the latest installer and run it. The installer will detect the existing installation and upgrade in place. Your data, configuration, and license are preserved. It is recommended to stop the Hub service before upgrading.

nssm stop ExekraHubService
:: Run the new installer
nssm start ExekraHubService

Exekra Studio Guide

Exekra Studio is a browser-based visual editor for building automation workflows. It uses a canvas-based interface powered by React Flow where users drag activities from a toolbox, connect them with edges, and configure their properties.

Activities

Exekra includes over 50 activities across 17 categories:

Expressions and Variables

Variables store data flowing between activities. Reference variables in any input field using curly braces: {variableName}. The expression editor provides variable suggestions and a multiline editor.

Browser Recording

Click Record in the toolbar, enter a target URL, and interact with the page normally. The extension captures clicks, typing, dropdown selections, and navigation, converting each action into a workflow activity with multi-layered selectors (CSS, XPath, anchors) for reliable replay. Password fields are automatically masked.

Publishing

Click Publish to promote the latest draft. The new version receives an auto-incremented version number and becomes the version used by all triggers and execution requests. Previous versions are retained for audit and rollback.

Versioning and Environments

Draft vs. Published

Every save creates a version record. Drafts (published=false) represent work in progress. Publishing locks the version. It cannot be modified, only superseded by publishing a newer draft. All versions are retained for audit and rollback.

Environment Isolation

The recommended approach for strict separation is deploying separate hub instances for Development, Staging, and Production. Each instance has its own database, runners, and license. Workflows are promoted between environments by exporting the graph definition and importing it into the next environment.

Rollback Strategy

If a published version causes failures: 1. Disable all triggers for the workflow. 2. Wait for in-flight executions to complete. 3. Load a previous version's graph definition, save as a new draft, and publish. 4. Validate with a test run. 5. Re-enable triggers.

Runners

How Runners Work

Runners execute workflows either interactively (triggered from Studio) or in the background (scheduled triggers, webhooks, API calls). All runners use the same priority-based execution queue with duplicate detection.

Registration

Administrators register runners via the Hub. The system generates a Machine Key (FC-prefix) and Machine Secret (64 hex chars). The secret is hashed with bcrypt before storage and shown only once. The license enforces a total runner limit for the organization.

Heartbeat and Polling

Runners send heartbeats every 30 seconds with CPU, memory, and disk metrics. Runners with no heartbeat for 120 seconds are marked OFFLINE. Runners poll for assigned work every 5 seconds. Polling pauses during execution.

Failure Handling

Trigger Engine

Schedule Triggers (Cron)

Execute workflows at specified intervals using standard cron expressions. Cron jobs run in-memory using node-cron and are rebuilt on hub startup. Updating a schedule trigger restarts the cron job with the new expression.

Webhook Triggers

Expose unique HTTP endpoints for external systems. Endpoint format: POST /api/triggers/webhook/{triggerId}. The endpoint is public (no authentication required). Disabled triggers reject incoming requests with a 400 error.

Retry Model

Queue-level: 3 attempts with exponential backoff (1s, 2s, 4s). Execution-level: one automatic re-queue if a runner goes offline during ASSIGNED state. No automatic retry of failed executions at the trigger level.

Execution Lifecycle

State Transitions

QUEUED ──> ASSIGNED ──> RUNNING ──> COMPLETED
  |            |            |
  v            v            v
FAILED      FAILED       FAILED
                            |
                            v
                         STOPPED

Stale Execution Handling

A background job runs every 60 seconds to detect stale executions:

Performance Metrics

Each execution records CPU average/peak and memory average/peak, sampled every 5 seconds on the runner and included in the final status report.

Security Model

On-Premise Data Isolation

All data remains within the organization's network. No data is transmitted to external servers during normal operation. The only external communication occurs during initial license activation.

Authentication

Web users authenticate via email/password with JWT tokens (HS256, 7-day expiry) stored in HTTP-only secure cookies. Runners authenticate via machine credentials (Machine Key + Machine Secret) and receive 24-hour JWT tokens with automatic refresh.

Role-Based Access Control

Encryption

Passwords: bcrypt (12 rounds). Machine secrets: bcrypt (12 rounds). License data: AES-256-GCM with per-installation key. Transport: TLS with organization-provided certificates. JWT signing: HS256 with 48-character generated secret.

Audit Logging

All administrative actions (user creation, runner registration, workflow publishing, license activation) are recorded with user ID, action, resource, IP address, and timestamp.

Administration Guide

Initial Setup

After installation: 1. Activate the license on the activation page. 2. Create the initial admin account on the bootstrap page (email must match the license). 3. Log in and access the dashboard.

Managing Users

Administrators create users with email, password, name, and role (ADMIN, DEVELOPER, or OPERATOR). Default role is OPERATOR (least privilege). Only administrators can create users and assign roles.

Managing Runners

Register runners from the Runners page. Monitor status, metrics, and connectivity. Rotate credentials with Regenerate Secret if compromised (immediately invalidates the previous secret).

Backup Strategy

Primary: Regular PostgreSQL backups (pg_dump or WAL archiving). Configuration: Back up hub-config.json, .env, and TLS certificates. Redis: Transient data, no backup required. Disaster recovery: Install hub on new machine, restore database, runners reconnect automatically.

Browser Extension

The Exekra Browser Extension is a Chrome extension (Manifest V3) that enables element selection, interaction recording, and table extraction for browser automation workflows. It communicates with the Exekra Studio canvas via a page-context bridge API.

Installation

Load the extension as an unpacked extension in Chrome from the hub's browser-extension directory. The extension requires the following permissions:

Host permissions are set to all URLs to support automation across any website. The extension is externally connectable only from localhost origins for secure communication with Exekra Studio.

Selector Capture Model

When the user activates element selection from Exekra Studio, the extension generates multiple selector candidates for the target element using a priority-based strategy:

Each generated selector is validated against the DOM. Selectors are classified as valid (exactly one match), multiple (more than one match), or invalid (no matches). The extension returns a primary selector, fallback alternatives, and the complete candidate list.

Anchor Detection

When a primary selector is ambiguous (matches multiple elements), the user can select an anchor element to disambiguate. The extension detects the spatial relationship between the target and anchor elements:

Anchors are captured with their type (aria-label, text, or label) and text content, providing a stable reference point for element location during replay.

Recording Mode

The recording mode captures user interactions on a target website and converts them into workflow activities. Exekra Studio initiates recording by specifying a target URL. The extension opens or activates the target tab and begins capturing events.

Captured action types:

Each recorded action includes the complete selector data (CSS, XPath, attributes, anchors, frame path), the action value, page URL, page title, and timestamp. Actions are relayed in real time from the target tab back to the Exekra Studio canvas via the background service worker.

Password Masking

When the recorder detects interaction with a password field (input type="password"), the actual value is replaced with the placeholder string{{credential}} before transmission. The original password value is never captured, stored, or transmitted. A boolean flag marks the action as password-related for the workflow engine to handle credential injection at runtime.

Frame and Iframe Handling

The extension traverses the window hierarchy from the current frame to the top-level document, building an array of selectors for each iframe in the path. This frame path is included in the selector data, enabling the runner to navigate through nested iframes during workflow execution. Cross-origin frame exceptions are handled gracefully.

Table Extraction

The extension detects and extracts structured data from tables on the page. Supported table types:

Extracted data includes the table selector, row selector pattern, column definitions with header and cell selectors, a preview of the first 5 rows, and total row/column counts.

Communication Architecture

The extension exposes a window.Exekra API to the page context via an injected bridge script. Exekra Studio calls this API to initiate selection, recording, and table extraction. Messages flow through three layers:

Exekra Studio (Canvas)
    ↕  window.postMessage()
Bridge Script (Page Context)
    ↕  chrome.runtime.sendMessage()
Background Service Worker
    ↕  chrome.tabs.sendMessage()
Content Script (Target Tab)

The bridge script is declared as a web-accessible resource and only responds to messages from localhost origins, preventing external websites from invoking extension functionality.

Scaling and Performance

Exekra scales execution capacity by adding runners. The hub remains a single instance that manages work distribution through a Redis-backed queue. This section covers the infrastructure considerations for scaling deployments.

Horizontal Scaling with Runners

Each runner provides one concurrent execution slot. To increase throughput, register additional runners on dedicated machines. The hub assigns work to runners automatically based on availability. Runners with the most recent heartbeat are preferred.

Redis Queue Architecture

The execution queue is implemented with BullMQ backed by Redis. Configuration:

The queue decouples execution creation from runner assignment. If Redis becomes unavailable, the system falls back to direct runner assignment with reduced functionality. Redis connection uses lazy connect with up to 3 retry attempts and incremental backoff (500ms increments, max 3s).

Runner Assignment Algorithm

When a queue worker processes an execution job, it selects a runner using the following criteria:

1. Filter runners by status = ONLINE
2. Filter by runner type (if specified)
3. Order by lastSeen DESC (most recently active first)
4. Select first available runner
5. Mark runner as BUSY (prevents double-assignment)
6. Runner picks up work on next poll cycle (every 5 seconds)

If no runner is available, the queue job throws an error and BullMQ retries with exponential backoff. After 3 failed attempts, the execution remains QUEUED until the stale execution check marks it FAILED (10-minute timeout).

Rate Limiting

The API enforces a global rate limit of 100 requests per minute per client via Fastify rate limiting. Runner operational endpoints (heartbeat, poll, authenticate, execution status updates) are exempt from rate limiting to prevent interference with execution flow.

Database Performance

The hub uses Prisma ORM with a global singleton PrismaClient instance and PostgreSQL's built-in connection pooling. Recommendations for production deployments:

Periodic Background Tasks

The hub runs maintenance tasks at fixed intervals:

High Availability Considerations

The current architecture uses a single hub instance. For high availability:

Runners are stateless between executions and reconnect automatically when the hub becomes available. Executions that were in-flight during an outage are handled by the stale execution check on restart.

Performance Metrics

Each execution records resource utilization sampled every 5 seconds on the runner: CPU average and peak (percentage), memory average and peak (megabytes). Runner heartbeats include real-time CPU, memory, and disk metrics. These metrics are available via the dashboard and the /api/analytics/process-performance endpoint for capacity planning.

Troubleshooting

Runner Not Connecting

Verify the hub URL (including protocol and port). Test network connectivity with curl to /api/health. Check machine credentials match the registered values. Review runner logs for specific errors (401, ECONNREFUSED, ETIMEDOUT).

Workflow Not Executing

Check for available ONLINE runners. Ensure the workflow has a published version. Verify the license status is ACTIVE or GRACE_PERIOD. Check Redis connectivity for queue processing.

Trigger Not Firing

Verify the trigger is enabled. For schedules: validate the cron expression and check the hub's system clock. For webhooks: test the URL with curl and check firewall rules.

Database Connection Issues

Verify PostgreSQL is running (pg_isready). Check the DATABASE_URL in .env. Test direct connectivity with psql. Check firewall rules between hub and database servers. Run Prisma migrations manually if the schema is missing.

Execution Stuck in Pending

The stale execution check runs every 60 seconds. Ensure runners are ONLINE. Check Redis connectivity. QUEUED executions are marked FAILED after 10 minutes. ASSIGNED executions with offline runners are re-queued after 5 minutes.

Service Fails to Start

Check service-stderr.log for errors. Common causes: port in use, missing Node.js binary, missing TLS certificates, invalid configuration. Test manually by running launcher.js directly.

FAQ

Can the system run without internet access?

Yes. After initial license activation, the platform operates entirely offline. All components run within the organization's network.

How are workflows versioned?

Each save creates a new version with an auto-incrementing number. Versions are classified as draft (in-progress) or published (executable). Only one version per workflow can be published at any time. All versions are retained for audit and rollback.

Can production be isolated from development?

Yes. Deploy separate hub instances for each environment, each with its own database, runners, and license. Promote workflows by exporting and importing graph definitions.

How does scaling work?

Add more runners to increase execution capacity. The hub assigns work automatically. Each runner adds one concurrent execution slot.

What happens if a runner goes offline?

ASSIGNED executions are re-queued once. RUNNING executions get a 5-minute grace period. If the runner does not recover, executions are marked FAILED. The runner reconnects automatically when network connectivity is restored.

Can multiple workflows run simultaneously?

Yes, with N online runners, up to N workflows can execute concurrently.

How are runner credentials stored?

On the hub: bcrypt-hashed. On the runner: encrypted via Windows Credential Manager (Electron safe storage).

Does the platform support SSO?

The current version uses built-in email/password authentication. SSO integration (SAML, OIDC) is not available in this release.

What is the backup strategy?

Primary: regular PostgreSQL backups. Configuration files (hub-config.json, .env, TLS certs) should be backed up separately. Redis data is transient and does not require backup.

Can I migrate the hub to a new server?

Yes. Back up the database and configuration files, install on the new server with the same configuration, restore the database. Runners reconnect automatically if the access URL remains the same.

What is the maximum execution duration?

No hard timeout. If a runner goes offline during execution and does not recover within 5 minutes, the execution is marked FAILED.

How is the license protected from tampering?

License data is signed with RSA-SHA256 and encrypted at rest with AES-256-GCM. The authentication tag detects any modification of the encrypted data.