eventum.yml
Full schema reference for the main application configuration file — server, logging, paths, and default generation parameters.
The main application config controls how Eventum runs as a service with eventum run. It defines four sections: server settings, file paths, logging, and default generation parameters that all generators inherit.
server:
host: "0.0.0.0"
port: 9474
path:
startup: /etc/eventum/startup.yml
generators_dir: /etc/eventum/generators
logs: /var/log/eventum
keyring_cryptfile: /etc/eventum/cryptfile.cfg
log:
level: info
format: plain
generation:
timezone: UTC
batch:
size: 10000The config supports both nested YAML and dot notation. For example, server.host: "0.0.0.0" is equivalent to the nested server: { host: "0.0.0.0" }. Both formats can be mixed in the same file.
Extra fields are forbidden — any unrecognized key will cause a validation error at load time.
server
Controls the built-in web server that exposes the UI and REST API.
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
server.ui_enabled | boolean | true | — | Enable the web-based management UI. |
server.api_enabled | boolean | true | — | Enable the REST API endpoints. |
server.host | string | "0.0.0.0" | Non-empty. | Address the server binds to. |
server.port | integer | 9474 | >= 1 | Port the server binds to. |
server.ssl
TLS/SSL settings for the server.
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
server.ssl.enabled | boolean | false | — | Enable HTTPS. When true, cert and cert_key are required. |
server.ssl.verify_mode | string or null | null | "none", "optional", or "required" | Client certificate verification mode. "none" — no client certificate required. "optional" — request but don't require. "required" — reject connections without a valid client certificate. |
server.ssl.ca_cert | path or null | null | Must be an absolute path. | CA certificate for verifying client certificates. |
server.ssl.cert | path or null | null | Must be an absolute path. Required when SSL is enabled. Must be provided together with cert_key. | Server certificate file. |
server.ssl.cert_key | path or null | null | Must be an absolute path. Required when SSL is enabled. Must be provided together with cert. | Server certificate private key file. |
All SSL paths must be absolute.
server:
ssl:
enabled: true
cert: /etc/eventum/server.crt
cert_key: /etc/eventum/server.key
verify_mode: optional
ca_cert: /etc/eventum/ca.crtserver.auth
HTTP basic authentication credentials for the UI and API.
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
server.auth.user | string | "eventum" | Non-empty. | Username. |
server.auth.password | string | "eventum" | Non-empty. | Password. |
Change the default credentials before exposing Eventum on a network.
server.mcp
Mounts the MCP server into the running server so an AI agent can build, validate, preview, and manage generators over HTTP. Disabled by default. The endpoint is served at <host>:<port><path> and protected by the server.auth credentials.
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
server.mcp.enabled | boolean | false | — | Mount the MCP server over HTTP. |
server.mcp.allow_write | boolean | false | — | Allow write tools — file writes and deletes, one-shot runs, and starting, stopping, registering, and unregistering generators. When false, the endpoint is read-only: discovery, validation, preview, and live status/log reads, but no changes. Enabling writes grants code execution on the host (see the warning below). |
server.mcp.path | string | "/mcp" | Leading /, no trailing /. | Mount path for the MCP endpoint. |
server.mcp.allowed_hosts | list of strings | [] | — | Allowed Host header values (DNS-rebinding protection). Empty disables the check — suitable behind a trusted reverse proxy; a non-empty list enables it and rejects other hosts. Allowed Origin values are derived from this list, so browser-based clients on a listed host pass while foreign origins are rejected. |
server:
mcp:
enabled: true
allow_write: false
path: /mcp
allowed_hosts: []allow_write over HTTP grants code execution: a connected agent can write a generator and preview it, and some plugins execute code on the host by design (the template plugin runs arbitrary Python; a script plugin runs a script you provide). Enable it only on a trusted network with a trusted agent, and change the default server.auth credentials first.
Local authoring doesn't need the server — run eventum mcp for a stdio server next to your agent. See Connect your agent.
path
File system paths used by the application. All paths must be absolute.
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
path.logs | path | — | Required. Must be an absolute path. | Directory for application log files. Created automatically if it doesn't exist. |
path.startup | path | — | Required. Must be an absolute path. | Path to the startup.yml file. |
path.generators_dir | path | — | Required. Must be an absolute path. | Directory containing generator subdirectories. Generator paths in startup.yml are resolved relative to this directory. |
path.keyring_cryptfile | path | — | Required. Must be an absolute path. | Path to the encrypted keyring file used for secrets. |
path.generator_config_filename | path | "generator.yml" | Single filename. Must end with .yml or .yaml. | The expected config filename inside each generator directory. Used by the API to auto-detect valid generator directories. |
path:
startup: /etc/eventum/startup.yml
generators_dir: /etc/eventum/generators
logs: /var/log/eventum
keyring_cryptfile: /etc/eventum/cryptfile.cfg
generator_config_filename: generator.ymllog
Controls application logging — separate from the events that generators produce.
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
log.level | string | "info" | "debug", "info", "warning", "error", or "critical" | Minimum severity level for log messages. |
log.format | string | "plain" | "plain" or "json" | Log output format. "plain" is human-readable, "json" is structured. |
log.max_bytes | integer | 10485760 (10 MiB) | >= 1024 | Maximum size per log file before rotation. |
log.backups | integer | 5 | >= 1 | Number of rotated log files to keep. |
log:
level: info
format: json
max_bytes: 52428800 # 50 MiB
backups: 10generation
Default generation parameters inherited by all generators. Individual generators can override any of these in startup.yml.
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
generation.timezone | string | "UTC" | Valid IANA timezone. Min length: 3. | Default timezone for generating timestamps. |
generation.batch
Controls how events are grouped before being passed to output plugins:
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
generation.batch.size | integer or null | 10000* | >= 1 | Maximum number of events per batch. |
generation.batch.delay | float or null | 1.0* | >= 0.1 | Maximum seconds to wait before flushing a partial batch. |
*The defaults of 10000 and 1.0 apply as a pair when neither field is specified. If you set only one, the other defaults to null. At least one of size or delay must be set. When both are set, the batch is flushed when either limit is reached — whichever comes first.
generation.queue
Controls the internal queues between pipeline stages. These act as backpressure buffers — when a downstream stage is slower, the upstream stage will block once the queue is full.
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
generation.queue.max_timestamp_batches | integer | 10 | >= 1 | Maximum timestamp batches in the input→event queue. |
generation.queue.max_event_batches | integer | 10 | >= 1 | Maximum event batches in the event→output queue. |
Concurrency and ordering
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
generation.keep_order | boolean | false | — | When true, output plugins process batches sequentially to preserve chronological order. |
generation.max_concurrency | integer | 100 | >= 1 | Maximum number of concurrent write operations across all output plugins. |
generation.write_timeout | integer | 10 | >= 1 | Timeout in seconds for a single write operation. |
generation:
timezone: America/New_York
batch:
size: 20000
delay: 2.0
queue:
max_timestamp_batches: 20
max_event_batches: 20
keep_order: false
max_concurrency: 200
write_timeout: 30Complete example
# Server
server:
ui_enabled: true
api_enabled: true
host: "0.0.0.0"
port: 9474
ssl:
enabled: true
cert: /etc/eventum/server.crt
cert_key: /etc/eventum/server.key
verify_mode: none
auth:
user: admin
password: s3cret
# Paths
path:
startup: /etc/eventum/startup.yml
generators_dir: /etc/eventum/generators
logs: /var/log/eventum
keyring_cryptfile: /etc/eventum/cryptfile.cfg
# Logging
log:
level: info
format: json
max_bytes: 52428800
backups: 10
# Default generation parameters
generation:
timezone: UTC
batch:
size: 10000
delay: 1.0
queue:
max_timestamp_batches: 10
max_event_batches: 10
keep_order: false
max_concurrency: 100
write_timeout: 10What's next
startup.yml
Full schema reference for the startup configuration file — generator entries, per-generator parameter overrides, and the parameter cascade from eventum.yml.
Parameters
How to pass runtime values into generator configs via startup.yml entries to keep configurations reusable across environments.