Host Interface Configuration Reference

This page is the complete reference for the configuration keys each built-in host interface reads, as of wasmCloud 2.8.0. For the structure of the hostInterfaces field itself (namespace, package, interfaces, version, config, name, and multi-backend binding), see Host Interfaces in the CRD guide.

How configuration reaches an interface

Each hostInterfaces entry carries a string-to-string config map assembled from up to three sources, later sources winning on key conflicts:

1. The inline config map.
2. ConfigMaps referenced by configFrom.
3. Kubernetes Secrets referenced by secretFrom.

Some interfaces also read keys from the component's localResources.config, which is passed through as written. Where an interface reads from both, the tables below say so and give the precedence.

Two rules that apply across interfaces:

• Named vs. unnamed entries bind differently. An entry with a name serves a labeled (implements ..) import and reads backend-selection keys (backend, url, and friends). An unnamed entry binds to the host's standalone plugin for that package, which on stock hosts means backend-selection keys on unnamed wasi:keyvalue, wasi:blobstore, and wasmcloud:messaging entries are ignored. Use a named entry (or the async wasmcloud:keyvalue/wasmcloud:blobstore packages) to select a backend per entry.
• A labeled import with no matching named entry is an error at workload start, never a silent fallback to the default backend.

wasi:http

Serves wasi:http/incoming-handler (components) and wasi:http/handler (services). Keys are read from the wasi:http entry config:

Key	Description
host	Routing hostname for the workload, matched against the request's Host header. Required on Kubernetes. Must be a bare RFC 1123 hostname without a port; matching ignores ports on both sides. Multiple workloads registered under the same hostname are load balanced per request.
host-aliases	Comma-separated additional hostnames. Invalid entries are dropped silently. When spec.kubernetes.service is set, the operator replaces this key with the Service's in-cluster names (<svc>.<ns>, <svc>.<ns>.svc), so user-supplied aliases do not survive alongside a Service.

There is no address key: the listen address and port are host-level settings (runtime.hostGroups[].http.port in Helm values, dev.address in wash configuration). Under wash dev, routing ignores hostnames entirely and sends every request to the current dev workload.

wasmcloud:messaging

Serves consumer, handler, and types at 0.2.0 (sync) and 0.3.0 (async). The entry's version selects which revision is linked for imports; the handler revision follows the component's export. See Messaging subscriptions and consumer groups for the delivery model.

Keys are read from the component's localResources.config first; the NATS backend falls back to the wasmcloud:messaging entry config (the in-memory backend reads component config only):

Key	Format	Default	On invalid value
subscriptions	Comma-separated NATS subjects; wildcards allowed (orders.*, audit.>)	No subscriptions on the NATS backend. The in-memory backend used by wash dev delivers everything when unset.	n/a
consumer_group	Queue group name, or the literal broadcast to deliver every message to every replica. No whitespace, *, or >.	Derived group scoped to the workload's namespace, name, and component	Workload fails to start
max_in_flight	Positive integer; per-component in-flight delivery cap across replicas on a host (added in 2.8.0). Can only lower the component below the host's per-component ceiling.	The host's per-component ceiling	Zero or invalid values are treated as unset, with a warning
admission_wait	Duration (45s, 2m, 1m30s) or bare seconds; how long a delivery waits for a slot before it is dropped (added in 2.8.0). Maximum 600s.	30s	Default, with a warning

A named entry serving a labeled consumer import additionally reads:

Key	Description
backend	nats or in-memory. Default in-memory.
url	NATS server URL. Required when backend: nats; the workload fails to start without it.

wasi:keyvalue and wasmcloud:keyvalue

wasi:keyvalue serves store, atomics, and batch (sync); wasmcloud:keyvalue serves store, atomics, cas, and batch (async).

An unnamed wasi:keyvalue entry binds the host's standalone backend and reads no config keys: the bucket is whatever the guest passes to store.open(), and the backend endpoint is a host-level setting. Named entries (and all wasmcloud:keyvalue entries) select a backend per entry:

