s3 backend

The s3 backend installs a binary or archive from Amazon S3 or S3-compatible storage such as MinIO. Use it when access should follow your AWS credentials, or when versions come from listing a bucket; for public or token-protected URLs, the http backend is simpler. It needs no AWS CLI.

Usage

Replace the bucket and object key below with an artifact you can read for your platform, then install it in the current project:

mise use 's3:my-tool[url=s3://my-bucket/tools/my-tool-v1.0.0.tar.gz]@1.0.0'
mise exec -- my-tool --version

Quote the argument so the shell does not expand the brackets. This writes the following to mise.toml. Add -g for a global tool.

[tools]
"s3:my-tool" = { version = "1.0.0", url = "s3://my-bucket/tools/my-tool-v1.0.0.tar.gz" }

With a fixed URL, the version is only a label. To follow releases, put the version in the URL and set up version discovery.

Authentication

mise uses the AWS SDK's default credential provider chain. It supports environment credentials, shared AWS profiles, web identity, and container or instance roles. Prefer an existing profile or workload role over copying long-lived access keys into project configuration.

For a configured local profile:

AWS_PROFILE=development AWS_REGION=us-east-1 mise install

Temporary environment credentials need AWS_SESSION_TOKEN as well as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. The region tool option sets the bucket's region explicitly.

Downloading a known object needs s3:GetObject. Version discovery from an object listing also needs s3:ListBucket, and discovery from a manifest needs read access to the manifest. A successful download does not prove that listing is allowed.

Tool options

url

The object to download, as s3://<bucket>/<key>. Set it at the top level, or per platform under platforms.<os>-<arch>.url; a tool needs one or the other. The key is a template:

[tools]
"s3:my-tool" = { version = "1.0.0", url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz" }

endpoint

A custom S3-compatible endpoint, such as MinIO, DigitalOcean Spaces or a self-hosted service. With an endpoint set, mise uses path-style bucket addressing.

[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
endpoint = "https://minio.example.com"

region

The AWS region of the bucket. Without it, mise uses the region from your AWS configuration, such as AWS_REGION or the profile.

[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
region = "us-west-2"

Options shared with the http backend

These options work as described for the http backend:

• URL templates and per-platform downloads
• checksum and size
• format, strip_components, bin_path, bin and rename_exe

Unlike http, this backend also applies bin to archives: it renames the archive's main executable. When neither bin nor rename_exe is set and an archive holds a single executable, mise removes an OS or architecture suffix from its name, as it does for single-file downloads.

The s3 backend does not support checksum_url, checksum_expr, headers, headers_forward, shared_extraction, windows_script_interpreter or version_order. mise lock records the object URL and any checksum you set.

Version discovery

The s3 backend finds versions from a manifest or from an object listing. Configure one of them before you use latest, then check it with mise ls-remote s3:my-tool. When both are set, mise uses the manifest. Versions that look like prereleases, such as 2.0.0-rc1, are left out unless the tool sets prerelease = true.

From a manifest

Set version_list_url to the s3:// URL of a file that lists versions:

[tools."s3:my-tool"]
version = "latest"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
version_list_url = "s3://my-bucket/tools/versions.json"

The manifest can be a JSON array of version strings, such as ["1.0.0", "1.1.0", "2.0.0"], or any other format the http backend reads. version_regex, version_json_path and version_expr work as on the http backend:

[tools."s3:my-tool"]
version = "latest"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
version_list_url = "s3://my-bucket/tools/releases.json"
version_json_path = ".[].version"

mise keeps the manifest's order and treats the last entry as the newest, so list versions oldest first.

From an object listing

Set version_prefix to the key prefix to list, without the bucket name. mise takes the bucket from url, lists the keys under the prefix, and extracts a version from each key with version_regex: its first capture group, or the whole match when there is none. version_regex defaults to ([0-9]+\.[0-9]+\.[0-9]+).

[tools."s3:my-tool"]
version = "latest"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
version_prefix = "tools/my-tool-v"
version_regex = 'my-tool-v(.+)\.tar\.gz$'

On this backend version_prefix is an object key prefix, not a tag prefix as on the github backend.

S3 returns keys in alphabetical order, and mise keeps that order, so latest is the last match: 1.9.0 comes after 1.10.0. When versions differ in the number of digits, pin the version or use a manifest.

Custom endpoint example (MinIO)

A complete configuration for a MinIO server:

[tools."s3:my-internal-tool"]
version = "latest"
url = "s3://tools-bucket/releases/my-tool-{{ version }}.tar.gz"
endpoint = "https://minio.example.com"
region = "us-east-1"
version_list_url = "s3://tools-bucket/releases/versions.json"
strip_components = 1 # assumes one outer directory containing bin/
bin_path = "bin"

Provide the MinIO access key and secret through an AWS profile or the standard environment variables, then run mise install. An https:// endpoint must present a certificate your system trusts; a local http:// endpoint also works.

Troubleshooting

Error	Check
Access denied	The selected profile or role, object read permissions, and listing permissions when using version_prefix.
Object not found	The bucket, full key, concrete version, and rendered platform URL.
Signature mismatch	Credentials, session token, region, endpoint, and local clock.
No versions	The manifest format or listing prefix and capture group. A download URL alone does not define a version list.
latest is an old version	The listing or manifest order; see From an object listing.
Installed command missing	The archive structure after root stripping and the bin or bin_path option.

Implementation: src/backend/s3.rs.