Skip to content

The canvas

The canvas is a visual editor for the model: entities as boxes, relationships as lines between their columns. It reads and writes the same YAML files as the CLI, through the same edit functions, so a change made on the canvas is exactly the change murakumo add, rename or remove would make, and it shows up in git diff the same way.

pip install "murakumo[canvas]"
murakumo canvas                 # in a project folder; opens http://127.0.0.1:8765
murakumo canvas path/to/project --port 9000 --no-open

Finding your way around

  • The top bar: the project, Find a table or column (⌘K), how tables show (all columns, keys only, names only, descriptions: ⌘1 to ⌘4, and when tables collapse), undo and redo, whether the generated code is up to date, and the problems.
  • The tool rail, on the left: add a table (T), a relationship (R) or a note (N), arrange the tables, export the canvas as an image; then the panels (Explorer, Sources, Stack, Schedules, Bus matrix, Team, CI, Runs, Health, Assistant, Guide, Activity, Changes, Problems), settings, the pipeline docs, light or dark, and help. Hover an icon for its name.
  • The Explorer lists every table by domain, layer, colour label and source, each opening to its tables and their columns; its search box finds tables and columns. Click a table to go to it; click a domain to show only its tables; the eye beside a layer hides it.
  • Diagram tabs, above the canvas: All tables, and any diagrams saved for a part of the model.
  • The inspector, on the right, opens when you click a table or a line.
  • Help (the ? at the bottom of the rail): a short tour, which also opens the first time, the keyboard shortcuts (press ?), and the notation.

