Velocity is experimental and new — it may have issues. Report them on GitHub.

Velocity

Developers

Create a plugin

Velocity is a desktop app with a thin phone-style shell. Plugins are small HTML apps that run as tiles and talk to the shell through window.VelocityPlugin — no bundler required.

Full markdown guide on GitHub: DEVELOPERS.md

What a plugin is

A plugin is a folder with:

Examples in the repo: spotify, aura-wallpapers.

Quick start

Manifest:

{
  "id": "com.example.hello",
  "name": "Hello",
  "version": "0.1.0",
  "description": "Minimal Velocity plugin",
  "icon": "assets/icon.svg",
  "entry": "ui/index.html",
  "permissions": []
}

Use a stable reverse-DNS id. UI skeleton:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Hello</title>
  </head>
  <body>
    <h1>Hello</h1>
    <button type="button" id="done">Close</button>
    <script src="./app.js"></script>
  </body>
</html>
const api = window.VelocityPlugin;
api.ready();
api.onHostMessage((msg) => {
  if (msg.type === "velocity:theme" || msg.type === "velocity:ready") {
    // apply msg.theme.mode / msg.theme.accent
  }
});
document.getElementById("done").onclick = () => api.close();

Relative <script src="./…"> files are inlined by the host. Keep app code local to the plugin folder.

Install

  1. Open Velocity → Plugins → Browse library (official catalog), or Install from disk.
  2. For disk installs, pick a plugin folder or .zip (must include velocity.plugin.json).
  3. Review name, version, and permissions, then confirm.
  4. Open the plugin or add it to Home.

Web catalog: vty.dev/library. Dev shortcut: copy into the user plugins folder and tap Refresh list.

Typical path on macOS:

~/Library/Application Support/com.inertiaux.velocity/plugins/

Plugin repositories

Velocity loads a JSON catalog (default https://vty.dev/repo) listing HTTPS zip packages. Custom feeds: Settings → Developer mode → Plugin repo URL.

To propose a plugin for the official shelf, use vty.dev/submit (also at vty.dev/repo/submit). Schema and self-hosted sources: docs/plugin-repo.md.

Host bridge

window.VelocityPlugin is injected automatically from @velocity/sdk. Permissions are enforced; unknown methods fail.

Method Purpose
ready() Signal that the UI mounted
close() Return to the home screen
toast(message) Show a short toast
request(method, params?) Promise-based host call
onHostMessage(handler) Theme / responses; returns unsubscribe

Stable request methods: host:getTheme, host:toast, shell:openUrl, oauth:start, oauth:poll, wallpaper:*.

Permissions you may declare: network, media, wallpaper, plus reserved filesystem, notifications, clipboard.

Wallpaper plugins

Set provides: ["wallpaper"], permission wallpaper, and a wallpapers array:

{
  "permissions": ["wallpaper"],
  "provides": ["wallpaper"],
  "wallpapers": [
    {
      "id": "harbor",
      "name": "Harbor",
      "css": "linear-gradient(180deg, #0b1f2a, #7fd3c2)"
    }
  ]
}
await VelocityPlugin.request("wallpaper:apply", {
  pluginId: "com.example.pack",
  id: "harbor",
  css: "linear-gradient(180deg, #0b1f2a, #7fd3c2)",
});

Security

Submit to the library Full guide on GitHub