Skip to content
Back to search

publisher

Publisher is the open-source analytics engine for Malloy. It lets you define data models once — and use them everywhere.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/malloydata/publisher with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/malloydata/publisher'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/malloydata--publisher/badge.svg)](/listings/malloydata--publisher)

HTML

<a href="/listings/malloydata--publisher"><img src="/api/listings/malloydata--publisher/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Run the examples

npx @malloy-publisher/server@latest --port 4000

Open **http://localhost:4000**. Three example packages are bundled — [`storefront`](examples/storefront) (a complete ecommerce model), [`governed-analytics`](examples/governed-analytics) (access control), and [`html-data-app`](examples/html-data-app) (a no-build dashboard) — all DuckDB-backed, no credentials required. The first run fetches them from GitHub.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 311 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!--
  2. Copyright (c) Credible Data Inc.
  3. SPDX-License-Identifier: MIT
  4. -->
  5. <h1 align="center">Malloy Publisher</h1>
  6. <h3 align="center">The Analytics Engine for <a href="https://malloydata.dev">Malloy</a></h3>
  7. <p align="center">A post modern data stack — built for the AI era.<br>
  8. One data model, served over MCP and REST to AI agents, applications, and BI tools.</p>
  9. <p align="center">Created and maintained by <a href="https://www.credibledata.com">Credible</a>, the company behind the AI Analytics Engine.</p>
  10. <p align="center"><sub><strong>AI agents:</strong> read <a href="AGENTS.md">AGENTS.md</a> first (raw: <code>https://raw.githubusercontent.com/malloydata/publisher/main/AGENTS.md</code>).<br>
  11. It covers starting the server, connecting over MCP, the bundled skills, and the package format. Fetch the raw file, not a summary of this page.<br>
  12. To learn the skills with nothing installed, read <code>https://unpkg.com/@malloy-publisher/skills@latest/skills/malloy-getting-started/SKILL.md</code>. With a shell, <code>npx -y @malloy-publisher/skills@latest install</code> copies them all into this project.</sub></p>
  13. <p align="center">
  14. <a href="https://github.com/malloydata/publisher/actions/workflows/build.yml"><img src="https://github.com/malloydata/publisher/actions/workflows/build.yml/badge.svg" alt="build"></a>
  15. <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  16. <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node.js >=20"></a>
  17. <a href="https://www.npmjs.com/package/@malloy-publisher/server"><img src="https://img.shields.io/npm/v/@malloy-publisher/server" alt="npm"></a>
  18. <a href="https://www.npmjs.com/package/@malloy-publisher/server"><img src="https://img.shields.io/npm/dm/@malloy-publisher/server" alt="npm downloads"></a>
  19. <a href="https://hub.docker.com/r/ms2data/malloy-publisher"><img src="https://img.shields.io/docker/pulls/ms2data/malloy-publisher" alt="Docker pulls"></a>
  20. <a href="https://github.com/malloydata/publisher/stargazers"><img src="https://img.shields.io/github/stars/malloydata/publisher?style=social" alt="GitHub Stars"></a>
  21. </p>
  22. <p align="center">
  23. <a href="https://github.com/user-attachments/assets/376a809d-8016-41a7-9464-a5634ea0589d"><img src="docs/malloy-publisher-demo.gif" alt="Malloy Publisher serving the bundled storefront dashboard" width="800"></a>
  24. </p>
  25. <p align="center"><sub>A 60-second walkthrough — model in your IDE with the Malloy skills, serve with Publisher, build a data app, materialize on a schedule, and analyze. <a href="https://github.com/user-attachments/assets/376a809d-8016-41a7-9464-a5634ea0589d">Watch the video</a> for playback controls.</sub></p>
  26. Modeling, a query engine, materialization, access control, and an API — the pieces you used to assemble
  27. from five projects — ship as one server, built assuming the first builder or consumer is an
  28. agent.
  29. Write down what your data means, in [Malloy](https://malloydata.dev): the sources, the joins, the
  30. measures, who may see what. The open-source Malloy [skills](skills/) ship alongside, so an agent can do
  31. the writing — build the model, then the reports and data apps on top of it.
  32. Publisher serves that model to every surface — over MCP to Claude, Cursor, Codex, or an agent you
  33. build; over REST to applications and BI tools. Agents compose queries against the model instead of
  34. writing SQL from scratch, so there is no wrong join, no invented column, no fan-out that double-counts
  35. but looks plausible — and the same question returns the same numbers tomorrow.
  36. - **Model** — an agent builds the model with the bundled open-source [skills](skills/), from a
  37. warehouse or a file, and validates each edit without a restart.
  38. - **Analyze** — Claude, Cursor, Codex, or an agent you build asks over MCP; unattended agents and
  39. applications use REST. Queries are Malloy, legible enough to review at a glance, and run against
  40. the model, never your raw tables.
  41. - **Surface** — reports declared in Malloy, read top to bottom or laid out as a grid and built by
  42. dragging tiles if you like, and no-build HTML data apps, all shipped inside the package, plus the
  43. Console for browsing it all.
  44. - **Govern** — givens, `#(authorize)` and `#(access_filter)` decide who may query and who sees what; discovery curation
  45. decides what is even visible. Publisher is a microservice: run it locally with your own
  46. permissions, or inside your cloud behind the gateway that authenticates your users and sets those
  47. givens. The controls rely on that gateway (see [operating model](docs/security-posture.md#operating-model-a-microservice-behind-your-gateway)).
  48. - **Optimize** — one `#@ persist` annotation materializes an expensive source into a table and
  49. `#@ preaggregate` rolls it up, rebuilt on demand or on a schedule.
  50. - **Run anywhere** — DuckDB built in for CSV, Parquet, JSON, and Excel; BigQuery, Snowflake, Postgres,
  51. Databricks, MotherDuck, and more by connection; `npx`, Docker, or Compose, in minutes.
  52. ## Requirements
  53. Node.js 20 or newer (the server refuses to start on anything older and says so). Building from a clone
  54. also needs [Bun](https://bun.sh/) 1.4.4+. The Docker image carries its own runtime and needs neither.
  55. ## Quick start
  56. ### Run the examples
  57. ```bash
  58. npx @malloy-publisher/server@latest --port 4000
  59. ```
  60. Open **http://localhost:4000**. Three example packages are bundled — [`storefront`](examples/storefront)
  61. (a complete ecommerce model), [`governed-analytics`](examples/governed-analytics) (access control), and
  62. [`html-data-app`](examples/html-data-app) (a no-build dashboard) — all DuckDB-backed, no credentials
  63. required. The first run fetches them from GitHub.
  64. ## Start from your own data
  65. ### Create a package
  66. ```bash
  67. mkdir my-data && cd my-data
  68. npm create @malloy-publisher/malloy-package@latest sales
  69. npm start
  70. ```
  71. This writes a package to `./sales` — plus, in the current directory, a small workspace: start and
  72. reset scripts, an MCP config, agent instructions, and the Malloy skills as files your agent can read.
  73. `npm start` serves the package in watch mode, so edits take effect as you save. Keep the `@latest`:
  74. without it npm may reuse a cached, older version. The finer points of `npm create` — caching, workspace
  75. layout, the bare `npx` form — are in [docs/scaffolding.md](docs/scaffolding.md).
  76. Agents: [AGENTS.md](AGENTS.md) sections 1 and 2 have the same steps plus the pitfalls around `@latest`,
  77. the `--` before `--data`, and reconnecting the MCP client after the server starts.
  78. ### Bring local data files
  79. ```bash
  80. npm create @malloy-publisher/malloy-package@latest sales -- --data ./orders.csv
  81. ```
  82. CSV, Parquet, JSON, newline-delimited JSON, or Excel `.xlsx` — DuckDB reads all of them in place. The
  83. `--` is required, and the path is relative to where you run the command. A seeded package starts
  84. small: a row count and an overview, which is the moment to point an agent at it.
  85. ### Connect a database
  86. A package is just Malloy, so it is not limited to local files. Add a
  87. [connection](docs/connections.md) — BigQuery, Snowflake, Postgres, Databricks, MotherDuck, and more —
  88. and point the model at it; the same workspace serves a warehouse. Have the warehouse but no model yet?
  89. Ask the agent what is in it: `search_database_schema` ranks a connection's tables against a
  90. plain-English description and hands back the `source:` line for each. Ranking needs no API key; the
  91. optional embedding-backed mode is in
  92. [docs/configuration.md](docs/configuration.md#semantic-ranking-for-search_database_schema).
  93. ## Point your agent at it
  94. ### Connect Claude Code
  95. Keep the server from [Quick start](#quick-start) running — or `npm start` from
  96. [Create a package](#create-a-package). On startup it wrote a `.mcp.json` into the directory you ran it
  97. in, pointing at the MCP port it bound. Open a second terminal, **in that same directory**, and start
  98. the agent:
  99. ```bash
  100. claude
  101. ```
  102. Say yes when the agent asks to trust the folder, use the server it found, and approve the first tool
  103. call — the trust prompt is asked once per directory, and only interactively, so a headless run can't
  104. clear it. Then ask, in plain English:
  105. > _"Use Malloy to explore the storefront sales data and chart revenue by category."_
  106. The agent discovers what exists (`get_context`), grounds itself in real source, view, and field
  107. names, runs the query (`execute_query`), and answers from your model — no schema spelunking, no
  108. hallucinated columns.
  109. If the agent reports no Malloy tools, register the server for yourself instead of relying on that
  110. file:
  111. ```bash
  112. claude mcp add --transport http malloy http://127.0.0.1:4040/mcp -s user
  113. ```
  114. The server skips writing the file in some directories (a git working tree, your home directory, one
  115. that already has a `.mcp.json`) and says so in its startup log. When it is written, why it can go
  116. stale, and how to turn it off:
  117. [docs/configuration.md](docs/configuration.md#the-mcpjson-the-server-writes).
  118. ### Other clients, and unattended agents
  119. Cursor, VS Code, Codex, and Claude Desktop take the same endpoint — `http://localhost:4040/mcp`,
  120. or whatever `--mcp_port` / `MCP_PORT` you set — through their own config; see
  121. [docs/ai-agents.md](docs/ai-agents.md). An agent working unattended that started the server itself uses
  122. the same loop over REST:
  123. ```bash
  124. curl -s -X POST \
  125. http://localhost:4000/api/v0/environments/examples/packages/storefront/models/storefront.malloy/query \
  126. -H 'content-type: application/json' \
  127. -d '{"query":"run: order_items -> by_category","compactJson":true}' | jq -r .result
  128. ```
  129. The running server serves its full OpenAPI spec at `http://localhost:4000/api-doc.yaml`.
  130. > **Operating model: a microservice behind your gateway.** Publisher runs either locally with your
  131. > own permissions, or inside your existing cloud behind the gateway or application that
  132. > authenticates your users. The server, MCP and REST alike, is stateless and unauthenticated, and it
  133. > can read any data your models connect to. Its access controls (`#(authorize)`, `#(access_filter)`,
  134. > `#(secure)` givens, `#(carries)`, the access record) are evaluated against what each request
  135. > carries. They enforce your policy only when that gateway authenticates the user, sets the givens
  136. > from the verified identity, and is the only way to reach Publisher. Bind it to loopback
  137. > (`--host 127.0.0.1`) for local use. See
  138. > [docs/security-posture.md](docs/security-posture.md#operating-model-a-microservice-behind-your-gateway)
  139. > for exactly what the gateway has to do.
  140. ## What you can do
  141. ### Model
  142. - **Build the model with an agent.** The bundled open-source [skills](skills/) carry the whole loop —
  143. discover what a database holds, define sources and measures, model as you go, review, document,
  144. publish. A LookML review skill covers coming from Looker.
  145. - **Start from a warehouse.** `search_database_schema` ranks a connection's tables against a
  146. plain-English description and returns the `source:` line for each.
  147. - **Validate without a restart.** `compile_model` checks an edit without running it;
  148. `reload_package` recompiles a package from disk. Watch mode does the same for a human editing
  149. in an IDE.
  150. ### Analyze
  151. - **Ask in plain English.** An agent grounds itself with `get_context`, runs
  152. `execute_query`, and answers from the model, never from raw tables. Analysis skills teach it the
  153. pitfalls and how to write up a finding — [docs/ai-agents.md](docs/ai-agents.md).
  154. - **Write it up as a report.** A report is a `.malloy` file with an `## artifact` tag, anywhere in a
  155. package; it mixes prose and queries and runs on the same governed endpoints. Pick a layout:
  156. `linear` for a story read top to bottom, `grid` for a view scanned at a glance —
  157. [docs/choosing-a-surface.md](docs/choosing-a-surface.md).
  158. - **Explore, no code.** Build and drill into queries visually with [Malloy Explorer](docs/explorer.md);
  159. every action generates Malloy, so metrics stay correct across joins. Or, on a server started
  160. with `PUBLISHER_MODEL_PAGE=viewer`, **browse a model** instead: open a `.malloy` file in the
  161. [Console](docs/console.md) to read each source it exposes, field by field with its Malloy, and run
  162. its views and named queries.
  163. ### Surface
  164. - **Reports declared in Malloy.** A tagged `.malloy` file _is_ the report: filterable, clickable,
  165. laid out as a grid or top to bottom, no code and no build step. Build it by dragging tiles around
  166. in the Console if you want the classic dashboard feel, or write the tags by hand — same file either
  167. way, and it reviews like any other source file — [docs/reports.md](docs/reports.md).
  168. - **No-build HTML data apps.** Ship HTML, CSS, and JavaScript inside a package and Publisher hosts it
  169. against the model — [docs/html-data-apps.md](docs/html-data-apps.md).
  170. - **The Publisher Console.** Browse packages, models, and every artifact in the built-in web UI, with
  171. your own [colors, fonts, and dark mode](docs/theming.md) — [docs/console.md](docs/console.md).
  172. - **Your own applications.** The REST API serves any language, and the running server publishes its
  173. OpenAPI spec. From Python, the standard library is enough: [AGENTS.md section 7](AGENTS.md#7-working-unattended-the-rest-api)
  174. has a copyable example. A generated client lives in [`packages/python-client`](packages/python-client),
  175. but it is not published to PyPI.
  176. ### Govern
  177. - **Decide who sees what.** [Givens](docs/givens.md) declare runtime parameters and drive filter
  178. widgets; [row-level access](docs/row-level-access.md) and [`#(access_filter)`](docs/authorize.md) gate
  179. which rows a caller gets and whether they may query a source at all.
  180. - **Decide what is visible.** Curate what is [discoverable and queryable](docs/discovery-and-access.md)
  181. separately, so an agent sees only the sources you meant it to.
  182. - **Know the boundary.** [docs/security-posture.md](docs/security-posture.md) lists what Publisher
  183. defends against and what it leaves to the gateway in front of it.
  184. ### Optimize
  185. - **Materialize.** One `#@ persist` annotation turns an expensive source into a table, rebuilt on
  186. demand, from the `malloy-pub` CLI, or on a cron with the opt-in scheduler —
  187. [docs/materialization.md](docs/materialization.md).
  188. - **Pre-aggregate.** `#@ preaggregate` rolls a measure up to a coarse grain so covered queries read a
  189. small table instead of the fact table — [docs/preaggregation.md](docs/preaggregation.md).
  190. - **Store it where you like.** Persist into a [DuckLake](docs/ducklake.md) storage tier, attach a
  191. DuckLake catalog read-only, and run offline or air-gapped —
  192. [docs/persist-storage-tutorial.md](docs/persist-storage-tutorial.md).
  193. - **Attribute every query.** [Query metadata](docs/query-metadata.md) tags each statement with a team,
  194. a workload, a request id, so the warehouse's own reporting can say who asked.
  195. ### Run anywhere
  196. - **Any data.** DuckDB is built in for CSV, Parquet, JSON, and Excel; connect BigQuery, Snowflake,
  197. Postgres, MySQL, SQL Server, Trino, Databricks, MotherDuck, and DuckLake — [docs/connections.md](docs/connections.md).
  198. - **Any host.** `npx`, Docker, or Docker Compose, in minutes — [docs/deployment.md](docs/deployment.md).
  199. - **Alongside dbt.** Where Malloy and dbt fit together, and the plan to close the gaps —
  200. [docs/dbt-roadmap.md](docs/dbt-roadmap.md).
  201. ## Examples
  202. The fastest way to see all of the above is the [`examples/`](examples/) directory. Three are packages
  203. Publisher serves out of the box, and a fourth shows the SDK:
  204. - **[storefront](examples/storefront)** — the flagship ecommerce model: sources, joins, reports in
  205. both layouts, and givens-driven filters. It is the package Quick start serves, and the one the SDK
  206. example reads from.
  207. - **[governed-analytics](examples/governed-analytics)** — the whole governance story in one small
  208. package: givens, row-level access, and `#(access_filter)` source gates.
  209. - **[html-data-app](examples/html-data-app)** — a no-build SaaS subscriptions dashboard served from
  210. a package's `public/` directory, driven by `Publisher.query()`.
  211. - **[data-app](examples/data-app)** — a standalone Vite + React app on
  212. [`@malloy-publisher/sdk`](packages/sdk), embedding live results in your own UI. Not a served
  213. package.
  214. ## Documentation
  215. The [`docs/`](docs/) folder is the reference hub; start at its [index](docs/README.md). Beyond the
  216. guides linked above: [architecture](docs/architecture.md) for how the pieces fit together,
  217. [api-overview](docs/api-overview.md) for the REST and MCP surface, [packages](docs/packages.md) for
  218. the package format (`publisher.json`, models, data), and the
  219. [Docker runtime deep-dive](packages/server/README.docker.md) for image layout, environment, and
  220. tuning. The complete user guide also lives at
  221. **[docs.malloydata.dev](https://docs.malloydata.dev/documentation/user_guides/publishing/publishing)**.
  222. ## Publisher and Credible
  223. Publisher is created and maintained by [Credible](https://www.credibledata.com), the company behind
  224. the **AI Analytics Engine**. The two fit together like this:
  225. - **Publisher is the open-source analytics engine.** It serves Malloy models over REST and MCP, and everything
  226. an agent needs from the language and the server — the modeling and analysis skills, the MCP tools —
  227. ships here in the open. Run it on a laptop, in Docker, or wherever you like.
  228. - **Credible is the hosted, governed engine built around it.** You write down what your data means
  229. once, in Malloy; the engine owns the how — it materializes and indexes the model in storage it
  230. brings along, enforces access at one gateway on every query, compresses each model into a concept
  231. index so an agent gets just the slice a question needs, and serves every surface — agents over MCP,
  232. dashboards and workspaces, the data apps and APIs in your product — from one model.
  233. Run Publisher yourself, or let Credible run it: the model is the same Malloy either way, and moving
  234. between them is a publish, not a rewrite. Where the open-source engine ends and the hosted one begins:
  235. [credibledata.com/malloy](https://www.credibledata.com/malloy) ·
  236. [Inside the AI Analytics Engine](https://www.credibledata.com/blog/posts/inside-the-ai-analytics-engine).
  237. ## Contributing
  238. Build and hack on Publisher from a clone with [docs/development.md](docs/development.md); contribution
  239. process and sign-off are in [CONTRIBUTING.md](CONTRIBUTING.md).
  240. ## Community
  241. - Join the [Malloy Slack](https://join.slack.com/t/malloy-community/shared_invite/zt-1kgfwgi5g-CrsdaRqs81QY67QW0~t_uw)
  242. - Report issues on [GitHub](https://github.com/malloydata/publisher/issues)
  243. - Report a security vulnerability privately — see [SECURITY.md](SECURITY.md) for the reporting form
  244. and what's in scope

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.