Configuration

Configure engine networking, retries, storage, clustering, and production routing.

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`	Cached current-state projections shared by Timebox stores

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`	Number of recent write-ahead log entries retained in memory (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

A write is committed only after enough voting nodes accept it. 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: mutating /engine/steps and /engine/spaces requests, POST /engine/flows, and POST /callbacks/*. Read-style POSTs like POST /engine/plan and POST /engine/flows/query can go to any node.

Health Checks on Steps

HTTP Steps can declare a health check endpoint:

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

The engine polls the health check with GET to track Step availability. Invocation outcomes continue to determine execution success.

Security

Deploy the engine behind an authenticated reverse proxy. Network isolation or mTLS provides service-to-service protection in production.

Lua Script Steps run inside the engine with the io, os, and debug modules excluded. Use only for trusted scripts.