Configuration

The E2Engine CLI can be used without creating a configuration file.

Default configuration is applied automatically, allowing the CLI to create resources and run tests with its local execution infrastructure.

Create a configuration file when you need to customize storage, runtime behavior, execution limits, transport, logging, or other operational settings.

Configuration file

E2Engine looks for:

config.yml

in the operating system’s per-user configuration directory for e2engine.

Typical locations are:

Platform	Configuration file
macOS	~/Library/Application Support/e2engine/config.yml
Linux	~/.config/e2engine/config.yml
Linux with XDG_CONFIG_HOME	$XDG_CONFIG_HOME/e2engine/config.yml
Windows	%APPDATA%\e2engine\config.yml

An empty configuration is valid.

All required values are populated from defaults.

Configuration structure

The top-level configuration is organized by responsibility:

output:
  # CLI output settings

logger:
  # logging configuration

db:
  # local repository configuration

runtime:
  # runtime environment and execution settings

scheduler:
  # execution scheduling settings

runner:
  # local runner settings

transport:
  # CLI-to-runner transport

These settings configure the E2Engine application and execution infrastructure. They are separate from portable Environment, Test, and TestSuite specifications.

Output

The output section controls CLI output behavior that applies across commands.

output:
  list_max_size: 50

List maximum size

list_max_size limits the maximum number of items returned by list commands.

The default is:

50

The value must be between 1 and 50.

When a command requests a larger --limit, the requested value is capped at the configured maximum.

For example:

e2engine get tests --limit 100

with:

output:
  list_max_size: 50

returns at most 50 Tests.

The setting can also be supplied through the environment:

E2ENGINE_OUTPUT_LIST_MAX_SIZE=20 e2engine get tests

Database

E2Engine stores resources and execution records in a local SQLite database.

db:
  name: e2engine.sqlite
  driver: sqlite
  max_open_conns: 1
  max_idle_conns: 1

The defaults are:

Setting	Default	Description
name	e2engine.sqlite	SQLite database filename
driver	sqlite	Database driver
max_open_conns	1	Maximum number of open database connections
max_idle_conns	1	Maximum number of idle database connections

Currently, sqlite is the supported database driver.

Data directory

The database is stored in the E2Engine application data directory.

Typical locations are:

Platform	Data directory
macOS	~/Library/Application Support/e2engine
Linux	~/.local/share/e2engine
Linux with XDG_DATA_HOME	$XDG_DATA_HOME/e2engine
Windows	%APPDATA%\e2engine

With the default database configuration, the database file is therefore:

<data-directory>/e2engine.sqlite

The data directory can be overridden with:

E2ENGINE_DATA_DIR

For example:

E2ENGINE_DATA_DIR=./data e2engine get environments

Runtime

The runtime section controls execution-runtime behavior.

runtime:
  environment_cleanup_timeout: 30s
  job_publish_timeout: 30s
  max_resolved_tests: 1000
  service_provider:
    buf_descriptor_loader_token: ""

Environment cleanup timeout

runtime:
  environment_cleanup_timeout: 30s

Controls the timeout used when cleaning up runtime Environments.

The default is:

30s

Job publish timeout

runtime:
  job_publish_timeout: 30s

Controls how long E2Engine waits when publishing execution work to the scheduler.

The default is:

30s

Maximum resolved Tests

runtime:
  max_resolved_tests: 1000

Limits the number of Tests that a TestSuite may resolve before execution.

The default is:

1000

The value must be at least 1.

This provides a safety limit for TestSuites whose selectors match unexpectedly large numbers of Tests.

BUF descriptor loader token

The runtime service provider can be configured with a token used when loading gRPC descriptors from BUF:

runtime:
  service_provider:
    buf_descriptor_loader_token: <token>

For sensitive values such as tokens, prefer supplying the value through the environment rather than storing it directly in config.yml.

Scheduler

The scheduler queues Test execution jobs before they are processed by the runner.

scheduler:
  queue_size: 1024

The default queue size is:

1024

The value must be at least 1.

For most local use, the default does not need to be changed.

Runner

The local runner executes scheduled Tests.

runner:
  workers_pool_size: 8
  cleanup_timeout: 30s
  worker:
    test_timeout: 30s

Worker pool size

runner:
  workers_pool_size: 8

Controls the number of Test jobs that the local runner can process concurrently.

The default is:

8

The value must be at least 1.

This setting is particularly relevant to TestSuite execution, where multiple Tests may execute concurrently.

It can also be configured through the environment:

E2ENGINE_RUNNER_WORKERS_POOL_SIZE=4 \
e2engine run testsuite smoke payment-demo

Cleanup timeout