backend	Additional keys	Notes
in-memory (default)	none	Isolated per entry
redis	url (required), prefix (optional)	Redis has a flat keyspace: the open() identifier does not namespace keys. prefix prepends a literal key prefix for isolation.
nats	url (required)	JetStream key-value; the bucket named by open() must already exist
filesystem	root (required)	Buckets are subdirectories of root

A missing required key fails the workload at start with an error naming the key.

wasi:blobstore and wasmcloud:blobstore

wasi:blobstore (sync) and wasmcloud:blobstore (async) serve blobstore, container, and types.

An unnamed wasi:blobstore entry binds the standalone NATS backend on a production host and reads:

Key	Description
buckets	Comma-separated allowlist of JetStream object store bucket names the workload may use. When empty or omitted, all container operations are denied, including create-container. Entries are matched exactly, without trimming whitespace.

The filesystem and in-memory backends used by wash dev read no keys and apply no allowlist, so a workload that works in the dev loop still needs buckets set for Kubernetes.

Named entries (and all wasmcloud:blobstore entries) select a backend per entry: in-memory (default), filesystem (requires root), or nats (requires url). Named entries do not read buckets.

wasi:config

Serves wasi:config/store. There are no fixed key names: the component's entire view is a merged map, later layers winning on conflicts:

1. The wasi:config entry config map.
2. The component's localResources.config.
3. The component's localResources.environment.

get and get-all expose exactly this merged map. Under wash dev, the project's workload.config values are injected into the wasi:config entry automatically.

wasmcloud:secrets

Serves store and reveal, plus labeled secret imports, at 2.1.0. Values are delivered from the entry's config, which on Kubernetes typically arrives via secretFrom. There are no fixed key names:

• Unlabeled imports (store/reveal): the config maps of every unnamed wasmcloud:secrets entry are flattened into one per-component map, and store.get(key) looks keys up there. The same key set by two entries fails the workload at start.
• Labeled imports (secret via (implements ..)): the entry's name doubles as the config key. The value at config[<name>] in that entry backs the label's get(). A label with no matching value fails the workload at start, naming the missing key.

See Workload Security for the delivery model and Interfaces for the package.

wasmcloud:postgres

Serves query, prepared, and types at 0.1.1-draft (sync) and 0.2.0 (async); the entry's version selects the revision.

• An unnamed entry requires the host to be started with a base connection URL (wash host --postgres-url or dev.postgres_url) and reads one key: database (required; the workload fails to start without it). Credentials, host, and TLS come from the host-level URL.
• A named entry reads url (required): a full Postgres connection string.

Both URL forms honor two query parameters: pool_size (connection pool size, default 10) and sslmode (require, verify-ca, or verify-full to enable TLS).

Interfaces with no configuration

• wasi:logging: structured logs flow to the host's logging pipeline; no keys.
• wasi:otel: no per-workload keys; exporter endpoints come from standard OTEL_* environment variables on the host, and the plugin is active only on hosts started with --wasi-otel.
• wasi:webgpu: no keys; active only on hosts started with --wasi-webgpu.
• The WASI P2 base (wasi:io, wasi:clocks, wasi:random, wasi:filesystem, wasi:sockets, wasi:cli) is always available and configured through workload-level fields rather than hostInterfaces entries.

wash dev differences

The same keys apply to entries under dev.host_interfaces in wash configuration, with these differences:

• Interfaces are also derived automatically from the component's own WIT imports, so most projects need no explicit entries.
• HTTP routing ignores host and host-aliases.
• Messaging keys are read from the component's config (workload.config merged with dev.components[].config), and the in-memory backend delivers all subjects when subscriptions is unset.
• Secrets values come directly from entry config, with no Kubernetes Secret indirection.

Related documentation

• Host Interfaces (CRD guide): entry structure and multi-backend binding.
• Interfaces overview: the WIT packages themselves.
• Secrets and Configuration Management: config, configFrom, and secretFrom in depth.
• Troubleshooting: errors when an interface is not declared.