rockDemo

Run Killercoda-style markdown scenarios as live, clickable demos inside VS Code. Instead of copy-pasting commands during a demo, rockDemo renders Run / Copy buttons above your code blocks and can drive a full multi-step scenario in real Docker containers — you just click through it.

Killercoda-compatible. Scenarios you already wrote for Killercoda (an index.json plus step markdown with {{exec}} / {{copy}} / {{open}} annotations) run in rockDemo unchanged. Scenario authoring syntax is documented by Killercoda: https://killercoda.com/creators.

Prerequisites

• VS Code 1.75 or newer.
• Docker, installed and running, on your PATH — required for scenario mode (the containers that back each step). Check with docker ps.
• Windows: use WSL2. Docker-backed scenarios need a Linux container host. Install Docker Desktop with WSL integration enabled (or Docker inside your WSL distro), open your project in VS Code via WSL (Remote - WSL), and run rockDemo from there so it talks to the Linux Docker daemon.

Plain single-file markdown demos (just the Run/Copy buttons) work without Docker. Docker is only needed for the JSON scenario player.

Run a scenario (the main use case)

A scenario is a folder containing an index.json (Killercoda format) and its step markdown files.

1. Open the scenario's index.json in VS Code.
2. Click the ▶ Run demo button in the editor title bar (top-right, next to VS Code's own preview button). This opens the scenario player.
3. The player shows an intro screen (title + description) with a START button. rockDemo has already launched a Docker container for each node in the background; START stays disabled until the environment is ready, then lights up.
4. Click START and step through the scenario:
   • ▶ Run on a code block sends that command into the node's terminal and runs it. 📋 Copy copies it. 📂 Open opens a referenced file.
   • NEXT / PREV move between steps (NEXT may be gated until a step's check passes). FINISH ends the last step.
5. On the end screen:
   • ⟲ RESTART — tear everything down and start clean from the intro.
   • ✖ CLOSE — end the scenario (stops and removes the containers).
   • 🗑 CLOSE & CLEAR CACHE — end and wipe the image cache (see below).

Stop any time with the ⏹ Stop button in the title bar.

Presenting: DEMO mode & font size

The player has a small control cluster pinned to the top-right on every screen:

• A− / A+ — resize the player and terminal fonts together for readability.
• 🖥 DEMO MODE — toggle projection mode: a light, high-contrast look with larger fonts, forced on the player, the node terminals, and the editor (it temporarily switches VS Code to your workbench.preferredLightColorTheme so files opened via an Open button read well too). It also collapses the file-explorer side bar and the bottom panel, so all that's left on screen is the scenario and its terminals — ideal for a projector or shared screen. Click again (🖥 EXIT DEMO MODE) to return to your normal look.

Both settings persist across RESTART and reloads. Exiting DEMO mode — or stopping the scenario — restores your original color theme, terminal colors, and font size, and re-reveals the side bar and panels.

Panel Restoration Settings

By default, exiting DEMO mode or closing the scenario re-reveals all three UI panels (the File Explorer Sidebar, the bottom Terminal panel, and the Agent Panel / Auxiliary Bar). If you prefer some of these panels to remain hidden when exiting, you can customize this in your VS Code settings under rockDemo:

• rockdemo.restoreSidebar (default true): Restore the primary sidebar (Explorer) when exiting demo mode or ending a scenario.
• rockdemo.restorePanel (default true): Restore the bottom panel (Terminal) when exiting demo mode or ending a scenario.
• rockdemo.restoreAgentPanel (default true): Restore the agent panel (Auxiliary Bar/Secondary Sidebar) when exiting demo mode or ending a scenario.

Terminal Startup Settings

By default, each node terminal is cleared once it is ready (meaning the shell is available and any background/foreground configuration scripts have finished executing) to start with a clean workspace. You can customize this behavior:

• rockdemo.clearTerminalOnReady (default true): Clear the terminal window to start clean when the shell is available and all startup/foreground scripts have finished. Set to false to preserve the command output and logs of the container startup in the terminal buffer.

Extra terminals on a node

Need a second shell on a node — e.g. to tail logs while you type commands in the first? While a scenario is running you can open more terminals attached to any node's container:

• Terminal panel + dropdown → rockDemo: Node Shell, or
• Command Palette → rockDemo: New terminal on node.

With a single node the terminal opens on it immediately; with several, you pick which node. Each opens a fresh shell on the running container using that node's configured shell (falling back to sh), and closes automatically when the scenario ends.

Terminal placement

By default node terminals open in the editor area, to the right of the instructions (vertical layout) — the scenario stays visible in its own column, and each node gets its own pane.

You can configure the overall layout orientation via the rockdemo.scenarioLayout setting in VS Code:

• "vertical" (default): Places scenario instructions on the left and terminals on the right.
• "horizontal": Places scenario instructions on the top and all terminals on the bottom.

Within the terminal area, a node's split controls how its pane is placed: "right" (or true) puts it beside the previous node, "down" stacks it below — so you can build side-by-side or grid layouts. The layout reverts automatically when the scenario ends.

Try it

The repo ships runnable examples — open one and click ▶ Run demo:

• scenarios/simple/index.json — a minimal scenario.
• scenario-examples/ — a gallery covering assets, multi-node Kubernetes, step verification, and more.

Run a single markdown file (no Docker)

Open any markdown file with fenced code blocks. rockDemo adds Run / Copy buttons (CodeLens) above the actionable ones — great while writing or giving a quick walkthrough. Click ▶ Run demo in the title bar to see the rendered, button-driven preview. bash / sh / shell blocks are runnable by default; add {{exec}}, {{copy}}, or {{open}} on a block's closing fence to control the buttons (Killercoda syntax).

Authoring scenarios

rockDemo follows the Killercoda scenario format, so the authoring guide lives there: https://killercoda.com/creators. In short, a scenario folder has an index.json describing the environment (backend / nodes) and an ordered list of steps (details.steps), each pointing at a markdown file. Annotate commands in that markdown with {{exec}} (run), {{copy}}, or {{open}}.

Custom Terminal Background Colors

While in DEMO MODE, you can dynamically change the background color of the terminal when executing a code block. To do this, add a background=<color> modifier to the {{exec}} annotation:

```bash
echo "Changing background to grey!"
```{{exec background=grey}}

```bash
echo "Returning terminal to default style"
```{{exec background=default}}

Both hex codes (e.g. background=#1e1e1e) and standard CSS color names (e.g. grey, black, navy) are supported. Use background=default to reset the terminal background back to the theme default. Note that this feature is active only while DEMO MODE is toggled on.

[!NOTE] VS Code Limitation: Due to a VS Code API limitation, setting a terminal background color dynamically changes the background color globally for all integrated terminals in the workspace, not just the single target terminal.

⚠️ Not Killercoda-compatible: Custom terminal backgrounds are a rockDemo-only feature. Killercoda does not support the background modifier and will ignore it.

Targeting Specific Terminals

In multi-node environments, you can direct a command to execute on a specific node terminal by adding the target=<node> modifier to the {{exec}} annotation:

```bash
echo "Hello from controlplane!"
```{{exec target=controlplane}}

```bash
echo "Hello from worker node 01!"
```{{exec target=host02}}

The target can be:

• The node's real name (e.g. controlplane).
• The node's optional alias configured in the backend profile (e.g. host01).
• Positional aliases automatically mapped by rockDemo based on the node order: host1/host01, host2/host02, etc.

When target is not set, the command is executed in the active terminal (or falls back to the first node terminal).

⚠️ Not Killercoda-compatible: The target modifier is a rockDemo-only feature. Killercoda does not support target annotations and will ignore them.

Multi-node environments (backendExtended)

Killercoda scenarios select an environment with a single backend.imageid. rockDemo adds an optional backendExtended block for richer, multi-container setups — an ordered list of nodes, each with its own image, shell (cmd), static IP, Docker-in-Docker, systemd, startup scripts, and terminal layout (stacked tabs or a side-by-side split via layout / per-node split):

"backendExtended": {
  "layout": "split",                 // "stacked" (default) | "split"
  "nodes": [
    { "name": "controlplane", "imageid": "…", "cmd": "bash", "ip": "172.30.1.2" },
    { "name": "node01",       "imageid": "…", "cmd": "bash", "ip": "172.30.1.3" }
  ]
}

⚠️ Not Killercoda-compatible. backendExtended is a rockDemo-only extension — Killercoda does not understand it and will ignore it, so a scenario that depends on it won't reproduce the same environment there. If you need your scenario to run on Killercoda too, stick to backend.imageid; reach for backendExtended when you specifically want rockDemo's multi-node features.

The full node schema (all fields, networking, layout, backend startup scripts) is in the technical reference.

For rockDemo-specific behavior and the exact index.json fields it supports (backends, multi-node networking, assets, step gating, traffic links), see the technical reference (REFERENCE.md).

Image cache (fast restarts)

Bringing up a container environment — especially a Kubernetes cluster — means pulling container images, which is the slow part of starting a demo. rockDemo keeps a persistent image cache so you only pay that cost once:

• The first run of a backend pulls its images from the network.
• Every run after that (including RESTART) starts from the warm cache — no re-pull. A normal Stop keeps the cache on purpose.

The cache is per-backend, so different scenarios that use the same environment share it automatically.

Persistent /rockdemo cache volume

In addition to the nested runtime image caches, rockDemo mounts an extra persistent cache volume at /rockdemo inside all scenario containers. This volume is unique per container (so multiple nodes in a backend get their own distinct volumes) and persists data across stops and restarts for warm state preservation.

When the image cache is cleared (via the actions below), the /rockdemo cache volumes are also automatically deleted.

Clearing the cache

Clearing is always deliberate — do it to reclaim disk or force a fresh pull:

• Command Palette → rockDemo: Clear image cache (removes all cached images not currently in use, and reports how much was freed).
• End screen → 🗑 CLOSE & CLEAR CACHE (ends the scenario, then clears).
• Stop dropdown (the ⋯ next to the title-bar Stop) → Stop and clear image cache.

Note: the cache also preserves state created inside Docker/podman nodes (containers, volumes) between runs, so RESTART isn't a fully clean slate for those scenarios — clear the cache when you want a pristine start.

Learn more

• REFERENCE.md — full technical reference: annotations, the index.json schema, backends, networking, assets, step gating, traffic links, bundled Docker images, and the cache internals.
• BUILD.md — how rockDemo is built, versioned, and published.

License

Apache-2.0. Bundles highlight.js (BSD-3-Clause) for syntax highlighting — see media/LICENSE-highlight.js.