ε 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.

Epsilon

Install / Use

README