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.

Orchestrator vs. Runner

Architecture Overview

System Diagram

                    +------------------------------------------+
                    |           Exekra Orchestrator          |
                    |              (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  |
| Attended |       |Unattended|       |Unattended|       | Attended |
+----------+       +----------+       +----------+       +----------+

Component Responsibilities

Orchestrator

The orchestrator 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 workstations. It authenticates with the orchestrator, sends heartbeats every 30 seconds, polls for work every 5 seconds (unattended mode), 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.

Attended vs. Unattended Execution

Execution Flow Summary

1. A user, schedule, or webhook creates an execution request. 2. The orchestrator 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 orchestrator.

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 orchestrator 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).

Attended vs. Unattended

Attended runners operate on user workstations with interactive feedback. Unattended runners operate in the background with automatic work assignment and priority queuing. The license enforces separate limits for each type.

Installation Guide

Orchestrator System Requirements

Windows Installation Steps

1. Run the installer as administrator. 2. Accept the license agreement and choose the installation directory. 3. Configure Database and Redis — enter the PostgreSQL and Redis connection URLs. 4. Configure Network — enter the access URL, HTTPS port, and backend port. 5. Provide TLS Certificate — browse to select the certificate and private key files. 6. The installer validates connectivity to PostgreSQL and Redis, and verifies the certificate files. 7. Installation extracts files, generates secrets, copies certificates, runs database migrations, and installs the Windows service. 8. Open the orchestrator in a browser at the configured Access URL.

Service Management

# Check service status
sc query ExekraOrchestratorService

# Stop / Start / Restart
nssm stop ExekraOrchestratorService
nssm start ExekraOrchestratorService
nssm restart ExekraOrchestratorService

Runner Installation

Install the runner on Windows 10/11 workstations. Register the runner in the orchestrator web interface (Runners > Register Runner), selecting Attended or Unattended type. Copy the generated Machine Key and Machine Secret to the runner application and connect.

Browser Extension

The browser extension enables recording and element selection for browser automation. Load it as an unpacked extension in Chrome from the orchestrator's extension directory. Required permissions: activeTab, scripting, storage, tabs. The extension communicates only with localhost.

Workflow Designer Guide

The Workflow Designer 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 orchestrator 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 an attended runner. 5. Re-enable triggers.

Runners

Runner Types

Attended runners operate on user workstations with interactive feedback. Unattended runners operate in the background with automatic work assignment and a priority-based execution queue with duplicate detection.

Registration

Administrators register runners via the orchestrator. 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. License limits are enforced per runner type.

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. Unattended 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 orchestrator 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 orchestrator 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 Workflow Designer canvas via a page-context bridge API.

Installation

Load the extension as an unpacked extension in Chrome from the orchestrator'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 the Workflow Designer.

Selector Capture Model

When the user activates element selection from the Workflow Designer, 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. The Workflow Designer 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 Workflow Designer 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. The Workflow Designer calls this API to initiate selection, recording, and table extraction. Messages flow through three layers:

Workflow Designer (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 orchestrator 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 orchestrator 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 orchestrator uses Prisma ORM with a global singleton PrismaClient instance and PostgreSQL's built-in connection pooling. Recommendations for production deployments:

Periodic Background Tasks

The orchestrator runs maintenance tasks at fixed intervals:

High Availability Considerations

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

Runners are stateless between executions and reconnect automatically when the orchestrator 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 orchestrator 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 orchestrator'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 orchestrator 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 orchestrator 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 orchestrator 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 unattended runners, up to N workflows can execute concurrently.

How are runner credentials stored?

On the orchestrator: 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 orchestrator 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.