runner:
  cleanup_timeout: 30s

Controls the timeout used when the runner shuts down and cleans up its execution infrastructure.

The default is:

30s

Test timeout

Each Test has an execution timeout:

runner:
  worker:
    test_timeout: 30s

The default is:

30s

The timeout applies to execution of an individual Test, including its protocol request and evaluation of expected interactions.

Transport

The transport section controls how scheduled execution jobs reach the local runner.

Two transport modes are available:

direct
socket

Direct transport

Direct transport is the default:

transport:
  kind: direct

In direct mode, the runner executes within the CLI process.

CLI
 │
 ▼
Scheduler
 │
 ▼
Local runner

Test and TestSuite execution is synchronous from the CLI user’s perspective: the run command waits for execution to complete before returning.

An address must not be configured for direct transport.

Because direct transport is the default, the transport section can normally be omitted entirely.

Socket transport

Socket transport uses a separate local runner process:

transport:
  kind: socket
  address: localhost:1234

An address is required when kind is socket.

CLI
 │
 ▼
Scheduler
 │
 ▼
Socket transport
 │
 ▼
Runner process

In socket mode, the CLI can return after the execution has been scheduled while execution continues through the runner.

Use the returned execution ID to inspect its current state:

e2engine get testexecution <execution-id>

or:

e2engine get testsuiteexecution <execution-id>

Transport can also be configured through environment variables:

E2ENGINE_TRANSPORT_KIND=socket \
E2ENGINE_TRANSPORT_ADDRESS=localhost:1234 \
e2engine run test successful-payment payment-demo

The transport settings must form a valid combination:

Kind	Address
direct	Must not be specified
socket	Required and must be a valid host:port network address

See Test commands and Test suite commands for the corresponding run commands.

Logging

E2Engine enables logging by default.

Without an explicit logger configuration, E2Engine creates:

• a standard-error sink
• a file sink at debug level

The default log file is:

<data-directory>/e2engine.log

The database and default log file therefore use the same application data directory.

For example, on macOS the defaults are:

~/Library/Application Support/e2engine/e2engine.sqlite
~/Library/Application Support/e2engine/e2engine.log

Logging can be customized with the logger section:

logger:
  app_name: e2engine
  sinks:
    - kind: stderr
      format: text
      level: 0

    - kind: file
      format: text
      level: -4

See Logging for log locations, sinks, formats, levels, custom paths, and troubleshooting.

Environment variables

Configuration fields that support environment binding can be overridden with environment variables.

Variable names use the E2ENGINE_ prefix and reflect the configuration path.

For example:

output.list_max_size
        │
        ▼
E2ENGINE_OUTPUT_LIST_MAX_SIZE

and:

runner.workers_pool_size
        │
        ▼
E2ENGINE_RUNNER_WORKERS_POOL_SIZE

For example:

E2ENGINE_OUTPUT_LIST_MAX_SIZE=20 e2engine get tests

or:

E2ENGINE_RUNNER_WORKERS_POOL_SIZE=4 \
e2engine run testsuite smoke payment-demo

Transport settings can similarly be provided as:

E2ENGINE_TRANSPORT_KIND
E2ENGINE_TRANSPORT_ADDRESS

The data directory has a dedicated override:

E2ENGINE_DATA_DIR

Environment variables are particularly useful in CI/CD and containerized environments, where operational settings can be supplied without modifying config.yml.

Example configuration

A configuration for local execution might look like:

output:
  list_max_size: 50

db:
  name: e2engine.sqlite
  driver: sqlite
  max_open_conns: 1
  max_idle_conns: 1

runtime:
  environment_cleanup_timeout: 30s
  job_publish_timeout: 30s
  max_resolved_tests: 1000

scheduler:
  queue_size: 1024

runner:
  workers_pool_size: 8
  cleanup_timeout: 30s
  worker:
    test_timeout: 30s

transport:
  kind: direct

Most of these values are already defaults, so the equivalent minimal configuration is:

{}

Only settings that differ from the defaults need to be specified.

Configuration and resource specifications

CLI configuration and E2Engine resources serve different purposes.

CLI configuration
       │
       ├── storage
       ├── runtime
       ├── scheduling
       ├── runner
       ├── transport
       └── logging

Resource specifications
       │
       ├── Environment
       ├── Test
       └── TestSuite

Configuration describes how E2Engine operates.

Resource specifications describe what system and behavior E2Engine should test.

Keeping these concerns separate allows the same Environment, Test, and TestSuite definitions to be used with different local, CI/CD, or execution configurations.

See CLI for the CLI overview, Logging for logging configuration, and Architecture overview for the architectural role of repositories, scheduling, runners, and runtime environments.