OpenCockpit
Agent

HTML Apps

A plain HTML preview is static — try to pull real data from the page and the same-origin sandbox blocks it via CORS. HTML apps tear that wall down: /html has the AI generate a small app, and the preview injects a window.cockpit SDK — essentially the Bash tool exposed to the page. Now a button can curl for data, read/write files, or run a script. A static page becomes a mini-app with a backend.

It's a built-in command in the Skills / menu, resolving the same way as /qa or /fx. The generated page runs in the chat preview modal, the Explorer file browser, or a Console browser bubble — and you can bookmark it into an HTML panel to reopen anytime.

Generate one with /html

Type /html in the Agent chat box, followed by the page you want:

/html Build me a GitHub repo star dashboard — type a repo name, show stars, forks, and recent commits

The rest is the AI's job — you just describe what you want, not how to build it. By default it will:

  • generate a React page (zero-build; the dependencies are hosted locally by Cockpit, so it works offline);
  • apply the Cockpit theme automatically, with light/dark and a top-right toggle;
  • fetch/update data through cockpit.bash (not fetch(externalURL) — CORS blocks it).

These rules live in the built-in /html prompt; you normally don't need to think about them. When you want to hand-edit a page, see the SDK cheatsheet below.

cockpit SDK cheatsheet

The global is ready on page load — no library to import:

APIWhat it does
cockpit.cwdDirectory of the current file; relative-path commands run here
cockpit.bash(command, opts?)Run one bash command, mirroring the Bash tool
cockpit.toggleTheme()Switch light/dark (there's a top-right button too)

cockpit.bash returns the full output in the foreground, or streams in the background:

// Foreground: short command, await for { stdout, stderr, exitCode }
const { stdout, exitCode } = await cockpit.bash("curl -s https://api.github.com/repos/Surething-io/cockpit");
if (exitCode !== 0) { /* the command ran but failed — show stderr */ }
const repo = JSON.parse(stdout);

// Background: long/live command, opts.background + callbacks, returns { kill() }
cockpit.bash("tail -f ./build.log", { background: true, onOutput: c => { /* … */ } });

For a complex backend (multi-step, DB writes), have the AI write a script file next to the page and call it with cockpit.bash("node ./api.js") — CGI-style: the page renders, the script handles the backend.

⚠️ Previewing runs the file. cockpit.bash is a real command-execution channel — equivalent to a shell on your machine. Previewing a local .html in Cockpit executes its scripts with your privileges, exactly as risky as running the file yourself. So don't preview or bookmark an .html you don't trust — an unknown/third-party page can do anything you can from a terminal. (It still obeys Cockpit's startup token gate: open on localhost without --token, validated when one is set.)

Opening and bookmarking

Once generated, you have a few entry points:

  • Chat preview modal: click the reply to preview. Top-right has two buttons — Add to HTML panel (bookmark icon) and Open in Console bubble (external-link icon).
  • Explorer file browser: select any .html to read its source; click Preview to render and run it — HTML never auto-previews, so that click is what grants the page its SDK. The toolbar has the same two buttons.
  • Console browser bubble: a persistent place to keep an app running across the session. Every preview now runs with the SDK (chat modal, Explorer, bubble) — the bubble just survives tab switches.

The HTML panel

The first icon in the sidebar's Apps dock opens the HTML Apps modal. It lists your bookmarked apps, with search at the top, plus an Add button for manually registering an existing .html file by absolute path. When the list is empty, the modal points you to /html or lets you add an existing HTML file.

Each card's title / description / icon come from the page's <head>:

<title>Repo Dashboard</title>
<meta name="cockpit-name" content="repo-dashboard">
<meta name="description" content="Track stars, forks, and commits.">
<meta name="cockpit-icon" content="⭐">

Click a card to preview it. Hover a card to reveal Open in Console bubble and Delete; the copy button next to the path copies the file path. Minimized previews stay in the sidebar Apps dock, where clicking their icon restores the same running preview. If a file was deleted or moved, the card is dimmed and marked Invalid; you can still delete it or copy its path, but you cannot open or preview it.

The panel records absolute paths only; the registry lives in ~/.cockpit/html.json (same mechanism as skills.json). The HTML files themselves stay in your project — the panel is just a bookmark folder. Manual adds require an absolute path to an existing, readable .html or .htm file.

Quick-open with /name

Type / in the Console input bar and registered apps appear ahead of custom commands (tagged with a blue HTML label); select or press Enter to open one in a bubble. The short name is the cockpit-name from the page meta. It never intercepts real commands — /usr/bin/x is still treated as a path.

Next

Edit this page on GitHub ↗