Build with your own tools

Overview

Quickstart

<!-- In <head>, before your own scripts -->
<script src="https://apps.vibeoscloud.com/sdk/v1/vibeos-dev.js"
        data-manifest="./vibe.json"></script>

{
  "name": "My VibeOS App",
  "description": "Saves notes and asks the AI for ideas.",
  "iconEmoji": "✨",
  "iconBg": "linear-gradient(135deg,#10b981,#0ea5e9)",
  "icon": "./icon.png",
  "version": "1.0.0",
  "permissions": {
    "read": ["home/Documents"],
    "write": ["home/Documents"],
    "ai": true,
    "network": ["https://api.open-meteo.com/v1"]
  }
}

function vosReady() {
  return window.vos
    ? Promise.resolve(window.vos)
    : new Promise((r) => addEventListener("vos-ready", () => r(window.vos), { once: true }));
}

const vos = await vosReady();
await vos.fs.writeFile("home/Documents", "hello.md", "# Hi from localhost");
const reply = await vos.ai.chat([{ role: "user", content: "Say hello" }]);

Sample apps

Complete apps you can open, read and change. Each download has an index.html with the dev script tag, a vibe.json, a README and the packager. Double-click index.html to run it; AI Chat and News Reader also need a developer key.

Get them all in vibeos-samples.zip — they're also in the starter kit's samples folder.

Developer keys

Files work straight away. AI and network calls run through VibeOS under your account, so they need a developer key. Create one in Dashboard → Developer SDK, then click the VibeOS dev badge in the corner of your page and paste it (or run vosDev.setKey("vdk_…") in the console).

• The key is saved in your browser, not your code, so it can't leak into a submitted app.
• Keys only work from localhost, 127.0.0.1 and file:// pages.
• AI calls use your own plan and AI credits, with the same messages for sign-in, plan and credit problems.
• Revoke a key any time; pages using it lose AI and network access immediately.

How dev mode behaves

Errors reject with a plain Error carrying only a message, the same as in VibeOS. See Errors & limits.

Vite, React & TypeScript

Put the dev script tag in your index.html and copy vibeos.d.ts into src/. Nothing to install from npm, and no imports: window.vos is provided at runtime.

// src/main.ts — works the same in dev, in VibeOS and after packaging
/// <reference path="./vibeos.d.ts" />

const vos = await new Promise<VibeOS.Vos>((resolve) =>
  window.vos ? resolve(window.vos) : addEventListener("vos-ready", () => resolve(window.vos!), { once: true }),
);
const notes = await vos.fs.readDir("home/Documents");

Assets

A .vibe app is one HTML document. The packager inlines local JS and CSS; images, fonts and other files must be inlined as data: URLs (Vite: build.assetsInlineLimit), stored with vos.fs, or loaded from a URL in your network permissions. Keep the page under 2 MB.

Package & submit

# plain HTML project
node vibeos-pack.mjs index.html vibe.json

# Vite / Parcel / any build that outputs dist/
npm run build
node vibeos-pack.mjs dist/index.html vibe.json -o my-app.vibe

Upload the .vibe file on Submit App, or try it on your own desktop first via VibeOS → App Center → Install from File. You can also open the file in the IDE to keep editing there.

Configuration

To keep permissions checked on a double-clicked page, put the manifest inside the page, before the dev script. The packager removes it, and uses it as your manifest when there's no vibe.json.

<script type="application/json" id="vibe-manifest">
  { "name": "My App", "permissions": { "read": ["home/Documents"], "write": ["home/Documents"] } }
</script>
<script src="https://apps.vibeoscloud.com/sdk/v1/vibeos-dev.js"></script>

Script attributes: data-manifest, data-badge="false". Or set window.VIBEOS_DEV before the script loads:

<script>
  // Optional — set before vibeos-dev.js loads
  window.VIBEOS_DEV = {
    manifest: "./vibe.json",   // or manifestData: { ...inline manifest }
    badge: false,              // hide the corner badge
  };
</script>
<script src="https://apps.vibeoscloud.com/sdk/v1/vibeos-dev.js"></script>

Dev helpers

window.vosDev exists only in dev mode — never call it from app code you ship.

vosDev.setKey("vdk_…")     // save a developer key in this browser
vosDev.clearKey()
vosDev.files()              // every file the app saved, as { path: content }
vosDev.exportFiles()        // JSON string — handy for fixtures
vosDev.importFiles(json)    // load fixtures; fires vos-fs-change
vosDev.resetFiles()         // start from an empty home folder
vosDev.status()             // version, key, file count and where permissions came from