WASI preopen directory and environment configuration for repeatable Wasmtime modules

Direct Answers

1. Declare WASI snapshot_1 (preview2) as the host version. This stabilizes preopened directory rights across Wasmtime releases.

2. Store environment variables and arguments in a version-controlled manifest (e.g., wasi.json) alongside the module. The host reads this manifest to populate WasiConfig::args and WasiConfig::env at startup.

3. Outbound TCP access is not part of core WASI. It must be granted explicitly via runtime-specific extensions such as Wasmtime's WasiConfig::tcp_connect; treat it as an explicit host permission.

Explanation and Confirmed Facts

Snapshot Version Stability

WASI snapshot_1 (preview2) defines the wasi:filesystem/types.preopens interface, which fixes the preopen directory contract. Wasmtime has maintained backward compatibility for this interface since its stabilization. Compiling modules against snapshot_1 ensures the same file descriptor layout across Wasmtime versions.

Confirmed: Wasmtime release notes (v20.0.0+) show no breaking changes to snapshot_1 preopen semantics.

Assumption: You are using Wasmtime ≥ 20.0.0. Older versions may have partial preview2 support.

Environment and Argument Versioning

There is no cross-runtime standard for embedding WASI environment state in the module. The portable approach is a sidecar manifest:

{
  "module": "app.wasm",
  "wasiVersion": "preview2",
  "preopens": {
    "/host/data": "/app/data",
    "/host/config": "/app/config"
  },
  "args": ["app", "--config", "/host/config/settings.toml"],
  "env": {
    "APP_ENV": "production",
    "LOG_LEVEL": "info"
  }
}

The container entrypoint reads this file, constructs WasiConfig, and passes it to the Wasmtime engine. This keeps the WASI state reproducible and auditable.

Caution: Embedding a custom WASM section for env/args is possible but non-portable; other runtimes will ignore it.

Outbound TCP Access

Core WASI (snapshot_0 and snapshot_1) does not include sockets. Wasmtime exposes networking through the wasi:io/poll and wasi:socket/* interfaces, which are opt-in via WasiConfig::tcp_connect (and related methods). Without explicit permission, socket calls return ENOTCAPABLE.

Verification step: Compile a test module that attempts tcp_connect; run with and without WasiConfig::tcp_connect enabled to confirm the permission gate.

Minimal Reproducible Setup

1. Install wasi-sdk (≥ 24.0) and Wasmtime (≥ 20.0.0).
2. Compile your module targeting wasm32-wasip2 (snapshot_1).
3. Create wasi.json manifest as shown above.
4. Write a small host launcher (Rust, Go, or Python) that:
   • Parses wasi.json
   • Builds WasiConfig with preopens, args, env
   • Optionally enables tcp_connect for specific addresses
   • Instantiates and runs the module
5. Containerize the launcher, manifest, and module together.

Verification Commands

# Check Wasmtime version and WASI support
wasmtime --version
wasmtime --help | grep -i wasi

# Run module with manifest-driven config (example using a Rust launcher)
cargo run --release -- manifest=wasi.json module=app.wasm

# Test TCP permission denial
# (module compiled with socket import, run without tcp_connect)
wasmtime run --dir=/host/data app.wasm 2>&1 | grep -i enotcapable

Missing Diagnostic Detail

Which language and Wasmtime API (Rust wasmtime crate, Go wasmtime-go, Python wasmtime) are you using for the host launcher? The exact WasiConfig construction differs slightly, and I can provide a concrete snippet for your stack.