ε 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 ModuleImportBuilder:

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

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

CLI

Usage

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

Arguments:
  <module>      Path or URL to a WebAssembly module
  <function>    Name of the exported function to invoke
  [args...]     Arguments to pass to the function

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 a WASI module
  epsilon module.wasm add 5 10            Invoke a function
  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

Building from Source

To build the CLI from source:

git clone https://github.com/ziggy42/epsilon.git
cd epsilon
go build -o bin/epsilon ./cmd/epsilon

Testing & Benchmarks

Prerequisites

• Install WABT, which is required to compile WASM code defined in text format to binary.
• Fetch the spec tests submodule:

git submodule update --init --recursive

Running Tests

# Run unit tests
go test ./epsilon/...

# Run spec tests (requires git submodule)
go test ./internal/spec_tests/...

# Run WASI spec tests
uv run --with-requirements requirements.txt wasip1/wasi_testsuite.py

# Run benchmarks
go test -bench . ./internal/benchmarks

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.