Test in your own evoX

After writing your plugin, you run it in your own evoX app and test it on your device. This page describes the full loop and common problems.

T1 (trusted-node) is not a sandbox; the code you load can access everything your Windows account can access. Load only your own/reviewed code.

Full loop

Prepare the project

npx @evoxapp/plugin-cli init my-plugin --runtime trusted-node --name "Denemem"
cd my-plugin
npm install

npm install is required — if @evoxapp/plugin-sdk and the libraries you added (obs-websocket-js etc.) are not installed into node_modules, the plugin fails with an import error when starting.

Open the Developer window

In evoX, go to the Plugins section and click the Developer button in the top bar.

Select the project and grant trust

Select the my-plugin folder with Select project. The entry moves to the Awaiting trust state; read the T1 risk text and confirm trust.

Start

Press Start. The status should go Starting → Running. If it does not, see the troubleshooting below.

Assign the action to a key

On the Keys screen, drag your plugin’s action from the action library onto a key. Press the key and rotate the knob to see the behavior.

Change → reload

After changing the code, reload in the Developer window (cycle icon, visible only while running). You don’t need to close the app. If you added a new dependency, run npm install again first.

See the logs

With the entry’s log action, see your plugin’s console.log/console.error output (bounded/redacted). This is the main place for debugging.

Status labels

Status	Meaning
Awaiting trust	You haven’t granted trust yet; confirmation is required before starting
Starting	The process was forked, waiting for the handshake
Running	The plugin is active; it receives events and can update the key
Retrying	It crashed and is being restarted with a limited budget (backoff)
Disabled due to error	It crashed too many times; fix it using the logs and start again
Stopped	You stopped it manually or it was never started

Troubleshooting

Symptom	Likely cause and fix
The project cannot be selected / invalid manifest	`manifest.json` `runtime.kind` must be `trusted-node` and `runtime.entry` (e.g. `runtime.mjs`) must be a real file in the folder. Symlinks/shortcuts are not accepted.
”Retrying” / “Disabled due to error” on start	`runtime.mjs` fails while starting. Open the logs. The most common cause: `@evoxapp/plugin-sdk` or a library cannot be found because `npm install` was not run.
The action does not appear in the key library	Is the plugin Running? Are `manifest.json` `actions[].controllers` correct (`Keypad`/`Knob`)?
The code changed but the key does not update	Reload from the Developer window. For knob behavior, make sure the action supports `Knob`.
Handshake/startup timeout	Does `runtime.mjs` call `await client.start()`? Long synchronous blocking can delay startup; set up connections lazily on `willAppear`.
The image does not appear	The `setImage` call must contain `kind:'raster'`, a `mimeType` value of `image/png`, `image/jpeg` or `image/webp`, and valid `dataBase64` bytes.

Getting started

Core concepts

Examples and distribution

Full loop

Status labels

Troubleshooting

Next step

Writing an integration plugin

Events and host-RPC reference

​Full loop

​Status labels

​Troubleshooting

​Next step

Writing an integration plugin

Events and host-RPC reference

Full loop

Status labels

Troubleshooting

Next step