What you can do

  • See the model. Raw tables are grouped by source, then staging, intermediate, marts and semantic, left to right. Inside a group, a table sits to the left of the tables it points at, so lineitem → orders → customer → nation → region reads left to right. Each table's header is its layer's colour (or its colour label's), with key icons for primary and foreign keys and ƒ for calculated columns. Drag boxes to arrange them; positions are saved to model/layout.yaml, keyed by entity id, so a rename keeps its place. Commit the file to share the layout. Shift+drag on the background selects several tables (⌘/Ctrl+click adds one), and dragging any of them moves them all.
  • Undo anything. Every change is saved to the model files as you make it, and ⌘Z (or ↶ in the top bar) takes it back; ⇧⌘Z redoes it. The button says what it would undo: "table dim_zone removed". A removed table comes back with its columns, mappings, relationships and place. Undo goes back up to 100 changes made in this canvas; if the files were changed some other way since (your editor, murakumo sync), it stops rather than overwrite that work, and git still has every version. Moving tables is not undone this way; Arrange has its own Put them back.
  • Show tables your way. All columns, keys only, names only, or each table's description (⌘1 to ⌘4). Each table's ▾ collapses it to its name and "+12 columns"; lines then meet its header. The slider button beside the view modes collapses every table with more than a number of columns, or all of them. Collapsed tables are saved in model/layout.yaml, so the team sees the same.
  • Organise a large model.
  • Colour labels: name a colour (Finance, PII, Deprecated) in the Explorer and give it to tables in the inspector, or to several at once; their headers take its colour, and clicking a label shows only its tables.
  • Notes: N adds a sticky note; double-click to write, drag to move, pick its colour.
  • Diagrams: select tables, then + Diagram above the canvas, to save a view of them as a tab. Double-click a tab to rename it. The inspector's Diagrams row puts a table in or out of each one. A note belongs to the diagram it was written on.
  • Arrange: lays the tables out left to right or top to bottom, the dimensions before the facts that point at them, so lines run one way.
  • Export: the tables shown, as a PNG or SVG image.
  • Several tables at once: with two or more selected, a bar sets their domain, layer or colour label, arranges them, or removes them, each as one change that one undo takes back.

Labels, notes and diagrams live in model/layout.yaml beside the positions; the model files do not change. - Read the relationships. Lines use crow's-foot notation: at each end, ‖ exactly one, ○| zero or one, a crow's foot for many (with ○ when it may be none); a dashed line is optional. Hover over a line to see its role and cardinality (pickup · N:1) and the joined columns highlighted in both tables; click it to keep them highlighted and edit it. Help → Notation and tips explains the symbols. When two tables are dragged one above the other, the line goes round them rather than behind them. - Edit an entity. Click it to open the inspector: rename it, change its layer, kind, source, domain and description, and add, rename, retype or remove columns and set primary keys and NOT NULL. + From a source table brings in columns of other tables: the tables it most likely reads from come first (those its mappings and relationships name, the raw table a staging table is named after, then the layer before), and you tick the columns you want, or a whole table. They keep their names, types and descriptions and, outside the raw layer, are mapped to where they came from, all in one change. A new table with no columns offers this straight away. Tables with more than six columns get a Find a column box, which filters the columns and mappings. Drag the inspector's left edge to make it wider. + on the rail (or T) adds a new table. - Reorder columns. Drag a column by its ⋮⋮ handle in the inspector, or focus the handle and press Alt+↑ or Alt+↓. Generated tables and dbt models list columns in the new order. Tables that already exist keep theirs, because no warehouse reorders columns in place; the Changes panel says so, and nothing needs a migration. - Add a relationship. Press R (or the line icon on the rail) and pick both tables and columns; or, in the inspector's Relationships section, click + Relationship and pick the column, the table it points to, its column and the cardinality. Or hover over an entity to show the handles beside each column, then drag from the foreign key column to the column it points at, on another entity. A dragged relationship is many-to-one; click the line to change the cardinality, make it optional, or give it a role (needed when two relationships join the same tables, like pickup and drop-off zones). - Map columns. For entities in staging, intermediate, marts and semantic, the inspector lists every column with where it comes from: entity.column sources (suggested as you type, or ticked in a list with ☰) and an optional SQL expression (ƒx), in DuckDB SQL and translated for your warehouse. Columns without a mapping are highlighted. - Calculate columns. ƒx opens the expression editor, and + Calculated in the Columns section adds a new column with its expression in one step. The editor highlights the SQL, suggests tables, their columns and functions as you type (type a table name and a dot; Tab or Enter accepts; Ctrl+Space asks), and checks the expression as you go: which columns it reads, whether they all exist, the type it returns (offered as the new column's type) and how it reads in your warehouse's SQL. Preview runs it on a dozen made-up rows in DuckDB on your computer, showing the inputs and the result; nothing touches the warehouse. Saving sets the mapping's sources to the columns the expression reads. An expression reads the tables an entity is built from, not the entity's own columns. - Follow lineage. ⇄ beside a column in the inspector (or Lineage, for the whole table) shows where the column comes from and what uses it: those columns are highlighted, linked by moving dashed lines, and everything else fades. Hover a link to see the expression that makes it, drawn over the tables and wrapped when it is long. The bar at the top lists the columns it comes from and the columns that use it; click one to follow it. murakumo lineage shows the same in a terminal. - Group by domain. The Explorer's Domains lists each domain and its tables; click one to show only its tables. Its ⚙ manages the domains in murakumo.yaml: add one, rename one (its tables follow), set its owner, or remove one no table uses. The eye beside it shades an area, with the domain's name and owner, behind each domain's tables. An entity's domain is picked from a list in the inspector. Each domain becomes a dbt group; see generating. - Add and import sources. Sources lists the sources, with where each is read from and how many tables it has. + Add source declares a new one in murakumo.yaml: a database by the name of an environment variable that holds its connection string (the string itself never goes into a file), Snowflake by its database name (the rest comes from the SNOWFLAKE_* variables), or a data dictionary, data file or OpenAPI spec by its path or URL. Browse tables connects to a database source and lists its schemas, tables and columns, read from the catalogue, never the rows; tick the tables you want (tables already in the model start ticked), Preview import shows what would be added, changed or removed, and Import into the model saves it. Other sources have Re-import, with the same preview. Connection errors are shown with any password removed. - Say how a source's data is fetched. Connect… on a source opens its connection: - Kinds: a REST API, SFTP, a database, a folder or S3 prefix, protobuf files, or Kafka (its brokers, security, and a topic per raw table). - A REST API is a request builder. Set the auth and paging once, add a request for each raw table, and Send it. You see the status, the time it took and the records, as a table or the raw response. Make … from these records creates the raw table from them. - Secrets stay out of the canvas. Each auth field names the environment variable that holds the secret, never the secret itself. - Save connection records your reason in the decisions log. Test reaches the source without landing anything, and Fetch now runs murakumo ingest for it. - See stack.md. - See the generated code. The inspector's Code tab shows the dbt SQL generated for the entity and its table's DDL, updated as you edit. - Write the code. The top bar says how many files in generated/ are out of date with the model. Click it for the Changes panel: every file that would change, each with its diff, and one button, Write N files to generated/, that writes them, as murakumo generate does. - Write migrations. When a change affects a table that keeps data (a landing table, an incremental model or a snapshot), the Changes panel explains that it needs a migration too, shows it with its SQL, and the button becomes Write migration #N and M files: it writes the migration to migrations/ first, then the code, so the two never get out of step. See migrations. The first migration, the baseline, has its own button. - Schedule refreshes. Schedules lists when each part of the project is refreshed, each time in words with its next run: add one with a preset or a cron time, choose what it refreshes (domain:, layer:, source: or a table, suggested as you type), set the time zone, and click a schedule's table count to highlight its tables. The inspector says which schedule refreshes the selected table. Each schedule becomes a pipeline for your orchestrator; see orchestration. - Read the docs. Docs opens the pipeline docs for the model as it is now: domains, schedules, sources, and every table's columns, lineage and tests, on one page. - Set up CI. CI shows whether the repository has a Murakumo workflow for GitHub Actions or GitLab, writes one (optionally with an approved production build), shows the difference when the file was changed by hand instead of overwriting it, and Run checks now runs the same four checks on your computer, each shown as it passes or fails. - Work as a team. Team shows your branch against the parent branch (collaboration.base_branch): how far behind and ahead it is, what is coming in, in model terms, and your uncommitted model changes. Get latest from main runs murakumo sync; Commit commits the project. See teamwork.md. - Be warned before breaking something. An edit that would break what reads the model (removing a column or table, narrowing a type, tightening nullability, changing a key) is previewed first: a confirmation lists what it reaches (columns built from it, tests, schedules) and the migration it needs, before anything is saved. - Fix problems. The top bar shows the problems murakumo validate and murakumo generate report, such as a column with no mapping (MK503). Click it for the list; click an item to go to its table and column, which is pointed out. Tables with problems carry a badge, the columns they are about are marked red or amber (hover for the message), and the inspector shows them.

Health and the assistant

  • Health shows what murakumo monitor finds (loads far from their usual size, late tables, rejected rows, failed runs; click a table to go to it), what murakumo cost estimates with its assumptions, the lineage for a catalog as OpenLineage events or plain JSON, and Bring in a dbt project: give its folder, see what it would add, then import.
  • Assistant is off until you turn it on. It then suggests descriptions, personal-data marks, mappings or new tables; you tick the ones to keep and apply them. See assistant.md.
  • Health also checks each load against its data contract, lets you download each table's contract (ODCS), and brings in a contract someone sent you.
  • The inspector sets a raw table's change feed (New rows → cdc, Operation, Latest by) and a mart's row access (Rows by, Roles).
  • The inspector's Quality rules lists every rule on the table and its columns, with what a failure does (Stop the run, Warn, Set rows aside on raw tables); change it there, or remove the rule. Add rule picks the column (or the whole table), the rule and its settings, and what a failure does. Data contract below sets its version, status and, on a raw table, whether a load that breaks it stops the build.
  • Query (the terminal icon) runs read-only SQL on any table at any stage: the source itself, what landed, raw, staging, quarantine, marts, snapshots, the audit tables, the Iceberg catalog, and files anywhere (Parquet, CSV, JSON, Excel, Iceberg, Delta; local, S3, GCS, Azure). Click a table to preview it; Ctrl+Enter runs what you typed; results download as CSV. The inspector's Query button opens it on the selected table. See operating.md.
  • Settings → Data quality writes the rules for Great Expectations and Soda too, turns on reconciliation and write-audit-publish, and says where contracts are enforced.

Running the project

Everything murakumo does in a terminal, the canvas does too. Long commands run as jobs: the canvas starts the same murakumo command in the project's folder, in the background, and shows its output as it comes in Activity (the pulse icon), with the command itself to copy. One job runs at a time; Stop stops it. The last twenty are kept with their output.

  • Stack (the layers icon) is murakumo stack, in three tabs:
  • Stack: each part of the platform (warehouse, extract, landing, load, transform, Python, orchestrator, CI, streaming, infrastructure as code), with what each choice means. It shows any choices that do not go together. Saving asks Why? and records the answer in the decisions log. Fetch now and Load what landed run murakumo ingest and murakumo load.
  • Deploy: the steps to stand the platform up in an environment, each with its SQL or commands and who runs it. Run Murakumo's steps runs the warehouse ones (murakumo stack deploy --apply).
  • Decisions: the log, newest first, and Record it for a decision of your own.
  • Guide (the book with a tick) is the replication guide: every step to rebuild the platform by hand, chapter by chapter, each with why, its SQL or commands (with a copy button) and what you should see. Tick the steps you have done; the ticks stay in this browser. Check it rebuilds the project runs murakumo guide --check.
  • Bus matrix (the grid) has three tabs, from the modelling patterns:
  • Bus matrix: a row per fact, a column per dimension, a tick where the fact uses it, which dimensions are conformed, and the problems (MK316, MK317). Click a name to go to its table.
  • Exposures: the dashboards, notebooks and apps that read the marts, with their owner, link, maturity and the tables they read. Save exposures writes model/exposures.yaml.
  • Metrics: each metric's table, expression, date, grain, the columns it breaks down by and the rows it counts. Save metrics writes model/metrics.yaml; the semantic layer is written from it.
  • Modelling patterns (in the inspector): a dimension's History (scd1 to scd6) and, for types 3 and 6, Tracked; its Unknown row (as the project, yes or no) and Conformed; a modelled table's Access (private, protected, public); and a table of kind accumulating's grain, Milestones and Time in.
  • Settings (the gear): Project sets the warehouse, orchestrator and modelling pattern (as murakumo config), the Python pipeline, plain-SQL output, the run log, the parent branch and personal schemas, unknown rows in dimensions, the replication guide, Open tables (the table format, catalog, layers and where they go), and Personal data: what PII, confidential and restricted columns show on Snowflake, and the roles that see them as they are. Each is saved to murakumo.yaml at once with its comments kept, and undoable. This machine is murakumo setup: what the project needs here (drivers, variables, key files, connections) and how to fix each, with Test the connections. Passwords and keys are never typed into the canvas: they stay in environment variables and key files.
  • Build… (in Activity) loads the raw tables and builds every model and test into the warehouse: from files you add (Add a file…; they go to data/, which git ignores), from what is already loaded, or from made-up rows; into dev or prod, one schedule or everything, a day for cumulative tables, and a schema prefix. Fetch what is new from the sources first fetches every connected source and loads what landed (build --ingest). Verify builds on a throwaway DuckDB and runs every test twice. Run as Python… runs the Polars or PySpark pipeline. Generate and Export as plain SQL write generated/ and export/.
  • Runs (the clock) reads the audit tables every run writes: by day, each run with its engine, schedule and counts, each load's rows taken in and rejected (hover for why), and the last run's failed tests (click one to go to its table). Schedules says when each schedule last ran here and how it ended, and Run now builds it.
  • Backfill: a cumulative table's inspector takes a first and last day and fills them in, one day after another.
  • Data dictionaries: + Add source with a CSV or Excel dictionary has Choose a file from this computer…, which copies it into data/ and fills in the path; then import as usual.
  • Environments and the git flow (in Team and Settings): Start new work creates a feature/, fix/, chore/ or hotfix/ branch from the latest dev; Promote shows what moving dev into stage (or stage into main) would bring and opens the pull request on GitHub or GitLab; Create missing dev, stage branches starts the flow. Settings → Project → Environments sets each environment's database and branch and where people's own schemas live, and Setup SQL… shows what an administrator runs once (murakumo env provision).
  • Loading and increments (in the inspector): a raw table's New rows says how loads take new rows (append, incremental by key, or full); a modelled table's Each run builds it in full, by load time (late rows included, with a look-back in hours), or by its watermark. Settings → Project's Keep raw columns as text converts them in staging instead, counting what does not convert. The Build dialog can load every new file in data/ that starts with a table's name.
  • Schedules here: the Schedules panel's Run them here runs every schedule on this computer at its times (murakumo scheduler), until Stop.
  • Test my change (in Team, or Activity): what a pull request's preview does, one step at a time: copy production into a prefix (pr_<branch>_), apply this branch's new migrations there, build and test there, and drop the copy. Each step shows its command and result, and what is under the prefix after it. On Snowflake the copy is a zero-copy clone; on DuckDB, the tables are copied.
  • Compare with (in Team): murakumo diff against any branch, tag or commit: each change, how risky, what it reaches, the migration it needs, and Copy the report for a pull request.

Renames follow references, as with murakumo rename: renaming lineitem updates the relationships, mappings and metrics that use it, and renames lineitem.yaml too; renaming a column updates keys, grain, watermark, tests, relationships, and mappings, including expressions such as l_extendedprice * (1 - l_discount). Ids never change.

Working alongside an editor

Every request reads the project from disk, and the canvas checks for changes every two seconds, so edits made in your editor, with the CLI, or by git pull appear on the canvas straight away; so does running murakumo generate or murakumo migrate in a terminal. If a file changed after the canvas last loaded it, the canvas refuses to save over it, shows the latest version and asks you to make the change again. If a file stops loading (a YAML syntax error, say), the canvas turns read-only until it is fixed, so nothing is ever saved over a file it could not read.

The API

murakumo canvas serves the canvas and a JSON API under /api; interactive documentation is at /api/docs. Every change returns the whole new state, validated.

Method Path Does
GET /api/state The model, layout, canvas settings, sources, domains, schedules, diagnostics (with the column each is about), what undo and redo would do, revision, and the choices for each field
GET /api/revision Just the revision, a fingerprint of the model files: cheap to poll
POST /api/entities Add an entity: {name, layer, kind, source, domain, description, position}
PATCH /api/entities/{id} Change or rename it: any of name, description, layer, kind, source, domain, owner, history, load, watermark, tags
DELETE /api/entities/{id} Remove it, its file and its relationships
POST /api/entities/{id}/columns Add a column: {name, type, primary_key, nullable, description, pii, classification}
PATCH /api/entities/{id}/columns/{column_id} Change or rename it
DELETE /api/entities/{id}/columns/{column_id} Remove it
POST /api/relationships Add one: {from, to, keys: [{from, to}], cardinality, name, optional, role}
PATCH /api/relationships/{id} Change it: name, cardinality, optional, role, description, keys
DELETE /api/relationships/{id} Remove it
PUT /api/entities/{id}/mappings/{column_id} Set a column's mapping: {sources: ["entity.column"], expression}; both empty removes it
PUT /api/entities/{id}/columns/order Put the columns in this order: {columns: [column_id, ...]}, every column once
POST /api/entities/{id}/calculated Add a column worked out by an expression: {name, expression, type} (type optional)
POST /api/expressions/check Check an expression: {expression, sources, entity} gives what it reads, problems, its type and its warehouse SQL
POST /api/expressions/preview Run it on made-up rows in DuckDB: the input columns, the result and a note
GET /api/lineage?entity=&column= Where a column (or every column of an entity) comes from and what uses it: nodes with their distance, links with their expressions, and the joins between them
POST /api/domains Add a domain to project.domains: {name, owner, description}
PATCH /api/domains/{name} Change its owner or description, or rename it with name (its entities follow)
DELETE /api/domains/{name} Remove a domain no entity uses
POST /api/sources Declare a source in murakumo.yaml: {name, kind, location}; kind is database (location: an environment variable's name), snowflake (a database name), csv, excel, file or openapi (a path or URL)
GET /api/sources/{name}/browse A database source's schemas, tables and columns, each table marked if it is in the model
POST /api/sources/{name}/import/preview What importing would change: {tables: ["schema.table"], prune}; tables: null imports the whole source
POST /api/sources/{name}/import Import it and save; returns the new state and the reports
POST /api/schedules Add a schedule: {name, cron, select, description}
PATCH /api/schedules/{name} Change its name, cron, select or description
DELETE /api/schedules/{name} Remove it
PUT /api/orchestration/timezone Set the time zone schedules run in: {timezone}
GET /api/pipeline-docs The pipeline docs page, as HTML
GET /api/ci?provider=&deploy= The CI file: missing, current or changed, with its content or difference, and the last local run
POST /api/ci Write it: {provider, deploy, force}; a file changed by hand needs force
POST, GET /api/ci/run Start the checks here in the background; follow them
GET /api/git?refresh= Branch, parent branch, ahead and behind, incoming and uncommitted model changes, your schema prefix
POST /api/git/sync?resume= Bring in the parent branch, as murakumo sync does
POST /api/git/abort Give up a sync with conflicts
POST /api/git/commit Commit the project: {message}
PUT /api/layout Save positions: {positions: {entity_id: {x, y}}}
POST /api/jobs Start a job: {kind, options}; kind is build, verify, run, backfill, migrate_apply, env_clone, env_drop, scheduler, ingest, load, deploy, export or generate, and each option is checked before the command is built
GET /api/jobs, /api/jobs/{id}?since= The jobs, newest first; one job and its output from line since on
POST /api/jobs/{id}/cancel Stop a job, and what it started
GET, PUT /api/stack The stack's parts, their choices, problems, each source's connection, the environments and the decisions log; PUT {values: {part: value}, why} changes parts (undoable)
PUT /api/sources/{name}/connection A source's connection: {connection, why}, or connection: null to stop fetching it
POST /api/sources/request Send one request: {connection, endpoint}; returns the status, time, record count, a sample and the response. Secrets come from the server's environment variables
POST /api/sources/{name}/test murakumo source test: what the connection can reach, without landing anything
POST /api/sources/table-from-records Make or update a raw table from records: {source, table, records, path}
GET /api/stack/deploy?env= The steps to deploy an environment, with their SQL or commands
GET, POST /api/decisions The decisions log; POST {what, why} adds one
GET /api/guide The replication guide's chapters and steps, as the model is now
GET /api/bus The bus matrix: dimensions, facts and the dimensions each uses, and conformed problems
PUT /api/exposures {exposures: [...]} replaces model/exposures.yaml (undoable)
GET, PUT /api/settings The project's settings and their choices; change any of warehouse, orchestrator, pattern, python_engine, plain_sql, run_log, raw_text, base_branch, personal_schemas, personal_database, environments: [{name, database, branch}]
POST /api/git/start Create the environments' missing branches from main (murakumo branch start)
POST /api/git/branch Start new work: {kind, name}; kind is feature, fix, chore or hotfix
GET /api/git/promotion?branch= What promoting a branch to the next would move, and the pull request's address
GET /api/env/provision The setup SQL for the environments
GET /api/setup?connect= What murakumo setup checks, each with how to fix it
GET, PUT, DELETE /api/uploads, /api/uploads/{name} Files in data/; add one as its raw bytes (application/octet-stream only), or remove one
GET /api/runs?environment=&prefix= The audit tables: days, runs, loads, the last run's failed tests, each schedule's last run
GET /api/env?environment=&prefix= Where an environment's builds go, and each schema's tables
GET /api/diff?ref= Model changes since a branch, tag or commit, what each reaches, and the report as Markdown
PUT /api/canvas Save what the canvas draws besides the model, in model/layout.yaml: any of collapse_over, collapsed: {entity_id: bool}, labels: [{name, colour, description}], colours: {entity_id: label}, notes: [{id, text, x, y, width, colour, diagram}], diagrams: [{id, name, entities}], and label (what undo calls it)
POST /api/undo, /api/redo Take back the last change, or make it again; refused (409) when the files changed some other way since
PATCH /api/entities The same change to several tables: {ids, changes}, one undo
POST /api/entities/remove Remove several tables: {ids}, one undo
POST /api/entities/{id}/columns/copy Bring in other tables' columns, mapped: {columns: ["entity.column"]}
GET /api/generated What generating would change: each file's status and entities, generate diagnostics, the next migration
GET /api/generated/file?path= One generated file and its diff against generated/
GET /api/entities/{id}/code The dbt SQL and DDL generated for one entity
POST /api/generate Write generated/
POST /api/migrations Write the next migration: {name} (optional)
GET /api/query/targets What the query console can query, at every stage, each with a preview query
POST /api/query Run one read-only query: {sql, engine, environment, limit, timeout}
GET /api/contracts?check= Each table's data contract (ODCS), and with check=true whether the latest loads kept to them
POST /api/import/odcs Bring in a data contract: {path, source, dry_run}

The generated endpoints take ?warehouse= to generate for another warehouse than the manifest's.

Send X-Murakumo-Preview: 1 with an edit to an entity, column or relationship to get what it would reach ({preview: {worst, impacts, files, migration}}) instead of making it.

Send the revision you last saw in an X-Murakumo-Revision header to have a change refused (409, with the current state) if the files changed since. A change the model rejects, such as a duplicate name or an unknown type, returns 400 with a message and changes nothing.

The server listens on 127.0.0.1 only, answers only requests addressed to localhost or 127.0.0.1, and accepts changes only as JSON, which a web page on another site cannot send to it without its consent.

Developing the canvas

The canvas lives in apps/canvas. Run the API and Vite side by side; Vite forwards /api to port 8765:

cd packages/python && uv run murakumo canvas ../../examples/commerce --no-open
cd apps/canvas && npm run dev        # http://localhost:5173

npm run build writes apps/canvas/dist. murakumo canvas serves the copy built into the Python package, or apps/canvas/dist when it runs from the repository; building the package (uv build) puts the built canvas inside it.