Skip to content

using-plugins.md

Latest commit

 

History

History
129 lines (90 loc) · 4.27 KB

using-plugins.md

File metadata and controls

129 lines (90 loc) · 4.27 KB
Raw
description Install the WASI plugin, review its access, and run a WASI module with Wago.

Using plugins

Wago keeps host capabilities outside the core runtime. Plugins add the capabilities a module needs without putting every integration into Wago itself.

In this guide, you will add WASI Preview 1 support to a local project and run a module that writes to standard output.

Inspecting an installed Preview 1 provider and running a WASI module

Before you begin

You need:

  • Wago installed with a runtime selected. Complete Getting started first if wago --version does not show an active runtime.
  • Go 1.22 or newer. Wago plugins are Go modules compiled into your runtime.

Check both tools from your terminal:

wago --version
go version

Create a local Wago project

Create or enter a directory for the example, then initialize it:

mkdir wasi-example
cd wasi-example
wago init --run

This creates a wago.json manifest. Keeping the plugin local makes the project's dependencies and reviewed access reproducible instead of changing the runtime used by every project on your machine.

Add WASI

WASI defines system-style interfaces that WebAssembly modules can import. Wago provides those interfaces through the official wago-org/wasi plugin:

wago add wago-org/wasi/p1

The /p1 suffix selects Preview 1 directly. Adding the root wago-org/wasi instead opens a provider picker; a non-interactive root install selects the whole bundle, including Preview 2 and its Component Model dependency.

Review the source, dependencies, and requested Authorities before accepting them. Plugins are native Go dependencies; grants control access to privileged Wago integration APIs, but they do not sandbox arbitrary plugin code.

Now, check to make sure it is installed:

wago plugins list

A lot of the subcommands have aliases so that it reads naturally. For example, wago plugin and wago plugins both work the same way.

The command updates wago.json, writes the complete resolved graph and reviewed grants to wago-lock.json, and builds a project runtime. Commit both JSON files with your project.

Download a WASI module

This small module imports WASI Preview 1's fd_write function and calls it from _start:

curl -fsSL https://wago.sh/corpora/wasi-hello.wasm -o wasi-hello.wasm

You can see the import before executing the module:

wago module imports wasi-hello.wasm

Run it

wago run wasi-hello.wasm

You should see:

hello from wasi

You can even compile it to a standalone executable:

::: code-group

wago compile wasi-hello.wasm -o wasi-hello
./wasi-hello
wago compile wasi-hello.wasm -o wasi-hello.exe
.\wasi-hello.exe

:::

Wago finds the nearest wago.json, selects its project runtime, and uses the WASI plugin to satisfy the module's import.

Where to go next

Pass arguments, choose environment values, and grant bounded filesystem access. Use typed Component Model exports and the Preview 2 command service from Go. Learn when to use local, global, or bare plugin selection. Understand Authorities, guest capabilities, dependency graphs, and reproducible builds. Scaffold a Go module and add a host import from definition to catalog. Find published host capabilities and runtime extensions. Fix missing Go tools, denied grants, stale lockfiles, and plugin build failures.