Wasm Shell Configuration

This document describes the configuration options available for the wash CLI. Configuration can be specified in YAML, JSON, or TOML format (.json, .yaml, .yml, or .toml).

Wasm Shell uses two configuration files:

• User configuration that is local to the machine
• Project configuration in the .wash directory at the root of each project

Configuration hierarchy

Configuration is merged with the following precedence (highest to lowest):

1. CLI arguments
2. Environment variables (WASH_ prefix)
3. Project config (.wash/config.yaml)
4. User config ($HOME/.config/wash/config.yaml)
5. Default values

Managing the config file

wash ships three subcommands for managing the project-local config file in .wash/. Together they cover the typical lifecycle: scaffold a working file, check it before you run anything against it, and clean up stale state when something goes wrong.

Creating a new config

Use wash config init to create a starter file. The --example flag populates every section with illustrative values, which is the fastest way to see what wash accepts:

shell

wash config init --example

The --format flag selects the serialization format. yaml is the default; yml, json, and toml are also supported:

shell

wash config init --format toml --example

init always writes to the project-local .wash/ directory. The legacy --global flag is deprecated and has no effect.

Validating a config

Run wash config validate to catch hard errors in the merged project configuration before they show up at runtime:

shell

wash config validate

Validation covers socket-address syntax, redis:// / nats:// / postgres:// URL schemes, paired TLS cert and key files, WebGPU availability on Windows, non-empty build commands, well-formed WIT registry URLs, and local WIT source paths that actually exist on disk. Remote sources (HTTP, Git, OCI) are skipped — validate doesn't reach out to the network. Errors are collected across every section before the command returns, so every issue surfaces in one pass.

To validate a specific file instead of the merged project config (useful when working with multiple variants), pass --file:

shell

wash config validate --file ./alternate-config.yaml

Cleaning up cache and data directories

wash config cleanup removes the wash cache and/or data directories. Use it to reclaim disk space or to recover from a corrupted cache. Always preview with --dry-run first to see what would be removed and how much space it would free:

shell

# Preview
wash config cleanup --all --dry-run

# Apply
wash config cleanup --all

Use --cache or --data instead of --all to target a single directory.

User configuration

By default, user configuration files are found at $HOME/.config/wash/config.yaml.

Under construction

This section is under active development—please check back soon for a more complete reference.

Project configuration

Projects can be configured via a project config file that resides in the .wash directory at the project root, and which may be expressed in JSON, YAML, or TOML format.

Top-level project configuration options include:

Option	Type	Description
version	string	Configuration schema version
build	object	Build configuration options
dev	object	Development server configuration options
wit	object	WIT dependency management configuration

version configuration

Specify the wash version for this project.

Example:

yaml

version: 2.3.0

build configuration

Wasm Shell builds WebAssembly component binaries by wrapping language-specific utilities like cargo, go, npm, etc, and project configuration files are used to define configuration for builds.

Wasm Shell executes the build command for your language toolchain specified in your project configuration file.

build options

Option	Type	Default	Description
command	string	-	Build command to execute
env	map	{}	Environment variables to set during the build process
component_path	string	-	Path to the output Wasm component file

build examples

Rust

yaml

build:
  command: cargo build --target wasm32-wasip2 --release
  component_path: target/wasm32-wasip2/release/project_name.wasm

TinyGo

yaml

build:
  command: go generate ./... && tinygo build -target wasip2 -wit-package ./wit -wit-world example -o build/output.wasm ./
  component_path: build/output.wasm

TypeScript

yaml

build:
  command: npm run install-and-build
  component_path: dist/output.wasm

This build command will execute the install-and-build script defined in your TypeScript project's package.json file. Make sure the value for component_path matches the path defined in your build script.

dev configuration

wash dev builds a component according to the specified build options (unless otherwise specified in the dev options) and then starts a local development server. There are a variety of options available for local development.

dev options

