Installing Artifacts

mur install fetches an artifact from a configured source and writes it into a local store. How you reference the artifact determines what gets fetched and where authentication comes from.

Reference forms

Form	Example	Resolved against
Name and version	`murmur-tool-git@1.0.0`	The registry first, then the configured sources
Bare name	`murmur-tool-git`	The configured sources, latest release
GitHub release	`github:<owner>/<repo>@<tag>`	That release, directly
Local file	`./murmur-tool-git-1.0.0.mur.zip`	A path on disk. A reference counts as a path when it starts with `./`, `../` or `/`, or contains `/` and ends in `.mur.zip`

mur install murmur-tool-git@1.0.0

Which assets an install pulls

Reference	Assets installed
`<name>` or `<name>@<version>`	One — the matching asset from the first source that has it
`github:<owner>/<repo>@<tag>`	Every `.mur.zip` asset in that release

Use a name reference to take a single artifact out of a release that contains several; the github: form cannot target one asset. A name reference needs the repository configured as a source — see Multiple sources and fallthrough.

<name>@<version> searches the release tagged <version>, then v<version>, then the source's latest release, so a repository whose release tags are independent of artifact versions still resolves. Within a release, assets are matched by filename in this order, where <platform> is the host platform — darwin-aarch64, darwin-x86_64, linux-aarch64 or linux-x86_64:

Reference	Filenames tried, in order
`<name>@<version>`	`<name>-<version>-<platform>.mur.zip`, `<name>-<version>.mur.zip`
`<name>`	`<name>--<platform>.mur.zip`, `<name>.mur.zip`, `<name>-.mur.zip` — the last pattern matches only assets whose filename carries no platform tag

A platform tag in an asset filename is the publisher's declaration of which platform those bytes are for, so a tagged asset is only ever installed on the platform it names. When no filename matches, the install fails with E-REG-001 naming the host platform and the platforms the release publishes that artifact for. linux-aarch64 is a supported target for which Murmur's own releases publish no asset: an artifact needed there is built on that host with mur build and installed from the resulting path.

Authentication

Token resolution happens in this order:

The token field of the matching registry.sources entry in the effective config
The GITHUB_TOKEN environment variable

For github: URIs, Murmur borrows the token of the configured source whose repo is <owner>/<repo>, then falls back to GITHUB_TOKEN. Public repositories work without a token; private repositories require one.

The token field accepts three forms:

Value	Resolved as
`${GITHUB_TOKEN}`	Value of the `GITHUB_TOKEN` env var. No token is sent when the variable is unset
`MY_TOKEN`	Value of the `MY_TOKEN` env var, or the literal string if the var is unset
`ghp_abc123`	Used as-is

Multiple sources and fallthrough

For lookups by name, configured sources are tried in the order they appear in the effective registry.sources list, with the source named by registry.default moved to the front. A source that does not have the requested artifact falls through to the next.

registry:
  default: internal
  sources:
    - name: internal
      type: github
      repo: my-org/private-artifacts
      token: "${GITHUB_TOKEN}"
    - name: official
      type: github
      repo: murmur-nexus/default-artifacts

type is github. Full field reference: registry: section.

Default source

With neither ~/.murmur/config.yaml nor <cwd>/.murmur/config.yaml present, mur install uses one built-in source: the public GitHub repository murmur-nexus/default-artifacts, which needs no token. Once ~/.murmur/config.yaml exists, its registry.sources list is the whole chain — see Merge rules.

Local artifact cache

mur install writes into the project store; mur install -g writes into the global store.

Store	Root
Project	`<project root>/.murmur/artifacts/` — the nearest directory at or above the working directory that holds a `murmur.yaml`. Installing without one fails with `E-IO-001`
Global	`~/.murmur/artifacts/`

Under either root, an artifact occupies <name>/<version>/. A native artifact is a different binary per platform, so its three files carry the platform tag its payload was built for; every other payload is one set of bytes each host resolves, and its files carry no tag:

File	Holds
`<name>-<version>.mur.zip`	The artifact — a WASM component or a static skill
`<name>-<version>.sha256`	Its SHA-256
`<name>-<version>.meta.json`	Its name, version, runtime, platforms, description, tags and WIT contracts
`<name>-<version>-<platform>.mur.zip`	A native artifact's payload for one platform
`<name>-<version>-<platform>.sha256`	That payload's SHA-256
`<name>-<version>-<platform>.meta.json`	That payload's metadata, with `platforms` naming the one platform

One version directory holds one payload, hash and metadata file per platform installed, so installing a native artifact for a second platform sits beside the first rather than replacing it. A resolve prefers the tagged payload for the host's platform and falls back to the untagged one, which is how a WASM artifact resolves everywhere; a native artifact resolved through that fallback is reported as W-REG-001.

The runtime and artifact_runtime keys of the metadata file record what the packed murmur.yaml declares: the packaging type (native, wasm or static) and the role (tool, skill, driver or hook). Every command that resolves an artifact takes both from the artifact bytes, so a metadata file recording something else does not change what is resolved, run or deployed. mur list reads the metadata file rather than the artifact, so an artifact whose file records the wrong role is listed with a blank RUNTIME column until it is reinstalled.

The wit_contracts key of the metadata file records the versioned WIT interface names the packed component declares, under exports and imports. The store derives both lists from the artifact bytes on every write, so they always describe the artifact they sit beside. The key is absent for an artifact carrying no readable component — a native binary, a skill, or a payload that is not a WebAssembly component. mur list --contract <PREFIX> reads it; see mur list.

mur install --all-platforms <name>@<version> installs into the global store, once per platform it downloads for, writing the same three files per platform as any other install.

The global root is derived from $HOME (or $USERPROFILE on Windows). No environment variable overrides it; to relocate the store, set HOME before invoking mur.

Registry selection

A <name>@<version> reference is resolved against a registry first, and falls through to the configured sources only when the registry does not have it. The registry is the local store unless remote mode is selected, by --registry <url>, by registry.remote_url in murmur.yaml, or by registry.default: remote in murmur.yaml. Remote mode requires the NEXUS_API_KEY environment variable. See Registry selection rules.