Publisher is the open-source semantic model server for Malloy. It serves Malloy models through REST and MCP APIs, enabling consistent data access for applications, tools, and AI agents.

The repo ships a .tool-versions file compatible with mise and asdf, so mise install (or asdf install) provisions all four versions at once.

npx @malloy-publisher/server --port 4000

Open http://localhost:4000 to explore the sample models. Three DuckDB-backed samples (ecommerce, imdb, faa) are cloned from GitHub on first launch — expect a 30–60s wait before operationalState reports serving. No credentials required.

Heads up — npx + DuckDB native binding. On some Node 24 setups, npx does not install DuckDB's native binding (node_modules/duckdb/lib/binding/duckdb.node), so the server exits at startup with Cannot find module ...duckdb.node. This is an upstream duckdb install-script issue tracked separately. Workaround until that's fixed: clone this repo and run make start-init (or bun run build && bun run start) from the repo root — the workspace's install-duckdb-bindings script handles the binding install during bun run build.

Pass --config <path> to point the server at a specific publisher.config.json, or place a publisher.config.json in the directory you launch from. Both forms override the bundled default.

# Existing repo of Malloy samples or your own packages
git clone https://github.com/credibledata/malloy-samples.git
npx @malloy-publisher/server --port 4000 --config malloy-samples/publisher.config.json

# Or cd in and rely on the implicit lookup
cd malloy-samples && npx @malloy-publisher/server --port 4000

To enable the BigQuery samples (bigquery-hackernews, etc.), copy packages/server/publisher.config.example.bigquery.json over your publisher.config.json and set GOOGLE_APPLICATION_CREDENTIALS.

curl -s http://localhost:4000/api/v0/status | jq .operationalState   # → "serving"
curl -s http://localhost:4000/api/v0/environments | jq '.[].name'    # → list of environments

operationalState reports the current server lifecycle:

• serving — ready to handle requests.
• initializing — loading packages and connections from publisher.config.json. Normal on boot, and especially noticeable on the first run when sample packages need to be cloned from GitHub. Wait for serving.
• draining — graceful shutdown in progress: the server is waiting for in-flight requests to finish before closing. Controlled by SHUTDOWN_DRAIN_DURATION_SECONDS and SHUTDOWN_GRACEFUL_CLOSE_TIMEOUT_SECONDS (see Configuration).

Two ways to run the Publisher in Docker: build the image from source, or pull the pre-built image from Docker Hub. Either way, the container's WORKDIR is /publisher (mount your publisher.config.json there), REST is on :4000, and MCP is on :4040.

docker build -t malloy-publisher .
docker run -d \
  -p 4000:4000 -p 4040:4040 \
  -v $(pwd)/publisher.config.json:/publisher/publisher.config.json:ro \
  malloy-publisher

If you don't have a config yet, copy packages/server/publisher.config.example.duckdb.json (DuckDB-only samples, no credentials needed) as a starting point.

The official pre-built image is published to Docker Hub at ms2data/malloy-publisher.

docker pull ms2data/malloy-publisher
docker run -d \
  -p 4000:4000 -p 4040:4040 \
  -v $(pwd)/publisher.config.json:/publisher/publisher.config.json:ro \
  ms2data/malloy-publisher

Tags:

• :latest — most recent stable release.
• :X.Y.Z — pinned to a specific release; recommended for production.
• :next — pre-release builds; not recommended for production.

*-dev tags (e.g. :0.0.198-dev) are frozen — no new ones are being published, and :next is the current pre-release channel. Existing *-dev tags still resolve in the registry; don't use them for new deployments.

A ready-to-use Compose file lives at docker-compose.example.yml — it runs the pre-built image with both ports mapped, a healthcheck against /api/v0/status, and a named volume for publisher_data/ so first-boot package clones survive restarts. To use it:

1. Copy it into your project: cp docker-compose.example.yml docker-compose.yml.
2. Place a publisher.config.json next to it (or change the volume mount). No config of your own yet? Copy packages/server/publisher.config.example.duckdb.json — DuckDB-only samples, no credentials needed.
3. docker compose up -d

For env-var configuration, persistent publisher_data/ volumes, and advanced options, see packages/server/README.docker.md.

Full documentation is available at docs.malloydata.dev/documentation/user_guides/publishing:

