← demoshell.com

DemoShell docs

Everything you need to put a live demo of your software on your site or README. Questions this page doesn't answer: use the contact form or email konstantin@goncharuk.info.

Quickstart

A demo is a saved Linux machine ("VM") that visitors boot in their own browser tab — no servers involved. From zero to a shareable demo:

1. Create a free account. You get a starter project named demo.
2. Click the verification link we email you. You can look around before that, but building, saving, publishing and embedding stay locked until the address is verified — and accounts that are never verified are deleted after 30 days.
3. Open the project and press ▶ Build your first demo. You land in the studio's build form.
4. Pick a template or write a short build script (see below), then press Build snapshot. The build boots a base Linux image right in your browser, runs your script, and saves the result. Keep the tab open until it finishes.
5. Done — the share panel gives you a hosted demo link, a README badge, and an embed snippet.

Try it once with the built-in mc template before wiring in your own app — a working example is the fastest way to learn the shape.

Build scripts

A demo is described by a base image plus a shell script. The build boots the base image, runs the script in the VM as root, and saves the machine state when the script exits with code 0. The script is stored with the VM, so the same demo can be rebuilt any time.

Base images

Rules that matter

• The VM has internet access. apk add, curl, wget, docker pull all work during the build and inside the demo.
• Every command in the script must finish. A script that ends by starting an app which keeps running (mc, top, a foreground server) never exits, so the build waits until the timeout and saves nothing. Start such apps with the separate Start app field instead.
• Start app (optional) runs after the script and is left running when the machine is captured — visitors land straight in your app instead of at a shell prompt. The build waits for the screen to settle before saving; raise Wait after start for apps that draw and then keep loading.
• Timeout defaults to 300 seconds; raise it if your script installs a lot. Nothing is saved on a timeout or a non-zero exit — a failed build never touches the live demo.
• The demo's CPU architecture is arm64 (aarch64). Fetch arm64 binaries and images.

Example: your own binary

# fetch your arm64 linux binary and put it on PATH
apk add curl
curl -fLo /usr/local/bin/yourapp https://example.com/yourapp-linux-arm64
chmod +x /usr/local/bin/yourapp

with Start app set to yourapp.

Automatic rebuilds on release

On paid and open-source plans, add a version watch to the VM: GitHub releases or Docker Hub tags. When a new release appears, the demo is rebuilt from its script automatically. Scripts can pin the watched version with a placeholder:

apk add docker={{versions.docker}}

where docker is the watch's name. If a rebuild fails, the live demo stays unchanged and you get an email with the build log.

Sharing your demo

Every built demo has a share panel with three artifacts, easiest first:

• Share link — a full-page demo hosted by us (…/launch?snapshot=you/project:demo). Works anywhere a link works: your site's "Try it live" button, docs, chat, social posts.
• README badge — markdown for GitHub: your demo's screenshot, linking to the hosted demo. READMEs can't run scripts, so an image-that-is-a-link is the way.
• Embed — a small script tag that runs the demo inside your own page (details below).

Public and private demos

Demos are public by default: anyone with the link can run them, and embeds work from any site. A private demo needs the project's embed key, and embeds only work on domains you allow for that key — the admin's share panel handles both for you. Keys are publishable (safe to appear in page source); the allowed-domains list is what restricts private demos.

Embedding on your site

The share panel gives you a snippet like:

<div id="demoshell" style="height: 420px"></div>
<script type="module">
  import DemoShell from 'https://build.demoshell.com/embed/demoshell-embed.js';
  DemoShell.mount('#demoshell', {
    snapshot: "you/project:demo",
    server: "https://build.demoshell.com",
  });
</script>

The demo boots inline — inside your page — when the page is cross-origin isolated, which requires two response headers on your page:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

These headers also affect your page's other third-party content (every subresource must allow being embedded), so check your page still works after adding them. On a static host where you can't set headers (GitHub Pages and similar), the coi-serviceworker shim can add isolation from a service worker.

Without isolation nothing breaks: the same snippet renders a "Launch demo" card that opens the hosted full-page demo — visitors always get the demo, never a blank box. Phones get the card too; the inline VM is a desktop experience.

What software fits

• Best today: terminal (TUI) apps and CLI tools, single-binary servers (Go, Rust, C, Zig), and anything installable with apk on Alpine Linux arm64 — including Docker images via the Docker base.
• Speed: the demo runs on the visitor's CPU through emulation. It feels like a modest machine — fine for interactive apps, not for heavy builds or number crunching inside the demo.
• Not yet: heavy JVM stacks, GUI/desktop apps, multi-machine setups (Docker Compose support is coming). If you're unsure whether yours fits, send us the repo — we'll build the first demo for you and tell you honestly.
• Privacy of a session: everything a visitor does in a demo happens in their browser and disappears when the tab closes. Nothing they type or load reaches you or us.

Plans

The free plan is one project with one demo, unlimited sessions (fair use limits apply). A demo's internet access is relayed by us and metered per visitor address — 100 MB per 24 h, which is far more than a demo needs; loading the demo itself does not count against it, only what the machine downloads while it runs. Paid plans add more demos and automatic rebuilds on release; the open-source plan (free, on request) has the paid features for OSS projects. See pricing — plans are switched for you on request, via the form.