Configuration reference

This page documents configuration options for self-hosted Wave deployments. If you are using Wave as a service, these configuration options do not apply to your setup.

Configure Wave by setting YAML values in the config.yml configuration file:

wave:
    mail:
        from: "wave-app@seqera.io"

Configuration paths in this reference use dot notation to represent nested YAML keys. In the example above, the from value nested under the mail section is referenced as wave.mail.from.

You can configure Wave using either the config.yml file or environment variables. Environment variables are provided where available, though not all configuration options support them.

General

Configure general Wave application settings, such as application name, port, anonymous access permissions, and platform URLs with the following options:

tower.endpoint.url (optional)

URL of the Seqera platform API service (default: https://api.cloud.seqera.io). Can be set using the ${TOWER_ENDPOINT_URL} environment variable.

wave.allowAnonymous (required)

When true, anonymous users can access the Wave server (default: false). Modify this option based on your security requirements.

wave.denyHosts (optional)

Hostname patterns to deny. Requests targeting these hosts are rejected. Example patterns: ngrok.app, ngrok-free.app, //localhost.

wave.denyPaths (optional)

API path patterns to filter out. Requests for matching artifacts, such as non-existent manifests, are rejected.

wave.server.url (required)

URL of the Wave server. Can be set using the ${WAVE_SERVER_URL} environment variable.

wave.tokens.cache.duration (optional)

Cache duration for tokens generated by Wave (default: 36h).

Container registry

Wave uses the generic format wave.registries.<REGISTRY_NAME>.username and wave.registries.<REGISTRY_NAME>.password for registry authentication. You must specify all repositories used in your Wave installation.

The examples below show standard formats for known registries, but you can customize the registry name (for example, change azurecr.io to seqeralabs.azurecr.io).

note

You can also define container registry credentials in the config.yml file. These configurations enable Wave authentication for repositories used to push or pull artifacts.

Configure container registry authentication with the following options:

wave.registries.<AWS_ECR_REPO_NAME>.password (optional)

AWS ECR password for authentication. For example: 195996028523.dkr.ecr.eu-west-1.amazonaws.com. Can be set using the ${AWS_SECRET_ACCESS_KEY} environment variable.

wave.registries.<AWS_ECR_REPO_NAME>.username (optional)

AWS ECR (Elastic Container Registry) username for authentication. For example, 195996028523.dkr.ecr.eu-west-1.amazonaws.com. Can be set using the ${AWS_ACCESS_KEY_ID} environment variable.

wave.registries.default (optional)

Default container registry for Wave (default: docker.io).

wave.registries.docker.io.password (optional)

Docker Hub password or PAT (Personal Access Token) for authentication. Can be set using the ${DOCKER_PAT} environment variable.

wave.registries.docker.io.username (optional)

Docker Hub username for authentication. Can be set using the ${DOCKER_USER} environment variable.

wave.registries.quay.io.password (optional)

Quay.io password or PAT for authentication. Can be set using the ${QUAY_PAT} environment variable.

wave.registries.quay.io.username (optional)

Quay.io username for authentication. Can be set using the ${QUAY_USER} environment variable.

AWS cross-account role chaining

When Wave needs to access ECR registries in customer AWS accounts using IAM role credentials provided by the Seqera Platform, you can configure an intermediate "jump role" for cross-account access. When configured, Wave first assumes the jump role using its own credentials, then uses the jump role's temporary credentials to assume the target role received from the Seqera Platform.

This enables a two-hop role chaining pattern:

1. Wave assumes the jump role (using its default credentials)
2. Wave uses the jump role's temporary credentials to assume the customer's target role
3. The target role's temporary credentials are used to authenticate with ECR

Configure jump role chaining with the following options:

wave.aws.jump-role-arn (optional)

ARN of the intermediate IAM role that Wave assumes before assuming the target role from the Seqera Platform. Can be set using the WAVE_AWS_JUMP_ROLE_ARN environment variable. For example, arn:aws:iam::123456789012:role/wave-jump-role.

wave.aws.jump-external-id (optional)

External ID used when assuming the jump role, for confused deputy protection. Can be set using the WAVE_AWS_JUMP_EXTERNAL_ID environment variable.

note

When the jump role is not configured, Wave assumes target roles directly using its default credentials (the previous behavior). The jump role is only used for role-based ECR authentication, not for static AWS credential flows.

STS retry configuration

Configure retry behavior for AWS STS AssumeRole calls:

wave.aws.sts.retry.delay (optional)

Initial delay between retry attempts (default: 1s).

wave.aws.sts.retry.maxDelay (optional)

Maximum delay between retry attempts (default: 10s).

wave.aws.sts.retry.attempts (optional)

Maximum number of retry attempts (default: 3).

wave.aws.sts.retry.multiplier (optional)

Exponential backoff multiplier (default: 2.0).

wave.aws.sts.retry.jitter (optional)

Jitter factor for retry delays (default: 0.25).

Jump role cache configuration

Configure caching for jump role temporary credentials to avoid redundant STS calls:

wave.aws.jump-role-cache.duration (optional)

Maximum cache duration for jump role credentials (default: 45m). Actual TTL is dynamically computed based on credential expiration with a 5-minute refresh buffer.

wave.aws.jump-role-cache.max-size (optional)

Maximum number of cached jump role credential entries (default: 100).

HTTP client

Configure the HTTP client with the following options:

wave.httpclient.connectTimeout (optional)

Connection timeout for the HTTP client (default: 20s).

wave.httpclient.retry.attempts (optional)

Number of HTTP client retry attempts (default: 5).

wave.httpclient.retry.delay (optional)

Delay between HTTP client retries (default: 1s).

wave.httpclient.retry.jitter (optional)

Jitter factor for HTTP client retries (default: 0.25).

wave.httpclient.retry.maxDelay (optional)

Maximum delay between HTTP client retries.

wave.httpclient.retry.multiplier (optional)

Multiplier for HTTP client retries (default: 1.75).

Container build process

Configure how Wave builds container images and manages associated logs for monitoring, troubleshooting, and delivery with the following options:

wave.build.buildkit-image (required)

Buildkit container image used in the Wave build process (default: public.cr.seqera.io/wave/buildkit:v0.25.2-rootless).

wave.build.cache (optional)

Cache repository for images built by Wave. Supports both container registry paths and S3 bucket paths. For Example:

• Container registry: registry.example.com/wave/cache
• S3 bucket: s3://my-bucket/wave/cache

wave.build.cache-bucket-region (optional)

AWS region for the S3 cache bucket when using an S3 path in wave.build.cache. If not specified, Wave uses the AWS_REGION or AWS_DEFAULT_REGION environment variable. For example, us-east-1. This setting is only used when wave.build.cache is configured with an S3 bucket path.

wave.build.cache-bucket-upload-parallelism (optional)

Number of layers uploaded to S3 in parallel during cache export. Each individual layer is uploaded with 5 threads using the AWS SDK Upload Manager. If not specified, BuildKit uses its default parallelism behavior. For example, 8. This setting is only used when wave.build.cache is configured with an S3 bucket path.

wave.cleanup.strategy (optional)

Cleanup strategy after the build process. For example, set to OnSuccess for cleanup only if a build is successful.

wave.build.compression (optional)

Compression type applied to cache layers (default: gzip). Options include: uncompressed,estargz, and zstd.

wave.build.force-compression (optional)

When true, forces compression for each cache layer produced by the build process (default: false).

wave.build.oci-mediatypes (optional)

When true, includes OCI media types in exported manifests (default: true).

wave.build.public-repo (optional)

Public repository for container images built by Wave. Wave uses this repository as the build target when a freeze mode build is requested with Conda or pip packages via the v2 API and no buildRepository is provided. Images stored here default to the imageSuffix naming strategy. The registry hostname must be unique so that Wave can resolve default credentials correctly (i.e, it cannot be shared with wave.build.repo or wave.build cache-repo). If not set, a buildRepository must be specified in each freeze mode operations with packages.

wave.build.repo (required)

Docker container repository for container images built by Wave.

wave.build.singularity-image (optional)

Singularity image used in the build process (default: public.cr.seqera.io/wave/singularity:v4.2.1-r4).

wave.build.status.delay (optional)

Delay between build status checks (default: 5s).

wave.build.status.duration (optional)

Duration for build status checks (default: 1d).

wave.build.timeout (optional)

Maximum duration for the build process (default: 5m).

wave.build.trusted-timeout (optional)

Maximum duration for the build process when you are authenticated and freeze mode is enabled (default: 10m). If set to less than wave.build.timeout, the longer wave.build.timeout value is used.

wave.build.workspace (required)

Path to the directory used by Wave to store artifacts such as Containerfiles, Trivy cache for scan, Buildkit context, and authentication configuration files. For example, /efs/wave/build.

tip

For S3 cache authentication setup (IAM roles, service accounts, and deployment examples), see S3 cache authentication.

Build process logs

Configure how Wave stores and delivers build logs from containers and Kubernetes pods, which can be retrieved later or included in build completion emails, with the following options:

wave.build.locks.path (required)

Path where Wave stores Conda lock files. Can be an S3 URI (e.g., s3://my-bucket/wave/locks) or a local filesystem path.

wave.build.logs.maxLength (optional)

Maximum number of bytes read from a log file. If a log file exceeds this limit, it is truncated (default: 100000 (100 KB)).

wave.build.logs.path (required)

Path where Wave stores build logs. Can be an S3 URI (e.g., s3://my-bucket/wave/logs) or a local filesystem path. When using an S3 URI, Wave automatically extracts the key prefix for log file organization.

Kubernetes container build process

Configure Kubernetes-specific settings for Wave, where build and scan processes share most configurations except for CPU and memory requirements, with the following options:

wave.build.k8s.labels (optional)

Labels for Wave build Kubernetes pods.

wave.build.k8s.namespace (required)

Kubernetes namespace where Wave runs build pods.

wave.build.k8s.dns.policy (optional)

DNS policy for Wave build Kubernetes pods. For example, None, Default, ClusterFirst. When set to None, you must also configure wave.build.k8s.dns.servers.

wave.build.k8s.dns.servers (optional)

Custom DNS server IP addresses for Wave build pods. Used when wave.build.k8s.dns.policy is set to None. For example, ['1.1.1.1', '8.8.8.8'].

wave.build.k8s.node-selector (optional)

Node selector for Wave build Kubernetes pods. Value is a map where keys are platform identifiers and values are Kubernetes node label selectors in label=value format. Supported platform keys: linux/amd64, linux/arm64, noarch. For example:

wave.build.k8s.nodeSelector:
  linux/amd64: 'seqera.io/wave-build-amd64=true'
  linux/arm64: 'seqera.io/wave-build-arm64=true'
  noarch: 'seqera.io/wave-build=true'

wave.build.k8s.resources.requests.cpu (optional)

CPU resources allocated to Wave build processes. For example, set to 2 (2 CPU cores) or 1500Mi (1.5 CPU cores).

wave.build.k8s.resources.requests.memory (optional)

Memory resources allocated to Wave build processes. For example, set to 3Gi (3 Gigabytes) or 2000Mi (2000 Megabytes).

wave.build.k8s.service-account (optional)

Kubernetes service account name for Wave build pods.

wave.build.k8s.storage.claimName (optional)

Volume claim name for Wave build Kubernetes pods.

wave.build.k8s.storage.mountPath (optional)

Volume mount path for Wave build Kubernetes pods.

Container scan process

Configure how Wave's vulnerability scanning process uses a Trivy Docker image with customizable tags and severity levels with the following options:

wave.scan.enabled (optional)

When true, activates vulnerability scanning (default: false).

wave.scan.image.name (optional)

Container image used for security scanning (default: public.cr.seqera.io/wave/scanner:v1-0.65.0-oras-1.3.0).

wave.scan.reports.path (required)

S3 bucket path where Wave stores SBOM reports. For example, s3://wave-store/scan-reports.

wave.scan.severity (optional)

Severity levels to report in vulnerability scanning.

Options include: MEDIUM,HIGH, and CRITICAL.

wave.scan.status.duration (optional)

Duration for which scan status records are retained (default: 5d).

Kubernetes Wave scan process

Configure Wave scanning process resource requirements for Kubernetes deployments with the following options:

wave.scan.k8s.resources.requests.cpu (optional)

CPU resources allocated to Wave scan processes. For example, set to 2 (2 CPU cores) or 1500Mi (1.5 CPU cores).

wave.scan.k8s.resources.requests.memory (optional)

Memory resources allocated to Wave scan processes. For example, set to 3Gi (3 Gigabytes) or 2000Mi (2000 Megabytes).

Container mirror process

Configure Kubernetes resource requirements for Wave's container mirroring operations with the following options:

wave.mirror.k8s.resources.requests.cpu (optional)

CPU resources requested for mirror Kubernetes pods.

wave.mirror.k8s.resources.requests.memory (optional)

Memory resources requested for mirror Kubernetes pods.

wave.mirror.k8s.resources.limits.cpu (optional)

CPU resource limit for mirror Kubernetes pods.

wave.mirror.k8s.resources.limits.memory (optional)

Memory resource limit for mirror Kubernetes pods.

Proxy cache

Configure Wave's in-memory proxy cache for registry responses with the following options:

wave.proxy-cache.enabled (optional)

When true, activates the proxy cache (default: false).

wave.proxy-cache.duration (optional)

Cache entry expiration duration (default: 120s).

wave.proxy-cache.max-size (optional)

Maximum number of entries in the proxy cache (default: 10000).

Rate limits

Configure how Wave controls rate limits for anonymous and authenticated user access with the following options:

rate-limit.build.anonymous (required)

Rate limit for build requests from anonymous users (default: 10/1h).

rate-limit.build.authenticated (required)

Rate limit for build requests from authenticated users (default: 10/1m).

rate-limit.pull.anonymous (required)

Rate limit for pull requests from anonymous users (default: 100/1h).

rate-limit.pull.authenticated (required)

Rate limit for pull requests from authenticated users (default: 100/1m).

rate-limit.timeout-errors.max-rate (optional)

Maximum rate of timeout errors before Wave begins rejecting requests (default: 10/1m).

Database and cache

Wave uses external database and caching services to store application data and improve performance.

Redis

Configure Redis with the following options:

redis.client.timeout (optional)

Timeout duration (in milliseconds) for Redis client operations (default: 5000 (5 seconds)).

redis.password (optional)

Password used to authenticate with the Redis server. Can be set using the ${REDIS_PASSWORD} environment variable.

redis.pool.enabled (optional)

When true, activates the Redis connection pool (default: true).

redis.pool.maxIdle (optional)

Maximum number of idle connections in the Redis connection pool (default: 10).

redis.pool.maxTotal (optional)

Maximum number of connections in the Redis connection pool (default: 50).

redis.pool.minIdle (optional)

Minimum number of idle connections in the Redis connection pool (default: 0).

redis.uri (required)

URI for connecting to Redis (default format: redis://${REDIS_HOST:redis}:${REDIS_PORT:6379}). Can be set using the ${REDIS_URI} environment variable.

PostgreSQL

Configure PostgreSQL with the following options:

wave.db.password (required)

Password for the PostgreSQL database user. Can be set using the ${WAVE_DB_PASSWORD} environment variable.

wave.db.uri (required)

JDBC connection string for the PostgreSQL database. For example, jdbc:postgresql://localhost:5432/wave. Can be set using the ${WAVE_DB_URI} environment variable.

wave.db.user (required)

Username for authenticating with the PostgreSQL database. Can be set using the ${WAVE_DB_USER} environment variable.

Blob cache

Configure how Wave caches container blobs to improve client performance and optionally delegates transfer tasks to Kubernetes pods for scalability with the following options:

wave.blobCache.baseUrl (optional)

URL that overrides the base URL (the part before the blob path) of blobs sent to the client.

wave.blobCache.cloudflare.lifetime (optional)

Validity duration of the Cloudflare WAF token.

wave.blobCache.cloudflare.secret-key (optional)

Cloudflare secret used to create the WAF token.

wave.blobCache.url-signature-duration (optional)

Validity duration of the AWS S3 URL signature (default: 30m).

wave.blobCache.enabled (optional)

When true, activates the blob cache (default: false).

wave.blobCache.k8s.resources.requests.cpu (optional)

CPU resources requested for the Kubernetes pod used for blob binary transfers.

wave.blobCache.k8s.resources.requests.memory (optional)

Memory resources requested for the Kubernetes pod used for blob binary transfers.

wave.blobCache.k8s.resources.limits.cpu (optional)

CPU resource limit for the Kubernetes pod used for blob binary transfers.

wave.blobCache.k8s.resources.limits.memory (optional)

Memory resource limit for the Kubernetes pod used for blob binary transfers.

wave.blobCache.s5cmdImage (optional)

Container image that supplies the s5cmd tool for uploading blob binaries to the S3 bucket (default: public.cr.seqera.io/wave/s5cmd:v2.2.2).

wave.blobCache.signing-strategy (optional)

URL signing strategy for different services. Currently supports AWS S3 and Cloudflare service. Options include: aws-presigned-url and cloudflare-waf-token.

wave.blobCache.status.delay (optional)

Delay between status checks for blob binary transfers from the repository to the cache (default: 2s).

wave.blobCache.status.duration (optional)

Duration for which blob transfer status records are retained in cache (default: 1h).

wave.blobCache.storage.accessKey (required)

Access key credential for the caching service.

wave.blobCache.storage.bucket (required)

Name of the Cloudflare or S3 bucket. For example, s3://wave-blob-cache.

wave.blobCache.storage.endpoint (optional)

Storage endpoint URL for blob binary downloads and uploads.

wave.blobCache.storage.region (required)

AWS region of the bucket.

wave.blobCache.storage.secretKey (required)

Secret key credential for the caching service.

note

Static credentials (accessKey and secretKey) are currently required for blob cache storage access. IAM-based authentication (such as EKS Pod Identity or IRSA) is not yet supported for the blob cache feature. This differs from the S3 build cache, which does support IAM-based authentication.

wave.blobCache.timeout (optional)

Timeout for blob binary transfers. Transfers exceeding this duration fail (default: 10m).

Email configuration

Configure how Wave sends email notifications on behalf of the service with the following options:

mail.from (required)

Sender email address for Wave notifications. Can be set using the ${MAIL_FROM} environment variable.

Metrics

Configure how Wave Metrics service provides data about container builds and pulls per organization and date with the following options:

wave.metrics.enabled (optional)

When true, activates Wave metrics (default: false).

Accounts

Configure user credentials for accessing authenticated Wave APIs and services with the following options:

wave.accounts (required)

List of credentials for accessing authenticated Wave APIs such as the metrics API. Format of the credential list: - <USERNAME>:<PASSWORD_CHECKSUM>

License server

Configure the connection to the Seqera license management server:

license.server.url (optional)

URL of the Seqera license management server. Required when license validation is enabled. For example, https://licenses.seqera.io.

Job manager

Configure polling and scheduling intervals for Wave's asynchronous job processing.

wave.job-manager.poll-interval (optional)

Polling interval for checking job status (default: 1s).

wave.job-manager.scheduler-interval (optional)

Interval for the job scheduler to process queued jobs (default: 1s).

Message stream

Configure how Wave consumes messages from the Redis stream used for internal event processing.

wave.message-stream.claim-timeout (optional)

Timeout for claiming messages from the Redis stream (default: 5s).

wave.message-stream.consume-warn-timeout (optional)

Threshold duration after which a slow message consumer triggers a warning (default: 4s).

Thread monitor

Configure thread monitoring to detect and diagnose thread exhaustion issues. When enabled, Wave writes a thread dump to disk if the active thread count exceeds the configured threshold.

wave.thread-monitor.dump-file (optional)

File path where thread dumps are written when the thread count exceeds the threshold. For example, /efs/wave/dump/threads-dump.txt.

wave.thread-monitor.dump-threshold (optional)

Thread count threshold that triggers a thread dump (default: 200).

wave.thread-monitor.interval (optional)

Interval for the thread monitor check (default: 5m).

Trace

Configure slow endpoint logging to identify HTTP endpoints that exceed expected response times.

wave.trace.slow-endpoint.duration (optional)

Threshold duration for logging slow HTTP endpoints (default: 1m).