Option	Type	Default	Description
command	string	-	Custom command to run for building during development
address	string	-	Address for the development server to listen on
service	boolean	false	Whether to run as a long-running service with port binding
service_file	string	-	Path to a service definition file
components	array	[]	Additional components to load during development
volumes	array	[]	Volumes to mount from host to guest
host_interfaces	array	[]	WIT interfaces to expose from the host
tls_cert_path	string	-	Path to TLS certificate file for HTTPS
tls_key_path	string	-	Path to TLS private key file for HTTPS
tls_ca_path	string	-	Path to TLS CA certificate file
wasi_webgpu	boolean	false	Enable WASI WebGPU support
wasi_keyvalue_path	string	-	Path for WASI key-value store data
wasi_blobstore_path	string	-	Path for WASI blob store data
data_nats_url	string	-	Unified NATS URL for blobstore, keyvalue, and messaging plugins (introduced in 2.4.0). Per-plugin URLs override it.

2.4.0: unified data_nats_url

Setting dev.data_nats_url points the blobstore, keyvalue, and messaging plugins at a single NATS endpoint at once, mirroring the production host's --data-nats-url. The existing per-plugin URLs (wasi_keyvalue_nats_url, wasi_blobstore_nats_url, etc.) still work and take precedence when set. This release also brings a NATS-backed blobstore to wash dev for the first time.

dev.components[]

Additional components to load alongside your main component. Starting in 2.4.0, each entry accepts per-component overrides of the workload-wide environment, config, and allowed-host lists; the override fields mirror the localResources shape on a WorkloadDeployment.

Field	Type	Description
name	string	Name identifier for the component
file	string	Path to the component Wasm file
environment	object	Environment variables (wasi:cli/env) merged over workload.environment. This component wins on key conflicts. Introduced in 2.4.0.
config	map	Opaque key-value config merged over workload.config. This component wins on key conflicts. Introduced in 2.4.0.
allowedHosts	array	Outbound HTTP allowlist. When set, replaces workload.allowedHosts for this component ([] denies all egress); when omitted the workload list applies. Introduced in 2.4.0.

2.4.0: workload values apply to every component

Workload-wide workload.environment, workload.config, and workload.allowedHosts are now the base layer for every component in a dev workload, including sidecars loaded via dev.components[] and the service from dev.service_file. Before 2.4.0, only the main dev component received these values; sidecars saw default LocalResources and were silently missing env vars and allowed-host policy.

Multi-component messaging workloads also become possible in this release: more than one component in the same workload can now export the same host-invoked interface (for example, two NATS subscription handlers), where workload linking previously rejected duplicates.

dev.volumes[]

Volume mounts for filesystem access from within the Wasm component.

Field	Type	Description
host_path	string	Path on the host filesystem
guest_path	string	Path as seen from within the Wasm component

dev example

yaml

dev:
  command: cargo build --target wasm32-wasip2 --debug
  address: 127.0.0.1:8080
  service: true
  wasi_webgpu: true
  tls_cert_path: "./certs/cert.pem"
  tls_key_path: "./certs/key.pem"

wit configuration

Configuration for WIT (WebAssembly Interface Type) dependency management.

wit options

Option	Type	Default	Description
registries	array	wasm.pkg registry	Registries for WIT package fetching
skip_fetch	boolean	false	Skip fetching WIT dependencies
wit_dir	string	./wit	Directory where WIT files are stored
sources	map	{}	Source overrides for WIT dependencies (target → source mapping)

wit.registries[]

Registry configuration for fetching WIT packages.

Field	Type	Description
url	string	Registry URL endpoint
token	string	Optional authentication token

wit example

yaml

wit:
  wit_dir: "./wit"
  skip_fetch: false
  registries:
    - url: "https://private-registry.example.com"
      token: "${REGISTRY_TOKEN}"
  sources:
    "wasi:http": "https://github.com/WebAssembly/wasi-http/archive/refs/tags/v0.2.0.tar.gz"