Agent endpoint

The agent exposes a REST service to the Controller, which is consumed by the controller to execute Keywords. The endpoint of this service is called agent endpoint. The agent endpoint is configured automatically at agent startup and is communicated to the controller at registration. If required, the endpoint can be tweaked as follow:

Agent port

Per default the agent lets the system find a free port automatically at startup to listen on. If required you can set the agent port explicitly using the parameter agentPort. The agent service would then run on that specific port.

For example :

# Configure the agent to listen on port 8080
agentPort: 8080

Agent host

Per default the hostname of the agent endpoint is determined automatically at agent startup. If required you can set the agent hostname explicitly using the parameter agentHost.

For example :

# Configure the agent to be called by the controller using the hostname agent-host.mynetwork.net
agentHost: agent-host.mynetwork.net

Agent URL

Per default the URL of the endpoint which is communicated to the controller is built as follow: http://<agentHost>:<agentPort>. If required (if your agent is behind a proxy for instance), you can set the URL of the agent endpoint explicitly using the parameter agentUrl:

For examples :

agentUrl: https://myAgentHost:7000
agentUrl: http://192.168.10.50:8888

SSL

Per default the agent exposes its service as plain HTTP. If required you can enable SSL for the agent service using the parameter ssl.

Before enabling SSL for the agent service you will need a valid SSL certificate for your agent endpoint. You can either use a self-signed certificate or obtain it from a certificate authority (CA).

In both cases you’ll get following files:

• the private key file (.key)
• the certificate file (.cert)

The agent requires the certificate in a Java KeyStore in JKS format. To generate the JKS KeyStore based on your .key and .cert files, follow the steps described here

As soon as you have your certificate in JKS format as a .jks file you can enable SSL for the agent service using following parameters:

ssl: true
keyStorePath: /path/to/cert.jks
keyStorePassword: '<password>' // The password for the key store used at key store generation
keyManagerPassword: '<password>' // The password for the specific key within the key store used at key store generation

Agent tokens

As described here in more detail, Keywords are executed on so-called agent tokens. On agent can emit multiple groups of agent tokens. The token groups are configured using the parameter tokenGroups. Each token group has its own number of tokens (capacity) and attributes. The following paragraphs explain the configuration of token groups.

Capacity

The number of agent tokens emitted by a token group is defined by the parameter capacity. This parameter defines how many tokens have to be made available to the controller for Keyword execution and thus defines the maximal number of parallel keyword executions to be allowed on the agent for a specific group. Set this value according to the resources of your agent:

For example :

# Defines 1 token group with 200 tokens
tokenGroups:
- capacity: 200
  tokenConf:
    attributes:
    properties: 

Attributes

As described here, specific agent tokens can be selected for execution using so-called agent attributes. The agent attributes are defined as key-value pairs in the parameter tokenConf.attributes.

For example, we could define a pool of “Windows” agents by setting an “OS” attribute like below :

tokenGroups:
- capacity: 1
  tokenConf:
    attributes:
      OS: Windows

On that example, the OS attribute can be used to route the workload on specific machines hosting this agent, enabling the ability to choose where to run test plans (see this link)

Grid connection

When the agent downloads the files required for Keyword execution (Automation packages, resources, etc.) from the GRID, transient network issues can occur — for instance the grid being momentarily unreachable, a connection being reset, or a slow/unresponsive endpoint. The following parameters control the connection/read timeouts and the automatic retry behaviour for these file transfers. They apply to both the Java and the Node.js agents.

# Timeout in milliseconds to establish a connection to the grid (default 3000)
gridConnectTimeout: 3000
# Maximum time in milliseconds to wait for the next chunk of data once connected, i.e. an
# inactivity timeout that is reset every time data is received (not a total download budget).
# A download therefore only fails if the grid stops sending data for longer than this (default 3000)
gridReadTimeout: 3000
# Maximum number of retries when a download fails with a transient network error (default 3)
gridMaxRetries: 3
# Delay in milliseconds between two retry attempts (default 1000)
gridRetryDelayMs: 1000

