What is a Spark?
Learn about What is a Spark? in WaymakerOS.
A Spark is a published HTML document with a permanent, shareable URL. It is the destination for anything you have already built — a report, a dashboard, an interactive tool, a landing page, a data visualisation. If you have a finished HTML thing and want a destination for it, it is a Spark.
Sparks are designed for the moment after creation. You use OneAI or any AI tool to build something in HTML, and then you push it to a Spark so it has a home that can be visited, shared, linked to, and updated over time. The Spark holds the HTML. The URL stays the same. You update the content by publishing a new version.
Every Spark gets a slug — a short, readable URL segment — that makes the address memorable and shareable. A Spark called "Q2 Revenue Summary" might live at sparks.waymakerone.com/q2-revenue-summary.
What a Spark is not
Sparks are one of several ways to create content in Commander. Understanding the boundaries helps you pick the right tool.
A Spark is not a Document. Documents support real-time collaboration, comments, version tracking, and rich formatting blocks like tables and embeds. Documents are where your team writes together. A Spark is a published output — it does not support inline editing by collaborators. You write the HTML elsewhere and push it to the Spark.
A Spark is not a Sheet. Sheets are structured data surfaces with typed columns, row-level permissions, formula columns, and schema-driven exports. A Spark can display data from a Table using the live binding feature, but the Spark itself has no schema. It is a presentation layer, not a data layer.
A Spark is not a Host App. Host Apps go through a build pipeline — source code, dependencies, environment variables, a deployment process, a custom domain. They are the right choice for production software your customers interact with. A Spark is much lighter: plain HTML, no build step, no dependencies, no pipeline. If you need React, a backend, or a custom domain, use a Host App. If you need to publish something immediately, use a Spark.
The mental model: if you are building software, use Host. If you are publishing a finished document or visualisation, use Sparks.
Three ways to create a Spark
1. OneAI in Commander
Open the OneAI chat inside Commander and ask it to build something. OneAI can generate HTML reports, data summaries, comparison tables, visual dashboards, and interactive tools. Once you are happy with the preview, use the "Save as Spark" action to publish it directly. OneAI handles the slug, the version metadata, and the publish — you get the URL immediately.
This is the fastest path. No file management, no upload step. Build it in the conversation, publish it in one click.
2. Paste or upload HTML
From the Sparks list view, click "New Spark" and paste your HTML into the editor, or upload an .html or .spk file from your computer. Give the Spark a name, choose a slug (or accept the auto-generated one), and publish. The content goes live within seconds.
This path suits any workflow where you generate HTML outside Commander — from a separate AI tool, from a code editor, from an export pipeline.
3. Save from any AI tool via MCP
If you use Claude Code, Cursor, or any MCP-compatible AI environment, the Waymaker MCP server includes four tools for Sparks: commander_spark_create, commander_spark_update, commander_spark_get, and commander_spark_list. Your AI agent can push HTML to a Spark directly from its working environment without leaving the tool.
This is the developer path. It means your agent can build something, test it, and publish it to a permanent URL as part of a single workflow.
Sharing a Spark
Sparks share the way taskboards and documents do: through guest links. Someone outside your organisation opens the link, gives their name and email, and then sees the Spark. Every guest is listed, and you can remove any of them.
- Public. In the Spark's Settings → Sharing, turn on Public. The Spark's own address becomes a guest link: send it to anyone. Turn Public off and the link, and everyone who opened it, stops working.
- Share. The Share button makes a separate link, with an optional expiry or password, for a particular audience.
- Guests. Settings → Sharing → Guests lists everyone who has opened the Spark through either kind of link, and when. It shows the name and email each guest typed; emails are not verified. Remove one and their next visit is refused, and that email cannot register on the link again. Turning Public off ends everyone's access; when you turn it back on, people you did not remove can register again.
Nobody outside your organisation opens a Spark without giving their name and email first.
A public link works while the person who turned Public on can still edit the Spark. If they leave or lose that access, the link stops; anyone who can edit the Spark turns Public off and on again to take it over.
View-only is the default sharing mode. Guests can view the Spark but cannot edit the underlying HTML. Only workspace members with the correct permissions can publish new versions.
Within your organisation, you can share a Spark with specific people, teams, or workspaces. Permissions follow the same model as Documents: share with a person, a role, or a team. The Spark respects whatever access level you set.
Sparks can't be embedded in other websites: they open at their own link, or inside Commander. To show a Spark somewhere else, share its link.
What is a .spk file?
.spk is a Waymaker file extension for Sparks. Under the surface, it is plain HTML with a Waymaker identity extension. If you download a Spark and rename the file from .spk to .html, it will open in any browser exactly as it does inside Commander.
The .spk extension exists so that Waymaker can identify Spark files when you upload them — the upload dialog accepts both .html and .spk. It also means Spark files are easy to spot in your file system or a shared folder.
When you export a Spark using the "Download" action, you get the .spk file. You can store it locally, put it in source control, or re-upload it to any workspace. There is no proprietary binary format, no encoding, no metadata embedded in the file beyond what a standard HTML document supports.
Connecting live data (Tables binding)
A Spark can display live data from a Waymaker Table using the <meta waymaker:tables> binding pattern.
In the <head> of your HTML, declare which tables the Spark should connect to:
<meta name="waymaker:tables" content='[{"id":"tbl_xxx","access":"read"}]'>
When the Spark runs in the browser, a Waymaker shim is available as window.waymaker. Your JavaScript calls await window.waymaker.tables.read('tbl_xxx') to fetch live rows from the declared table. You can call this on page load, on a button click, or on a timer — the data comes back as a JSON array every time.
const rows = await window.waymaker.tables.read('tbl_xxx')
// rows is an array of objects — render however you like
What the shim does: When a Spark is opened, Waymaker adds the window.waymaker script to the page. Each read it makes carries a short-lived key for this one page view of this one Spark, and Waymaker checks again on every read that the viewer may still see the Spark. No password or API key is ever in the HTML.
Security model: The Spark can only read the tables it declares. Someone you share a link with, or anyone opening a public Spark, can only see the results of the queries the Spark publishes: totals and summaries, not the table's rows. Even so, think about what those totals reveal before you share a Spark built on sensitive data.
Show a document, a sheet or a folder of images
A Spark can also show a Commander Document, a Sheet, or a project folder of images in Explorer. Declare each one
as a source, the same way as a table, with its type: document, sheet or folder. Inside the Spark:
await window.waymaker.documents.read('doc_id')gives the document's title and text.await window.waymaker.sheets.range('sheet_id', 'A1:F20')gives the cells in that range.await window.waymaker.files.list('folder_id')lists the folder's images, andawait window.waymaker.files.url('folder_id', 'cover.png')gives an address to put in an image.
You can only save a Spark that uses a document, sheet or folder you can open yourself. An archived document or sheet stops showing.
Who sees them. People in your organisation who can open the Spark see them. Someone with a share link, or anyone
opening a public Spark, sees one only if you mark it "publish": true:
- a sheet must also give a
"range"(such as"A1:F20"), and only that range is shown; - for a folder, list the images to show in
"files". A share link shows only those, never the rest of the folder. Only images shared with your organisation are shown. A private image never appears on a link or a public Spark, even your own and even if it is listed: share it with your organisation first.
You confirm what a link will show. Before a Spark that shows documents, sheets or images is saved, made public or
shared by link, Waymaker lists them under "Anyone with the link will see:", each document, each sheet with its range
and each folder with its images, and nothing goes ahead until you confirm. If you later add or widen one, you confirm
again, and if someone else changes the list while you are reading it, you are shown the new list. Waymaker records who
confirmed and when. From the CLI, the list is printed with a code: run the command again with --confirm-publish <code>
to agree to exactly that list.
If you later publish more, older share links stop showing data until you share again.
A folder's "files" are names: if someone uploads a new image with the same name to that folder, the Spark shows the
new one, including over links you have already shared.
Text comes back exactly as it was written. If your Spark puts a document's text or a sheet's values into the page,
set it with textContent (or escape it) rather than innerHTML, so text that looks like HTML is shown, not run.
Sheet formulas show the value from when the sheet was last opened. Formulas are worked out when someone opens the
sheet. A formula added by an AI tool or the API has no value until then, so the Spark gets the cell marked stale
instead of a number.
See what a Spark is connected to
Open a Spark, then Settings → Sources. You'll see every table, document, sheet and folder the Spark uses, whether it only reads it or can also change it, and for a document, sheet or folder whether a share link shows it. If a source has been deleted, it shows as Removed. A source you don't have access to yourself is listed without its name.
To go the other way, open a Table's, Document's or Sheet's Settings. Used by Sparks lists the Sparks that draw on it. A Public badge marks a Spark that anyone with its link can open.
Version history
Sparks keep the last 10 versions automatically. Every time you publish a new version — whether from OneAI, from a file upload, or from an MCP push — the previous version is stored and remains accessible.
How to restore: Open the Spark, click the three-dot menu in the top-right, and select "Version history". You will see a list of the 10 most recent versions with timestamps and optional labels. Click any version to preview it. Click "Restore" to make that version the current published version.
Version labels: When you publish a new version, you can add a short label (up to 80 characters) in the publish dialog. Labels are optional but useful — "Q2 final", "corrected revenue figures", "with client logo" are the kind of notes that make version history readable three months later.
The version cap: When you publish a new version and already have 10 versions stored, the oldest version is automatically purged. There is no way to recover a version after it has been purged. If you need to keep a specific version permanently, download the .spk file before it ages out of the 10-version window.