Get started

Review a source URL, lock the first bytes fetched, and verify later copies offline.

Requirements and installation

Prebuilt archives need no Go installation. Download the matching macOS, Linux, or Windows archive and its signed checksums from GitHub Releases.

Go projects can instead pin Muamba in their module. This path requires Go 1.26.5 or later:

Install

go get -tool github.com/araihu/muamba/cmd/muamba@v0.0.3
go tool muamba help

Workflow examples below use the standalone command. Project CI and Go code generation keep the module-pinned tool.

Write a manifest

A resource groups related downloads under one version. Each download names a destination path and either a base URL or platform-specific URLs.

muamba.yaml

schema: 1

resources:
  bootstrap:
    version: "5.3.8"
    downloads:
      bundle-js:
        url: https://unpkg.com/bootstrap@${version}/dist/js/bootstrap.bundle.min.js
        path: assets/vendor/bootstrap/${version}/bootstrap.bundle.min.js
      core-css:
        url: https://unpkg.com/bootstrap@${version}/dist/css/bootstrap.min.css
        path: assets/vendor/bootstrap/${version}/bootstrap.min.css
      license:
        url: https://unpkg.com/bootstrap@${version}/LICENSE
        path: assets/vendor/bootstrap/${version}/LICENSE

${version} is the only template token. With strict mode, Muamba rejects URLs that omit the declared version before it downloads or writes anything.

Review, lock, and verify

You choose what to trust

Review each source URL before you run lock. Running lock accepts the first response and records its digest. The digest detects later changes; it does not authenticate the publisher or content.

1. Lock reviewed sources

First trust

muamba lock --strict

Lock downloads every unlocked URL and platform variant, caches the first fetched bytes, and writes their SHA-384 SRI locks to the manifest atomically.

2. Verify offline

Read-only verification

muamba verify --strict

Default verify checks materialized files without network access. Run verify --all-platforms to check every locked cache variant.

3. Restore known bytes

Materialize

muamba sync --strict

Sync checks the destination first, then the cache, then the network. Cached or remote bytes must match the lock before the destination changes.

Use the integrity cache

The cache key is the integrity algorithm plus digest. URL, version, and resource name do not affect identity, so identical locked bytes share one blob.

go tool muamba sync --strict \
  --target linux/amd64 \
  --cache-dir .cache/muamba

Generate a Go embed registry

Run generate-go once for each Go package that owns vendored files. The generated registry exposes resources, files, original integrity, and normalized digests.

Generate

go tool muamba generate-go \
  --strict \
  -f muamba.yaml \
  --dir assets \
  --output muamba_gen.go

Use

hash, ok := assets.MuambaHash("bootstrap", "core-css")
if !ok {
	return errors.New("bootstrap/core-css is not embedded")
}
stylesheetURL := "/assets/bootstrap.css?v=" + url.QueryEscape(hash)

Use the full reference

The README documents platform maps, selectors, size limits, updates, transport controls, and failure guarantees.

Read the complete README on GitHub.