/app Editor — User Manual

1. What is RouterOS /app?

RouterOS 7.22+ introduced /app — a YAML-based format for packaging and deploying containerized applications directly on a MikroTik router. Think of it as a lightweight docker-compose — but RouterOS-specific, with its own networking model, placeholder system, and deployment lifecycle.

A single /app definition bundles everything a container needs: which image to pull, which ports to expose, which volumes to mount, and optional metadata like a name, description, category icon, and even a default web-UI page. MikroTik ships a growing library of built-in apps (Home Assistant, code-server, Pi-hole, and more) that can be explored and customized using this editor.

The /app YAML format is not compatible with standard docker-compose — the port notation, networking model, and placeholder tokens are RouterOS-specific. This editor and schema are designed specifically for the RouterOS dialect.

2. Getting Started

Open tikapp.html. On your very first visit (no saved session), the editor loads the code-server built-in example and opens the example picker automatically so you can browse all available apps.

1. Browse examples — use the category and app dropdowns to explore built-in MikroTik apps. Switching app when the editor is unmodified loads it instantly.
2. Customize — edit the YAML in the Monaco editor. Schema validation runs live. Errors appear below the editor.
3. Deploy — copy the resulting YAML to your router via the Copy /app/add button, or download the file and use the RouterOS Files menu.

3. Editor Interface

Toolbar (Line 1)

Example Picker (Line 2)

When the Examples button is active, a second row appears with a category dropdown and an app dropdown. Changing either when your current content is a clean (unmodified) example will immediately load the new example — no extra click needed. If you have edited the current example, the editor asks before replacing it. See §4 for full details.

Double-clicking an app name in the picker also loads it immediately.

Monaco Editor Controls

The editor is Monaco — the same engine that powers VS Code. All standard keyboard shortcuts work. Here are the most useful ones:

Browser differences: On some browsers (especially Firefox), Ctrl+W closes the tab instead of triggering an editor action — be careful. On macOS, ⌘ shortcuts are used instead of Ctrl.

Live Validation

Every change is validated against the JSON Schema for the selected RouterOS version. The validation summary below the editor turns green when valid, red when there are errors. Click the summary to expand the error list — click any error to jump to that line in the editor.

Action Bar (Bottom)

4. Examples, Stash & Dirty Editing

Understanding the dirty state model is the key to moving smoothly from browsing examples to editing your own app.

Clean vs. Dirty

The editor tracks whether the current content was loaded from a built-in example and whether it has been modified. Content is clean if it exactly matches the loaded example; it becomes dirty as soon as you make any change.

Browsing Examples (Clean State)

When the editor is in a clean example state — meaning you haven't edited anything yet — switching the app dropdown instantly loads the newly selected example. No extra click needed. This makes it easy to quickly preview any of MikroTik's built-in apps.

What Happens When You Edit an Example?

The moment you change anything, the status bar shows:

Editing 'code-server' example — changes not yet stashed. [Stash] [Discard]

• [Stash] — saves your changes to the stash slot, then clears the "example mode" so you can browse freely. If a stash already exists, you'll be asked to confirm before replacing it.
• [Discard] — reverts the editor back to the original example YAML, discarding your changes.

If you try to load a different example while the content is dirty, the same Load / Stash / Cancel choice appears:

'code-server' was edited — load 'pihole'? [Load] [Stash] [Cancel]

Stash — Your Scratch Pad

The stash is a single named slot in your browser's localStorage. Use it to:

• Preserve work-in-progress while you quickly look at another example
• Temporarily park a half-finished custom app before browsing
• Keep a "last good" version handy while experimenting

Restore the stash at any time with Recall Stash in the toolbar. The stash persists across page reloads until you explicitly replace it. Stashing again when a stash already exists prompts for confirmation.

Autosave

Every keystroke is silently autosaved to a separate localStorage key. On reload, your last session is restored automatically, so you never lose unsaved work. This autosave is independent of the stash.

Going from Example to Custom App

A typical workflow for building a custom app from an existing example:

1. Browse examples to find a similar app (e.g. code-server)
2. Start editing — the dirty indicator appears
3. Click [Stash] in the status bar to save a checkpoint
4. Keep editing; use Recall Stash to roll back if needed
5. When satisfied, use ⬇ Download or Copy /app/add to deploy

5. app-store-urls= Mode

RouterOS supports hosting a collection of app definitions on a web server and referencing them with /app set app-store-urls=http://…. The store file is an array of individual /app definitions in a single YAML document.

The app-store-urls= toggle in the toolbar switches the editor between single-app mode and store mode. It does more than change the validation schema:

• Toggling ON (single → store): if the current content is a valid single /app definition, it is automatically wrapped in a YAML array. If the content is not valid, you are offered the choice to Enable Anyway (schema only, no conversion) or Cancel.
• Toggling OFF (store → single): if the store contains exactly one app, it is automatically unwrapped to a single definition. If it contains multiple apps, you are asked whether to disable just the schema (keeping the array content) or cancel.

Filenames for download use .tikapp.yaml for single apps and .tikappstore.yaml for store files. These extensions are recognised by the VS Code YAML extension when the schemas are configured — see README → VSCode setup.

6. Sharing & Exporting

🔗 Share

Click Share in the action bar. The current URL — which encodes the selected version, schema mode, and the full YAML content — is copied to your clipboard. Share the link with anyone: opening it in a browser restores the exact editor state.

The YAML is encoded directly in the URL query string. Typical /app definitions share reliably; very large configs may hit browser or server URL length limits, in which case Download or Copy YAML are good fallbacks.

⬇ Download

Saves the YAML as a local file. The filename uses the app's name field when available (e.g. my-app.tikapp.yaml).

📋 Copy

Copies the raw YAML text to your clipboard.

Copy /app/add

Generates and copies the complete RouterOS CLI command:

/app add yaml="name: my-app
services:
  server:
    image: …"

Paste this directly into a RouterOS terminal or the WinBox terminal. Only available in single-app mode.

7. Behind the Scenes — How the Schema Gets Here

The editor's live validation is powered by a JSON Schema that is generated automatically from a real RouterOS router. Here is how the pipeline works — a quick look behind the curtain.

The schema files at routeros-app-yaml-schema.latest.json and routeros-app-yaml-store-schema.latest.json are also available as stable public URLs, making them suitable for use with the VS Code YAML extension and potentially SchemaStore (which would auto-apply the schema in editors without any configuration).

All of this infrastructure is open source in the tikoci/restraml repository. The project is not affiliated with MikroTik — it is a community tool built to make RouterOS app development more approachable.