On a transient network failure (connection refused, unknown host, connection reset, connect or read timeout), the agent retries the download up to gridMaxRetries times, waiting gridRetryDelayMs between attempts. Server-side errors, such as a non-200 HTTP response, are considered permanent and are not retried.

Configuration placeholders

Placeholders can be used in AgentConf.yaml and AgentConf.json to define dynamic values that have to be set at startup outside the configuration file.

For instance, you might want to set the gridHost at startup. You could achieve this using a placeholder like this in your AgentConf.yaml:

• gridHost: ${myGridHost}

and set the variable myGridHost in the startup script startAgent.bat(sh|command):

“%JAVA_PATH%java.exe” %JAVA_OPTS% -cp “..\lib*;” step.controller.ControllerServer -config=../conf/step.properties -myGridHost=http://mygridhost.net:8081

Agent working directory

The agent stores the runtime data it produces (most notably its local file cache) under a dedicated working directory defined by the parameter workingDir.

# Working directory of the agent, relative to the directory the agent is started from
workingDir: ../work

Relative paths are resolved against the directory the agent is started from, which is agent/bin resulting in following file structure with the default configuration:

agent/
├── bin
├── work : the agent working directory
├──── filemanager : local cache of the files downloaded from the controller or grid proxy

If workingDir is not set, the agent falls back to the directory it was started from, which means the cache ends up in agent/bin/filemanager.

The structure above applies to the Java and .NET agents (the .NET agent additionally uses a .tmp folder for its sessions, and workingDir is mandatory). The Node.js agent uses its working directory only for the npm project workspaces: its file cache is located independently, under fileManagerConfiguration.path (see Node.js agent file manager).

Agent cleanup configuration

Agents keep the files required for Keyword executions on their local filesystem, to avoid downloading or preparing them again for every execution. What is kept and how it is cleaned up depends on the type of agent, and determines how much disk space the agent requires: refer to File cache storage sizing to size the storage of the agent accordingly.

Java agent

There are 2 caching mechanism in place with automatic cleanup provided out of the box. While their configuration is distinct, it is important to understand that files stored in the file manager cannot be cleanup as long as they are used by the execution context cache. The default configuration is meant for optimal performance, reducing the timeToLive can decrease the execution throughput as well as increase the resource consumption on both the agent and controller (network, CPU and memory).

The cleanup settings below also determine how much disk space the agent requires: the shorter the time to live, the fewer files are kept simultaneously.

File Manager cleanup configuration

When the controller needs to transfer files to an agent for the execution of keywords, these file are cached locally on the agents to improve performance. The agent stores this cache in a folder named filemanager underneath its working directory. This cache is automatically cleaned up, but following properties can be customized in the agent configuration to tweak this behaviour.

fileManagerConfiguration:
  # enable or disable the cleanup (true by default)
  enableCleanup: true
  # define file that are eligible for cleanup based on their last access time (default 1440 minutes).
  # When set to 0, files are cleaned up as soon as they're not used anymore without waiting for the clean up job (also see execution context cache cleanup)
  cleanupTimeToLiveMinutes: 1440
  # define the frequency of the cleanup job in minutes (default 60)
  cleanupFrequencyMinutes: 60

Execution context cache cleanup configuration

For the execution of Keywords on the Java agent, the keywords package (JAR files) must be loaded in the context of the agent process. For performance reason, these package are cached in the so-called execution context cache. This cache is automatically cleaned up, but following properties can be customized in the agent configuration to tweak this behaviour.

executionContextCacheConfiguration:
  # enable or disable the cleanup (true by default)
  enableCleanup: true
  # define file that are eligible for cleanup based on their last access time (default 1440 minutes).
  # When set to 0, files are cleaned up as soon as they're not used anymore without waiting for the clean up job (also see execution context cache cleanup)
  cleanupTimeToLiveMinutes: 1440
  # define the frequency of the cleanup job in minutes (default 60)
  cleanupFrequencyMinutes: 60

Node.js agent

The Node.js agent keeps two kinds of data on its filesystem: the files downloaded from the controller, and the npm project workspaces in which the Keywords are executed.

File manager

The files downloaded from the controller (the Keyword projects) are cached in the folder <path>/work/, where <path> is defined by the parameter fileManagerConfiguration.path (default filemanager, relative to the directory the agent is started from). Unlike for the Java and .NET agents, this location does not depend on the agent working directory.

fileManagerConfiguration:
  # Folder of the file manager cache, relative to the directory the agent is started from (default filemanager)
  path: filemanager

This cache has no automatic cleanup: the cleanup parameters of the Java agent (enableCleanup, cleanupTimeToLiveMinutes, cleanupFrequencyMinutes) are ignored. One copy of each version of the Keyword projects executed is kept until the agent is restarted, the cache folder being emptied at each start of the agent.

Project workspace cleanup configuration

Before executing a JavaScript / TypeScript Keyword, the agent copies its Node.js project into a dedicated workspace and installs the project’s dependencies there (see Execution on the Node.js agent). The workspaces are created in a folder named npm-project-workspaces underneath the agent working directory, one per agent token and per version of the Keyword project, and are kept after the execution so that subsequent executions of the same project on the same token can reuse them without reinstalling the dependencies.

Unused workspaces are deleted by a cleanup job once they have been idle for the time defined by the parameter npmProjectWorkspaceCleanupIdleTimeMs:

# Time in milliseconds after which an unused npm project workspace is deleted (default 3600000 = 1 hour).
# The cleanup job runs at the same interval, a workspace is therefore deleted between 1x and 2x this time after its last use.
npmProjectWorkspaceCleanupIdleTimeMs: 3600000

.NET agent

The .NET agent caches the files downloaded from the controller (Keyword DLLs and their libraries) in a folder named filemanager underneath its working directory.

This cache has no automatic cleanup and the fileManagerConfiguration parameters of the Java agent are ignored: one copy of each version of the files executed is kept until the agent is restarted. The filemanager folder, as well as the temporary folder .tmp underneath the working directory, are emptied at each start of the agent.

The session folders created by the worker processes in .tmp are deleted when their session is closed.

Agents kubernetes probes

If you are running Kubernetes or any other platform for managing containerized workloads and services, you could use:

• the /running API endpoint as a liveness probe (the Agent process is running)
• the /registered API endpoint as a readiness probe (the Agent has successfully registered to the Step GRID)

Below an example of what your Kubernetes manifest could contain:

livenessProbe:
  httpGet:
    path: /running
    port: 12345
  initialDelaySeconds: 5
  periodSeconds: 5
readinessProbe:
  httpGet:
    path: /registered
    port: 12345
  initialDelaySeconds: 10
  periodSeconds: 5

Exposing JVM metrics for prometheus endpoints

It is possible to expose the default JVM metrics using the Prometheus format by adding the below parameter to your Agent configuration file:

exposeMetrics: true

The metrics will then be exposed under the /metrics path on the same port the Agent is running.

Forked Agent Mode (Java Agent Only)

Availability: Step 29+
Scope: Java Agent only (not supported by .NET or Node.js agents)

Overview

By default, the Java Agent executes all Keywords (automation scripts) inside a single JVM, isolating sessions with per-session classloaders for maximum performance.
However, this in-process mode can lead to:

• Potential JVM leaks (threads, static objects) if Keywords don’t clean up their resources properly,
• Side effects from shared singletons or global state,
• Framework incompatibilities where libraries expect the JVM to terminate (e.g., deleteOnExit or shutdown hooks).

Forked Agent Mode provides process-level isolation: each Keyword session runs in its own JVM (a forked agent) that starts on demand and shuts down at the end of the session.

Benefits:

• Resources are fully reclaimed on JVM exit (leak containment),
• Frameworks depending on JVM shutdown behave correctly,
• Sessions are isolated from each other (no shared static state).

Trade-off: higher startup overhead per session compared to the default, classloader-based mode.

Configuration

Enabling the Forked Agent Mode

To enable the Forked Agent Mode, update your AgentConf.yaml add the following to your AgentConf.yaml:

agentForker:
  enabled: true