• Getting Started - Setup, deployment options, configuration
• Database Connections - BigQuery, Snowflake, Postgres, DuckDB, and more
• Explorer - No-code visual query builder
• REST API - Build custom applications
• Publisher SDK - Embed analytics in React apps
• MCP for AI Agents - Connect Claude and other AI assistants

The core compiler and query execution engine. Malloy compiles .malloy files into SQL, executes queries against databases, and returns structured Result objects. Malloy is a pure JavaScript/TypeScript library with no UI or serving capabilities—it's the foundation everything else builds on.

Repository: github.com/malloydata/malloy

A visualization library that transforms Malloy Result objects into interactive tables, charts, and dashboards.

When Malloy executes a query, the result includes both data and rendering hints—tags like # bar_chart or # line_chart that indicate how the data should be displayed. Malloy Render interprets these tags and produces the appropriate visualization.

Built with: SolidJS and Vega/Vega-Lite. Available as both a JavaScript API (MalloyRenderer) and a <malloy-render> web component.

Repository: github.com/malloydata/malloy/packages/malloy-render

An open-source semantic model server for Malloy. Publisher makes Malloy models accessible over the network and provides a professional UI for data exploration.

• Server: REST API for listing content, managing database connections, compiling models, and executing queries. Also provides an MCP API for AI agent integration. Supports source filters for model-driven, server-side query filtering.
• App: Web interface for browsing Malloy content, exploring models with a no-code query builder, and viewing results.

A React component library for building custom data applications powered by Publisher:

• API communication — Talks to the Publisher Server via REST
• Query execution — Submits queries and retrieves results
• Result visualization — Integrates Malloy Render to display results
• UI components — Pre-built pages for browsing environments, packages, models, and notebooks
• Source filters — Automatically renders filter widgets for models with #(filter) annotations

The Publisher App is built entirely with the SDK, but the SDK is a standalone NPM package for building your own applications.

Publisher consists of four packages:

This project uses bun as the JavaScript runtime. Sample packages are fetched at runtime per publisher.config.json — no submodule checkout needed.

The bundled publisher.config.json ships three samples (ecommerce, imdb, faa) that run via per-package DuckDB sandboxes — no GCP credentials needed. To enable the BigQuery-required bigquery-hackernews sample, copy publisher.config.example.bigquery.json over publisher.config.json (or point --server_root at a directory containing it) and set GOOGLE_APPLICATION_CREDENTIALS.

A top-level Makefile wraps the common workflows so you don't have to remember script names or cd into individual packages. Run make help for the full list. The most useful targets:

One command builds the SDK, app, and server bundle in order:

make install
make build
make start                # Run the built server (REST on :4000, MCP on :4040)

Or run the underlying bun scripts directly: bun install && bun run build:server-deploy && bun run start.

Express and Vite run as separate processes. Express on :4000 proxies non-API traffic to Vite on :5173 when NODE_ENV=development, so visit http://localhost:4000 for the full app — :5173 won't have API access.

One terminal (recommended):

make dev

This runs both servers with combined, color-prefixed logs ([server] / [react]). Ctrl+C stops both cleanly.

Two terminals (if you prefer split logs):

make dev-server          # Express (REST :4000 + MCP :4040, watch mode)

make dev-react           # Vite dev server (:5173, proxied through :4000)

Open http://localhost:4000.

make test                # unit + integration server tests
make lint && make format # eslint + prettier
make typecheck           # tsc --noEmit across sdk/app/server

make typecheck (and the underlying bun run typecheck) depends on the SDK's emitted .d.ts files, which in turn depend on the OpenAPI codegen. On a fresh clone, build first — either with make build (full SDK + app + server bundle), or with the targeted minimum:

bun install
bun run generate-api-types
bun run build:sdk
bun run typecheck

After that, bun run typecheck works on its own as long as the SDK build artifacts stay current:

• After editing api-doc.yaml → re-run bun run generate-api-types && bun run build:sdk.
• After editing SDK source → re-run bun run build:sdk.

Publisher reads its runtime configuration from publisher.config.json (see Development for the BigQuery opt-in) and a handful of environment variables. Every CLI flag below has an env-var equivalent; pass either.

PostgreSQL and other database-specific connections may also honor their respective driver env vars (e.g. PGSSLMODE).

• Join the Malloy Slack
• Report issues on GitHub