Aqua Backend

Aqua tools can be used natively in mise. aqua is the ideal backend for new tools: it does not require plugins, it works on Windows, and it offers security features beyond checksums. aqua installs also show more progress bars, which is nice.

You do not need to install aqua separately. mise does not use the aqua CLI at all; it uses the aqua registry, which is compiled into the mise binary on release. Here is an example package entry: aqua:hashicorp/terraform. mise has its own reimplementation of aqua that reads these files to install tools.

By default, the bundled snapshot is used. The opt-in registry_floating setting checks the current official aqua registry first while retaining the bundled snapshot as a fallback. It also floats mise's shorthand registry; see Floating registries for the tradeoffs and cache behavior.

Some aqua tool configurations may need tightening up. Common issues are listed below; if you notice problems, I strongly recommend contributing fixes back to the aqua registry. The maintainer is very responsive and great to work with.

If all else fails, you can disable aqua entirely with MISE_DISABLE_BACKENDS=aqua.

Currently, aqua tools cannot set environment variables or do more than download binaries (and I'm not sure this functionality will ever be added), so some tools will likely always require asdf or vfox plugins.

The code for this backend is in the mise repository at ./src/backend/aqua.rs.

Custom Registry

Set aqua.registries to check custom aqua registry sources before the baked-in registry:

[settings]
aqua.registries = ["https://github.com/my-org/aqua-registry"]

To check multiple registries before the baked registry, list them in order:

[settings]
aqua.registries = [
  "https://github.com/my-org/internal-aqua-registry",
  "https://github.com/partner/aqua-registry",
]

Each source can be a repository URL, a direct URL to a registry.yaml or registry.yml file, or a local directory or registry file specified with an absolute file:// URL:

[settings]
aqua.registries = [
  "file:///absolute/path/to/aqua-registry",
  "file:///absolute/path/to/registry.yaml",
  "https://example.com/registry.yaml",
]

For repository and directory sources, mise loads registry.yaml from the source root, falling back to registry.yml if needed. Remote registry sources are cached under MISE_CACHE_DIR for aqua.registry_cache_ttl, which defaults to one week. Local file:// sources bypass the downloaded source cache, so changes are read the next time the registry is loaded. In MISE_AQUA_REGISTRIES, separate multiple registry URLs with commas.

After a refreshed registry source is downloaded, mise hashes the source and uses that hash in the compiled registry cache path. When a new compiled cache is successfully loaded or written, older compiled caches for the same registry URL are pruned.

Packages are resolved by checking the configured registries in order. When aqua.baked_registry is enabled, the baked-in registry remains a fallback for packages missing from all configured registries. Aqua registry aliases are local to the registry that defines them; use [tool_alias] when you want a mise shorthand or alias to point at an aqua package from another registry.

The legacy aqua.registry_url setting is still supported for a single registry URL, but aqua.registries takes precedence when both are set.

Usage

The following installs the latest version of ripgrep and sets it as the active version on PATH:

$ mise use -g aqua:BurntSushi/ripgrep
$ rg --version
ripgrep 14.1.1

The version is set in ~/.config/mise/config.toml with the following format:

[tools]
"aqua:BurntSushi/ripgrep" = "latest"

Some tools default to aqua because they are configured in registry/ to use the aqua backend. To see these tools, run mise registry | grep aqua:.

Tool Options

symlink_bins

Some tools bundle extra executables that you may not want exposed on PATH. For example, aws-cli bundles Python, which can conflict with your intended Python version.

Setting symlink_bins = true creates a filtered .mise-bins directory and exposes only the binaries intended for that aqua package, instead of every executable discovered in the install.

[tools]
aws-cli = { version = "latest", symlink_bins = true }

When enabled:

• If the aqua registry defines a files field, only those binaries are exposed (e.g., aws and aws_completer for aws-cli)
• Otherwise, mise falls back to exposing the inferred primary binary for the package
• A .mise-bins subdirectory is created with symlinks to the exposed binaries
• Bundled dependencies and other extra executables, such as Python in aws-cli, are not added to PATH

vars

Some aqua registry entries define template variables (for example {{.Vars.channel}}). Set them via tool options using either top-level keys or a nested vars table:

[tools]
"aqua:flutter/flutter" = { version = "3.32.8", channel = "stable" }
"aqua:scenarigo/scenarigo" = { version = "0.21.0", vars = { go_version = "1.24" } }

Vars with defaults are filled automatically. Vars marked as required in the aqua registry must be set unless the registry also provides a default.

prerelease

By default, releases flagged prerelease: true on GitHub are excluded from mise ls-remote and from latest resolution. Set prerelease = true to include them:

[tools]
"aqua:owner/tool" = { version = "latest", prerelease = true }

When set, pre-release tags (e.g. v1.0.0-rc1, v0.1.2-dev.86) appear in mise ls-remote, latest resolves against the full list including pre-releases, and fuzzy version queries match pre-release tags. The option has no effect when a package uses the github_tag version source (git tags don't carry a prerelease flag). Draft releases are always excluded. See the github backend docs for more detail.

Settings

aqua.baked_registry

• Type: boolean
• Env: MISE_AQUA_BAKED_REGISTRY
• Default: true

Use baked-in aqua registry.

aqua.cosign

• Type: boolean
• Env: MISE_AQUA_COSIGN
• Default: true

Use cosign to verify aqua tool signatures.

aqua.github_attestations

• Type: boolean
• Env: MISE_AQUA_GITHUB_ATTESTATIONS
• Default: true

Enable/disable GitHub Artifact Attestations verification for aqua tools. When enabled, mise will verify the authenticity and integrity of downloaded tools using GitHub's artifact attestation system.

aqua.minisign

• Type: boolean
• Env: MISE_AQUA_MINISIGN
• Default: true

Use minisign to verify aqua tool signatures.

aqua.registries

• Type: string[](optional)
• Env: MISE_AQUA_REGISTRIES(comma separated)
• Default: None

Aqua registry sources to load before the baked-in registry. Each source can be a repository URL, a direct URL to a registry.yaml or registry.yml file, or an absolute file:// URL to a local registry directory or file. For repository and directory sources, mise loads registry.yaml from the source root and falls back to registry.yml if needed.

A source that is not a URL is read as a filesystem path, resolved against the config root of the file that declared it. This is how you reference a registry committed alongside the project:

[settings]
aqua.registries = ["registry.yaml"]

Path resolution applies only to sources set in a config file, since only those have a config root to resolve against. A path given via MISE_AQUA_REGISTRIES or the CLI must be an absolute file:// URL.

Downloaded registries are cached according to aqua.registry_cache_ttl, which defaults to one week. To refresh sooner, run mise cache clear, set aqua.registry_cache_ttl = "0s", or change MISE_CACHE_DIR to use a different cache location. Local file:// sources bypass the downloaded source cache, so changes are read the next time the registry is loaded.

If this is set, mise checks the configured registries in order. When aqua.baked_registry is enabled, the baked-in aqua registry remains a fallback for packages missing from all configured registries.

By default, mise uses the baked-in official aqua registry when aqua.baked_registry is enabled. If the baked registry is disabled and no registries are configured, mise downloads the official registry: https://github.com/aquaproj/aqua-registry

aqua.registry_cache_ttl

• Type: string
• Env: MISE_AQUA_REGISTRY_CACHE_TTL
• Default: 1w

How long downloaded aqua registry source files remain fresh before mise re-downloads them.

When the downloaded source changes, mise writes the new source cache atomically, compiles a new source-hash-scoped registry cache, and prunes older compiled caches for that registry URL after the new compiled cache is available.

Set to 0s to re-download remote registries every time.

aqua.registry_urldeprecated

• Type: string(optional)
• Env: MISE_AQUA_REGISTRY_URL
• Default: None
• Deprecated: Use aqua.registries instead.

Deprecated. Use aqua.registries instead.

Legacy single aqua registry repository URL to fetch before the baked-in registry.

aqua.slsa

• Type: boolean
• Env: MISE_AQUA_SLSA
• Default: true

Use SLSA to verify aqua tool signatures.

Security Verification

The aqua backend supports multiple verification methods to ensure the integrity and authenticity of downloaded tools. mise provides a native Rust implementation of every method, so no external CLI tools such as cosign, slsa-verifier, or gh are needed.

GitHub Artifact Attestations

GitHub Artifact Attestations provide cryptographic proof that artifacts were built by specific GitHub Actions workflows. mise verifies these attestations natively to ensure the authenticity and integrity of downloaded tools.

Requirements:

• The tool must have a github_artifact_attestations entry in the aqua registry for attestations to be verified
• No external tools are required - verification is handled natively by mise

Configuration:

# Enable/disable GitHub artifact attestations verification (default: true)
export MISE_AQUA_GITHUB_ATTESTATIONS=true

Registry Configuration Example:

packages:
  - type: github_release
    repo_owner: cli
    repo_name: cli
    github_artifact_attestations:
      signer_workflow: cli/cli/.github/workflows/deployment.yml

Cosign Verification

mise natively verifies Cosign signatures without requiring the cosign CLI tool to be installed.

Configuration:

# Enable/disable Cosign verification (default: true)
export MISE_AQUA_COSIGN=true

SLSA Provenance Verification

mise natively verifies SLSA (Supply-chain Levels for Software Artifacts) provenance without requiring the slsa-verifier CLI tool.

Configuration:

# Enable/disable SLSA verification (default: true)
export MISE_AQUA_SLSA=true

Other Security Methods

aqua also supports:

• Minisign verification: Uses minisign for signature verification
• Checksum verification: Verifies SHA256/SHA512/SHA1/MD5 checksums (always enabled)

Verification Process

During tool installation, mise will:

1. Download the tool and any signature/attestation files
2. Perform native verification using the configured methods
3. Display verification status with progress indicators
4. Abort installation if any verification fails

Example output during installation:

✓ Downloaded cli/cli v2.50.0
✓ GitHub artifact attestations verified
✓ Tool installed successfully

Troubleshooting

If verification fails:

1. Check network connectivity: Verification requires downloading attestation data
2. Verify tool configuration: Ensure the aqua registry has correct verification settings
3. Disable specific verification: Temporarily disable problematic verification methods
4. Enable debug logging: Use MISE_DEBUG=1 to see detailed verification logs

Common issues:

• No attestations found: The tool may not have attestations configured in the registry
• Verification timeout: Network issues or slow attestation services
• Certificate validation: Clock skew or certificate chain issues

To disable all verification temporarily:

export MISE_AQUA_GITHUB_ATTESTATIONS=false
export MISE_AQUA_COSIGN=false
export MISE_AQUA_SLSA=false
export MISE_AQUA_MINISIGN=false

Common aqua issues

Here are some common issues I've seen when working with aqua tools.

Supported env missing

The aqua registry defines the supported os/arch envs for each tool. I've noticed that some of these are missing os/arch combos that are in fact supported—possibly because support was added after the tool's registry entry was created.

The fix is simple: edit the supported_envs section of registry.yaml for the tool in question.

Using version_filter instead of version_prefix

This is a weird one that causes odd issues in mise. In general, mise prefers versions like 1.2.3 without decoration such as v1.2.3 or cli-v1.2.3. This consistency not only keeps mise.toml cleaner, it also helps commands like mise up work correctly, because the version can be parsed as semver without a bunch of edge cases.

If you notice aqua tools giving you versions that aren't simple triplets, it's worth fixing.

One common issue I've seen is registries using a version_filter expression like Version startsWith "atlascli/".

This causes the version to be atlascli/1.2.3, which is not what we want. The fix is to use version_prefix instead of version_filter and put the prefix (atlascli/ in this example) in the version_prefix field. mise automatically strips the prefix and adds it back when needed, which it can't do with version_filter.