ε Epsilon

Epsilon is a pure Go WebAssembly runtime with zero dependencies.

• Fully supports WebAssembly 2.0 Specification
• Runs on any architecture supported by Go (amd64, arm64, etc.) without requiring CGo
• Allows embedding WebAssembly modules in Go applications
• Includes experimental WASI Preview 1 support
• Includes a command-line interface

Installation

As a Library

To use Epsilon in your Go project:

go get github.com/ziggy42/epsilon

As a CLI Tool

To install the epsilon command-line interface:

go install github.com/ziggy42/epsilon/cmd/epsilon@latest

Quick Start

Basic Execution

Load and run a WebAssembly module directly from a byte slice:

package main

import (
	"fmt"
	"os"

	"github.com/ziggy42/epsilon/epsilon"
)

func main() {
	// 1. Read the WASM file
	wasmBytes, _ := os.ReadFile("add.wasm")

	// 2. Instantiate the module
	instance, _ := epsilon.NewRuntime().InstantiateModuleFromBytes(wasmBytes)

	// 3. Invoke an exported function
	result, _ := instance.Invoke("add", int32(5), int32(37))

	fmt.Println(result[0]) // Output: 42
}

Using Host Functions

Extend your WebAssembly modules with custom Go functions and more using ModuleImports:

// Create imports before instantiation
imports := epsilon.NewModuleImports("env").
	AddHostFunc("log", func(m *epsilon.ModuleInstance, args ...any) []any {
		fmt.Printf("[WASM Log]: %v\n", args[0])
		return nil
	})

// Instantiate with imports
instance, _ := epsilon.NewRuntime().
	InstantiateModuleWithImports(bytes.NewReader(wasmBytes), imports)

CLI

Usage

Usage:
  epsilon [options] <module> [function] [args...]

Options:
  -arg value
        command-line argument
  -dir value
        directory to mount (use /from=/to to mount at a different path)
  -env value
        environment variable (KEY=VALUE)
  -fuel value
        enable instruction fuel (e.g. 1000000000 for ~1s of execution)
  -version
        print version and exit

Examples:
  epsilon module.wasm                     Run module.wasm
  epsilon module.wasm add 5 10            Call add(5, 10)
  epsilon -fuel 1000000 module.wasm       Run with 1M instruction fuel
  epsilon -dir /host=/guest module.wasm   Mount /host as /guest

Example

$ epsilon https://github.com/mdn/webassembly-examples/raw/refs/heads/main/understanding-text-format/add.wasm add 10 32
42

Development

A complete set of development targets is defined in the Makefile. Run make (or make help) to view the available targets:

Usage: make <target>

Targets:
  help                  Show this help
  build                 Compile all Go packages
  build-all             Cross-compile the CLI for Linux, Darwin, and Windows
  run-example           Run the basic example (smoke check)
  fmt                   Run gofmt across the tree
  fmt-md                Format repo-owned Markdown
  fmt-c                 Format benchmark C sources
  vet                   Run go vet across the tree
  clean                 Remove built artifacts (keeps the wasi-sdk toolchain)
  distclean             Remove built artifacts AND the wasi-sdk toolchain
  test                  Run all Go tests (unit + spec)
  test-spec             Run wasm spec tests
  test-wasi             Run the WASI testsuite
  test-all              Run all tests (Go tests + WASI spec tests)
  bench                 Run benchmarks (vars: BENCH_PATTERN, etc.)
  bench-compare         Compare benchmarks across refs; TARGET=<ref> required
  build-wasm            Rebuild benchmark .wasm files
  setup-wasi-sdk        Install wasi-sdk locally
  setup-wabt            Install WABT locally (one-time)

Common overrides:
  BENCH_PATTERN=<pat>   go test -bench filter (default: .)
  BENCH_TIME=<dur>      go test -benchtime (default: 1s)
  BENCH_COUNT=<n>       iterations (default: 3)
  WASI_SDK_DIR=<p>      wasi-sdk path (default: .toolchain/wasi-sdk)

Targets that need external toolchains (wasi-sdk for build-wasm, wabt for the spec tests) auto-install them into .toolchain/ on first run. test-wasi additionally needs uv installed on the host.

Contributing

See CONTRIBUTING.md for details.

License

Apache 2.0; see LICENSE for details.

Disclaimer

This is not an officially supported Google product. This project is not eligible for the Google Open Source Software Vulnerability Rewards Program.