When enabled, the agent spawns a dedicated JVM for each Keyword session and terminates it after completion. The default configuration should work by default and suit the common needs. For advanced configuration of the forked agent mode, a comprehensive list of the configuration parameters is provided in the following section.

Configuration reference

All settings live under agentForker.

Example

agentForker:
  enabled: true
  javaPath: /usr/lib/jvm/java-17/bin/java
  vmArgs: "-Xmx512m -Dfile.encoding=UTF-8"
  agentConf: /opt/step/conf/agent-forked.yaml
  logbackConf: /opt/step/conf/logback-forked.xml
  startTimeoutMs: 20000
  shutdownTimeoutMs: 10000
  callTimeoutOffsetMs: 1000
  gridPort: 0
  agentPortRangeStart: 50000
  agentPortRangeEnd: 50100
  tempDirectoryDeletionRetryWait: 100
  workingDirectory: work/forked-agents

File caching in forked mode

When the Forked Agent Mode is enabled, all Keyword sessions run in ephemeral forked agents (separate JVMs).

Rather than having every forked JVM download the resource files required for keyword execution from the controller (or grid proxy), the forked agents fetch them from their main agent. The main agent downloads each file from the controller once, caches it, and serves it to all the forked agents it spawns, reducing load on the controller, network and speeding up keyword executions. Each forked agent keeps its own copy under its temporary execution directory, which is removed when the forked agent terminates.

The same agent file cleanup configuration applies, be aware that turning ON/OFF the Forked Agent Mode will invalidate the existing cache.

The execution directories of the forked agents are created under agentForker.workingDirectory, which is subject to the same exclusive ownership rule as the main agent working directory: it must not be shared between two agent processes, and any leftover execution directories found there are cleaned up at startup.

Forked keyword process (Node.js Agent Only)

Scope: Node.js agent only

Unlike the Java agent, for which forking is an option (see Forked Agent Mode), the Node.js agent always executes Keywords in a forked Node.js process: each token session gets its own child process, which is shut down when the session is released.

Session release and shutdown sequence

When a token is released, the agent asks the forked process to dispose of the resources of its session (browsers, connections, and any other object registered in the session) and to exit. Because a Keyword or a session resource may hang while being released — a browser that never closes, a connection that never times out — the agent never waits indefinitely for the forked process and escalates instead:

1. The agent asks the forked process to release its session and exit, and waits up to shutdownTimeoutMs for it to terminate on its own.
2. If the process is still alive after that, it is terminated with SIGTERM, and the token release reports an error stating that the forked keyword process had to be terminated. This usually means that a Keyword or a session resource did not release properly.
3. If the process survives SIGTERM for terminationGracePeriodMs, it is killed with SIGKILL.
4. If it survives SIGKILL for another terminationGracePeriodMs, the agent gives up waiting and logs an error. The token is released in any case: a stuck forked process can never block the release of its token.

Any error raised while the session resources were being disposed of is reported on the token release as well, so that a failing resource release does not go unnoticed.

Configuration reference

These settings live under agentForker, the same configuration block as for the Java agent, but the parameters below are the only ones taken into account by the Node.js agent:

Example

agentForker:
  shutdownTimeoutMs: 40000
  terminationGracePeriodMs: 5000

Advanced configuration

Exposing agent services

In some advanced scenarios, users may need to control the agent from within a Keyword. To accommodate this, the Java agent can optionally expose internal agent control services to Keywords.

Supported operations

Currently, the only supported operation is the graceful shutdown of the agent. This allows controlled termination of the agent process from within a Keyword. Additional control operations may be introduced in future versions.

Note: This functionality is currently only available in the Java agent. The .NET and Node.js agents do not support this capability at this time.

Enabling Agent Control Services

By default, the agent control services are not exposed to Keywords for safety and encapsulation reasons. To enable this feature, set the following property in the agent configuration file:

exposeAgentControlServices: true

Usage Example (Java + step-api 1.4+)

Once enabled, the agent control service can be accessed within a Java Keyword using the TokenSession:

tokenSession.get(AgentControlServices.class).shutdownAgent();

This will gracefully shut down the running agent instance. Version requirement: This feature requires step-api version 1.4 or newer.