Environment Variables Reference
Complete reference of environment variables used by the testing framework, organized by category.
Runner Selection & Topology
Control which runner to use and the test topology:
| Variable | Default | Effect |
|---|---|---|
LOGOS_BLOCKCHAIN_DEMO_NODES | 1 | Number of nodes (all runners) |
LOGOS_BLOCKCHAIN_DEMO_RUN_SECS | 60 | Run duration in seconds (all runners) |
LOCAL_DEMO_NODES | — | Legacy: Number of nodes (host runner only) |
LOCAL_DEMO_RUN_SECS | — | Legacy: Run duration (host runner only) |
COMPOSE_NODE_PAIRS | — | Compose-specific topology format: “nodes” (e.g., 3) |
Example:
# Run with 5 nodes, for 120 seconds
LOGOS_BLOCKCHAIN_DEMO_NODES=5 \
LOGOS_BLOCKCHAIN_DEMO_RUN_SECS=120 \
scripts/run/run-examples.sh -t 120 -n 5 host
Node Binaries (Host Runner)
Required for host runner when not using helper scripts:
| Variable | Required | Default | Effect |
|---|---|---|---|
LOGOS_BLOCKCHAIN_NODE_BIN | Yes (host) | — | Path to logos-blockchain-node binary |
LOGOS_BLOCKCHAIN_NODE_PATH | No | — | Path to logos-blockchain-node git checkout (dev workflow) |
Example:
export LOGOS_BLOCKCHAIN_NODE_BIN=/path/to/logos-blockchain-node/target/release/logos-blockchain-node
Docker Images (Compose / K8s)
Required for compose and k8s runners:
| Variable | Required | Default | Effect |
|---|---|---|---|
LOGOS_BLOCKCHAIN_TESTNET_IMAGE | Yes (compose/k8s) | logos-blockchain-testing:local | Docker image tag for node containers |
LOGOS_BLOCKCHAIN_TESTNET_IMAGE_PULL_POLICY | No | IfNotPresent (local) / Always (ECR) | K8s imagePullPolicy used by the runner |
LOGOS_BLOCKCHAIN_BINARIES_TAR | No | — | Path to prebuilt bundle (.tar.gz) for image build |
LOGOS_BLOCKCHAIN_SKIP_IMAGE_BUILD | No | 0 | Skip image rebuild (compose/k8s); assumes image already exists |
LOGOS_BLOCKCHAIN_FORCE_IMAGE_BUILD | No | 0 | Force rebuilding the image even when the script would normally skip it (e.g. non-local k8s) |
Example:
# Using prebuilt bundle
export LOGOS_BLOCKCHAIN_BINARIES_TAR=.tmp/nomos-binaries-linux-v0.3.1.tar.gz
export LOGOS_BLOCKCHAIN_TESTNET_IMAGE=logos-blockchain-testing:local
scripts/build/build_test_image.sh
# Using pre-existing image (skip build)
export LOGOS_BLOCKCHAIN_SKIP_IMAGE_BUILD=1
scripts/run/run-examples.sh -t 60 -n 3 compose
Circuit Assets
Circuit asset configuration used by local runs and image builds:
| Variable | Default | Effect |
|---|---|---|
LOGOS_BLOCKCHAIN_CIRCUITS | ~/.logos-blockchain-circuits | Directory containing circuit assets |
VERSION | From versions.env | Circuit release tag (used by helper scripts) |
LOGOS_BLOCKCHAIN_CIRCUITS_VERSION | — | Legacy alias for VERSION (supported by some build scripts) |
LOGOS_BLOCKCHAIN_CIRCUITS_PLATFORM | Auto-detected | Override circuits platform (e.g. linux-x86_64, macos-aarch64) |
LOGOS_BLOCKCHAIN_CIRCUITS_HOST_DIR_REL | .tmp/logos-blockchain-circuits-host | Output dir for host circuit bundle (relative to repo root) |
LOGOS_BLOCKCHAIN_CIRCUITS_LINUX_DIR_REL | .tmp/logos-blockchain-circuits-linux | Output dir for linux circuit bundle (relative to repo root) |
LOGOS_BLOCKCHAIN_CIRCUITS_NONINTERACTIVE | 0 | Set to 1 to overwrite outputs without prompting in setup scripts |
LOGOS_BLOCKCHAIN_CIRCUITS_REBUILD_RAPIDSNARK | 0 | Set to 1 to force rebuilding rapidsnark (host bundle only) |
Example:
# Use custom circuit assets
LOGOS_BLOCKCHAIN_CIRCUITS=/custom/path/to/circuits \
cargo run -p runner-examples --bin local_runner
Node Logging
Control node log output (not framework runner logs):
| Variable | Default | Effect |
|---|---|---|
LOGOS_BLOCKCHAIN_LOG_LEVEL | info | Global log level: error, warn, info, debug, trace |
LOGOS_BLOCKCHAIN_LOG_FILTER | — | Fine-grained module filtering (e.g., cryptarchia=trace) |
LOGOS_BLOCKCHAIN_LOG_DIR | — | Host runner: directory for per-node log files (persistent). Compose/k8s: use cfgsync.yaml for file logging. |
LOGOS_BLOCKCHAIN_TESTS_KEEP_LOGS | 0 | Keep per-run temporary directories (useful for debugging/CI artifacts) |
LOGOS_BLOCKCHAIN_TESTS_TRACING | false | Enable debug tracing preset (combine with LOGOS_BLOCKCHAIN_LOG_DIR unless external tracing backends configured) |
Important: Node logging ignores RUST_LOG; use LOGOS_BLOCKCHAIN_LOG_LEVEL and LOGOS_BLOCKCHAIN_LOG_FILTER for node logs.
Example:
# Debug logging to files
LOGOS_BLOCKCHAIN_LOG_DIR=/tmp/test-logs \
LOGOS_BLOCKCHAIN_LOG_LEVEL=debug \
LOGOS_BLOCKCHAIN_LOG_FILTER="cryptarchia=trace" \
cargo run -p runner-examples --bin local_runner
# Inspect logs
ls /tmp/test-logs/
# logos-blockchain-node-0.2024-12-18T14-30-00.log
# logos-blockchain-node-1.2024-12-18T14-30-00.log
Common filter targets:
| Target Prefix | Subsystem |
|---|---|
lb_cryptarchia | Consensus (Cryptarchia) |
lb_blend | Mix network/privacy layer |
lb_chain_service | Chain service (node APIs/state) |
lb_chain_network | P2P networking |
lb_chain_leader_service | Leader election |
Observability & Metrics
Optional observability integration:
| Variable | Default | Effect |
|---|---|---|
LOGOS_BLOCKCHAIN_METRICS_QUERY_URL | — | Prometheus-compatible base URL for runner to query (e.g., http://localhost:9090) |
LOGOS_BLOCKCHAIN_METRICS_OTLP_INGEST_URL | — | Full OTLP HTTP ingest URL for node metrics export (e.g., http://localhost:9090/api/v1/otlp/v1/metrics) |
LOGOS_BLOCKCHAIN_GRAFANA_URL | — | Grafana base URL for printing/logging (e.g., http://localhost:3000) |
LOGOS_BLOCKCHAIN_OTLP_ENDPOINT | — | OTLP trace endpoint (optional) |
LOGOS_BLOCKCHAIN_OTLP_METRICS_ENDPOINT | — | OTLP metrics endpoint (optional) |
Example:
# Enable Prometheus querying
export LOGOS_BLOCKCHAIN_METRICS_QUERY_URL=http://localhost:9090
export LOGOS_BLOCKCHAIN_METRICS_OTLP_INGEST_URL=http://localhost:9090/api/v1/otlp/v1/metrics
export LOGOS_BLOCKCHAIN_GRAFANA_URL=http://localhost:3000
scripts/run/run-examples.sh -t 60 -n 3 compose
Compose Runner Specific
Variables specific to Docker Compose deployment:
| Variable | Default | Effect |
|---|---|---|
COMPOSE_RUNNER_HOST | 127.0.0.1 | Host address for port mappings |
COMPOSE_RUNNER_PRESERVE | 0 | Keep containers running after test (for debugging) |
COMPOSE_RUNNER_HTTP_TIMEOUT_SECS | — | Override HTTP readiness timeout (seconds) |
COMPOSE_RUNNER_HOST_GATEWAY | host.docker.internal:host-gateway | Controls extra_hosts entry injected into compose (set to disable to omit) |
TESTNET_RUNNER_PRESERVE | — | Alias for COMPOSE_RUNNER_PRESERVE |
Example:
# Keep containers after test for debugging
COMPOSE_RUNNER_PRESERVE=1 \
scripts/run/run-examples.sh -t 60 -n 3 compose
# Containers remain running
docker ps --filter "name=nomos-compose-"
docker logs <container-id>
K8s Runner Specific
Variables specific to Kubernetes deployment:
| Variable | Default | Effect |
|---|---|---|
K8S_RUNNER_NAMESPACE | Random UUID | Kubernetes namespace (pin for debugging) |
K8S_RUNNER_RELEASE | Random UUID | Helm release name (pin for debugging) |
K8S_RUNNER_NODE_HOST | — | NodePort host resolution for non-local clusters |
K8S_RUNNER_DEBUG | 0 | Log Helm stdout/stderr for install commands |
K8S_RUNNER_PRESERVE | 0 | Keep namespace/release after run (for debugging) |
K8S_RUNNER_DEPLOYMENT_TIMEOUT_SECS | — | Override deployment readiness timeout |
K8S_RUNNER_HTTP_TIMEOUT_SECS | — | Override HTTP readiness timeout (port-forwards) |
K8S_RUNNER_HTTP_PROBE_TIMEOUT_SECS | — | Override HTTP readiness timeout (NodePort probes) |
K8S_RUNNER_PROMETHEUS_HTTP_TIMEOUT_SECS | — | Override Prometheus readiness timeout |
K8S_RUNNER_PROMETHEUS_HTTP_PROBE_TIMEOUT_SECS | — | Override Prometheus NodePort probe timeout |
Example:
# Pin namespace for debugging
K8S_RUNNER_NAMESPACE=nomos-test-debug \
K8S_RUNNER_PRESERVE=1 \
K8S_RUNNER_DEBUG=1 \
scripts/run/run-examples.sh -t 60 -n 3 k8s
# Inspect resources
kubectl get pods -n nomos-test-debug
kubectl logs -n nomos-test-debug -l nomos/logical-role=node
Platform & Build Configuration
Platform-specific build configuration:
| Variable | Default | Effect |
|---|---|---|
LOGOS_BLOCKCHAIN_BUNDLE_DOCKER_PLATFORM | Host arch | Docker platform for bundle builds: linux/arm64 or linux/amd64 (macOS/Windows hosts) |
LOGOS_BLOCKCHAIN_BIN_PLATFORM | — | Legacy alias for LOGOS_BLOCKCHAIN_BUNDLE_DOCKER_PLATFORM |
COMPOSE_CIRCUITS_PLATFORM | Host arch | Circuits platform for image builds: linux-aarch64 or linux-x86_64 |
LOGOS_BLOCKCHAIN_EXTRA_FEATURES | — | Extra cargo features to enable when building bundles (used by scripts/build/build-bundle.sh) |
macOS / Apple Silicon:
# Native performance (recommended for local testing)
export LOGOS_BLOCKCHAIN_BUNDLE_DOCKER_PLATFORM=linux/arm64
# Or target amd64 (slower via emulation)
export LOGOS_BLOCKCHAIN_BUNDLE_DOCKER_PLATFORM=linux/amd64
Timeouts & Performance
Timeout and performance tuning:
| Variable | Default | Effect |
|---|---|---|
SLOW_TEST_ENV | false | Doubles built-in readiness timeouts (useful in CI / constrained laptops) |
TESTNET_PRINT_ENDPOINTS | 0 | Print TESTNET_ENDPOINTS / TESTNET_PPROF lines during deploy (set automatically by scripts/run/run-examples.sh) |
Example:
# Increase timeouts for slow environments
SLOW_TEST_ENV=true \
scripts/run/run-examples.sh -t 120 -n 5 compose
Node Configuration (Advanced)
Node-level configuration passed through to logos-blockchain-node:
| Variable | Default | Effect |
|---|---|---|
CONSENSUS_SLOT_TIME | — | Consensus slot time (seconds) |
CONSENSUS_ACTIVE_SLOT_COEFF | — | Active slot coefficient (0.0-1.0) |
LOGOS_BLOCKCHAIN_USE_AUTONAT | Unset | If set, use AutoNAT instead of a static loopback address for libp2p NAT settings |
LOGOS_BLOCKCHAIN_CFGSYNC_PORT | 4400 | Port used for cfgsync service inside the stack |
LOGOS_BLOCKCHAIN_TIME_BACKEND | monotonic | Select time backend (used by compose/k8s stack scripts and deployers) |
Example:
# Faster block production
CONSENSUS_SLOT_TIME=5 \
CONSENSUS_ACTIVE_SLOT_COEFF=0.9 \
cargo run -p runner-examples --bin local_runner
Framework Runner Logging (Not Node Logs)
Control framework runner process logs (uses RUST_LOG, not NOMOS_*):
| Variable | Default | Effect |
|---|---|---|
RUST_LOG | — | Framework runner log level (e.g., debug, info) |
RUST_BACKTRACE | — | Enable Rust backtraces on panic (1 or full) |
CARGO_TERM_COLOR | — | Cargo output color (always, never, auto) |
Example:
# Debug framework runner (not nodes)
RUST_LOG=debug \
RUST_BACKTRACE=1 \
cargo run -p runner-examples --bin local_runner
Helper Script Variables
Variables used by helper scripts (scripts/run/run-examples.sh, etc.):
| Variable | Default | Effect |
|---|---|---|
LOGOS_BLOCKCHAIN_NODE_REV | From versions.env | logos-blockchain-node git revision to build/fetch |
LOGOS_BLOCKCHAIN_BUNDLE_VERSION | From versions.env | Bundle schema version |
LOGOS_BLOCKCHAIN_IMAGE_SELECTION | — | Internal: image selection mode set by run-examples.sh (local/ecr/auto) |
LOGOS_BLOCKCHAIN_NODE_APPLY_PATCHES | 1 | Set to 0 to disable applying local patches when building bundles |
LOGOS_BLOCKCHAIN_NODE_PATCH_DIR | patches/logos-blockchain-node | Patch directory applied to logos-blockchain-node checkout during bundle builds |
LOGOS_BLOCKCHAIN_NODE_PATCH_LEVEL | — | Patch application level (all or an integer) for bundle builds |
Quick Reference Examples
Minimal Host Run
scripts/run/run-examples.sh -t 60 -n 3 host
Debug Logging (Host)
LOGOS_BLOCKCHAIN_LOG_DIR=/tmp/logs \
LOGOS_BLOCKCHAIN_LOG_LEVEL=debug \
LOGOS_BLOCKCHAIN_LOG_FILTER="cryptarchia=trace" \
scripts/run/run-examples.sh -t 60 -n 3 host
Compose with Observability
LOGOS_BLOCKCHAIN_METRICS_QUERY_URL=http://localhost:9090 \
LOGOS_BLOCKCHAIN_GRAFANA_URL=http://localhost:3000 \
scripts/run/run-examples.sh -t 60 -n 3 compose
K8s with Debug
K8S_RUNNER_NAMESPACE=nomos-debug \
K8S_RUNNER_DEBUG=1 \
K8S_RUNNER_PRESERVE=1 \
scripts/run/run-examples.sh -t 60 -n 3 k8s
CI Environment
env:
RUST_BACKTRACE: 1
LOGOS_BLOCKCHAIN_TESTS_KEEP_LOGS: 1
See Also
- Prerequisites & Setup — Required files and setup
- Running Examples — How to run scenarios
- Logging & Observability — Log collection details
- CI Integration — CI-specific variables
- Troubleshooting — Common issues with variables