Getting started with Custom Executables

Custom executables are a fairly new feature in CasualOS that lets you do anything a normal website can do while still taking advantage of bots and the CasualOS data model. Unlike Listen Tags, Custom executables allow you to access the Web Browser DOM to create experiences.

At their most basic, custom executables work by finding tags that start with a specific tag prefix and bundling them together into one big script. This big script is then injected into an iframe. Because iframes are a separate execution environment, the script can do whatever it wants without affecting the rest of CasualOS. This is different than listen tags which are executed inside CasualOS and are therefore restricted in what they can do.

Tag prefixes

Tag prefixes are used by CasualOS to indicate that a tag value should be interpreted in a particular manner. For example, the "@" symbol is used to specify that a value should be treated as a listen tag and the "🧬" emoji is used to specify that a value is JSON data.

Tag prefixes are also very easy to use: you just put the symbol/emoji at the beginning of the value.

You can also define your own tag prefixes by using the os.registerTagPrefix(prefix, options?) function. Whenever making a custom executable, it is recommended that you also use your own tag prefix so that conflicts with other custom executables are not likely.

Creating your first executable

Let's create a custom executable!

It is very easy to get started. First, register a tag prefix. Then open a executable from a tag.

Let me show you how this is done in practice: