> For the complete documentation index, see [llms.txt](https://docs.kouch.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kouch.dev/docs/adr/0011-wasm-plugins.md).

# ADR 0011: Sandboxed WebAssembly plugins

## Status

Accepted 2026-09-26.

## Context

The owner wants plugins for features inside the emulator. FEATURE\_PLAN §9 and §10 require Workshop content to be data only unless it is sandboxed.

## Decision

* **Runtime.** Plugins are WebAssembly modules run by `wasmtime`. By default they get no filesystem and no network access.
* **Capabilities.** The host API is versioned. Each capability a plugin wants is declared in its manifest and approved by the user:
  * Quick Menu actions and pre-launch options
  * session events
  * sending the profile's hotkeys
  * reading and writing only that emulator's `saves` and `storage` folders, never `bios`
  * toasts
  * a small settings store
* **Distribution.** Plugins come as Workshop items tagged `plugin`, or inside a `.kod` file's `plugins/` folder. They stay disabled until the user enables them.

## Consequences

* No native plugin code ever runs in Kouch's process.
* Emulator features that would need native hooking are out of scope.

## Addendum (2026-09-26, implementation)

The runtime is `wasmi` (a pure-Rust interpreter) rather than `wasmtime`: plugins are small event hooks, an interpreter keeps the build and binary light, and the fuel budget + memory cap give the same runaway protection. Implemented in `crates/kouch-plugins` (manifest, capability-checked host API, registry) and `app/src-tauri/src/plugins.rs` (session lifecycle, Quick Menu actions). ABI and capabilities: `docs/PLUGIN_AUTHORING.md`; sample: `examples/plugins/save-slots`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kouch.dev/docs/adr/0011-wasm-plugins.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.