Configuration

Every environment variable that controls the engine, plus single-node and three-node Raft setups, the X-Argyll-Raft-State header for leader-aware load balancing, and an HAProxy config you can copy.

Environment Variables

API and Webhooks

Variable	Default	Description
`API_HOST`	`0.0.0.0`	HTTP listen host
`API_PORT`	`8080`	HTTP API port
`WEBHOOK_BASE_URL`	`http://localhost:8080`	Base URL the engine uses to construct async callback URLs. Must be reachable from your step handlers.
`LOG_LEVEL`	`info`	`debug`, `info`, `warn`, `error`

Step Execution

Variable	Default	Description
`STEP_TIMEOUT`	`30000`	Global HTTP step timeout fallback (ms). Overridden per step by `http.timeout`.

Caching

Variable	Default	Description
`MEMO_CACHE_SIZE`	`65536`	In-memory memoization cache entries (LRU)
`TIMEBOX_CACHE_SIZE`	`32768`	Shared Timebox projection cache entries

Retry Defaults

Applied when a step omits retry fields or sets them to zero:

Variable	Default	Description
`RETRY_MAX_RETRIES`	`10`	Default max retries (cannot be `0`)
`RETRY_INITIAL_BACKOFF`	`1000`	Initial backoff in milliseconds (must be `> 0`)
`RETRY_MAX_BACKOFF`	`60000`	Backoff cap in milliseconds (must be `>= RETRY_INITIAL_BACKOFF`)
`RETRY_BACKOFF_TYPE`	`exponential`	`fixed`, `linear`, or `exponential`

Invalid retry defaults fail engine startup.

Raft Storage

Variable	Description
`RAFT_NODE_ID`	Local node identifier
`RAFT_ADDRESS`	Local Raft listen address (e.g. `127.0.0.1:9701`)
`RAFT_DATA_DIR`	Durable local state directory
`RAFT_SERVERS`	Bootstrap cluster members (e.g. `node1=host1:9701,node2=host2:9702`)
`RAFT_LOG_TAIL_SIZE`	Hot retained WAL tail cache entries (default `20480`)

Clustering

Argyll uses Raft for consensus. Run at least 3 nodes for high availability.

Single Node (development)

RAFT_NODE_ID=argyll-1
RAFT_ADDRESS=127.0.0.1:9701
RAFT_DATA_DIR=/tmp/argyll-raft/argyll-1
RAFT_SERVERS=argyll-1=127.0.0.1:9701

Three-Node Cluster

# On each node, set its own RAFT_NODE_ID and RAFT_ADDRESS,
# but the same RAFT_SERVERS listing all nodes:
RAFT_NODE_ID=argyll-1
RAFT_ADDRESS=argyll-1:9701
RAFT_DATA_DIR=/var/lib/argyll/raft/argyll-1
RAFT_SERVERS=argyll-1=argyll-1:9701,argyll-2=argyll-2:9702,argyll-3=argyll-3:9703

Writes commit on quorum. Only the Raft leader accepts writes; reads can be served from any node.

Health Check

GET /health

Returns 200. The response header X-Argyll-Raft-State contains the node’s role: leader, candidate, follower, or unknown. Use this for load balancer routing.

HAProxy Leader-Aware Routing

Route write traffic only to the Raft leader:

backend argyll_write
  option httpchk GET /health
  http-check expect hdr name "X-Argyll-Raft-State" value -m str leader
  server n1 argyll-1:8080 check
  server n2 argyll-2:8080 check
  server n3 argyll-3:8080 check

backend argyll_read
  option httpchk GET /health
  http-check expect status 200
  server n1 argyll-1:8080 check
  server n2 argyll-2:8080 check
  server n3 argyll-3:8080 check

Write paths: POST /engine/step, POST /engine/flow, /webhook/*. Read-style POSTs like POST /engine/plan and POST /engine/flow/query can go to any node.

Health Checks on Steps

HTTP steps can declare a health check endpoint:

{
  "http": {
    "endpoint": "https://api.example.com/process",
    "health_check": "https://api.example.com/health"
  }
}

The engine polls the health check to track step availability. Health checks do not block or fail step execution directly.

Security

The engine has no built-in authentication. Place it behind a reverse proxy and add auth at that layer. Network isolation or mTLS for service-to-service communication is recommended for production.

Script steps run inside the engine with restricted capabilities:

Ale: Purely functional, no I/O. Safe for untrusted scripts.
Lua: io, os, and debug modules excluded. Use only for trusted scripts.