---
slug: proto-v0.51
title: proto v0.51 - Unstable lockfiles and plugin registries
authors: [milesj]
tags: [lockfile, record, registry, oci, plugin, locator]
image: ./img/proto/v0.51.png
---

With this release, we're excited to introduce two major features that pave the way for proto's
future!

<!--truncate-->

## Unstable lockfile support

Lockfiles have been requested by the community since proto's inception, but adopting them has been a
non-trivial task, as it requires touching almost every aspect of proto. With that said, we've been
slowly reworking the internals to support lockfiles, and with this release, we're introducing
unstable support for them!

If you're unaware of what lockfiles are, they allow you to pin the exact version (and checksum) of a
tool that is installed, ensuring that your development environment is consistent and reproducible.
If you've used package managers like npm, Cargo, or uv, you're likely familiar with this concept.

In proto, the concept of lockfiles is mostly the same, but the manner in which they are created and
updated may differ based on other tools. To start, lockfiles in proto are _opt-in_ and can be
enabled with the new [`settings.unstable-lockfile`](/docs/proto/config#unstable-lockfile) setting in
`.prototools`.

```toml title=".prototools"
[settings]
unstable-lockfile = true
```

This will create a `.protolock` file in the current directory, relative to the `.prototools` file.
In effect, this locks that directory and all of its subdirectories. As a side-effect, nested
lockfiles are not supported.

To demonstrate how lockfiles work, installing the following tools with `proto install`...

```toml title=".prototools"
bun = "1.2.0"
deno = "2.4.0"
node = "22.17.0"

[settings]
unstable-lockfile = true
```

... would generate the following `.protolock` file:

```toml title=".protolock"
# Generated by proto. Do not modify!

[[tools.bun]]
spec = "1.2.0"
version = "1.2.0"
checksum = "sha256:fa72173cb2220d00e2d2650fefdc0b5b37bfd8bb33d8d671b50efb409c2f5745"

[[tools.deno]]
spec = "2.4.0"
version = "2.4.0"
checksum = "sha256:c913d018d64c48dcc5b7b90d844efb6d017595a7c1e237f89141df1b3ef8b962"

[[tools.node]]
spec = "22.17.0"
version = "22.17.0"
checksum = "sha256:cc9cc294eaf782dd93c8c51f460da610cc35753c6a9947411731524d16e97914"
```

### Updated workflows

The [`proto run`](/docs/proto/commands/run) (shims),
[`proto install`](/docs/proto/commands/install), and
[`proto uninstall`](/docs/proto/commands/uninstall) commands have been updated to support lockfiles.

When running or installing tools and a matching specification exists in the lockfile, the locked
version will be inherited even if there's a newer version upstream, and the tool's checksum will be
validated when available. These checks can be bypassed with the new `--update-lockfile` flag
(install only).

Inversely, when uninstalling tools, the lockfile will be updated to remove any matching
specification records.

### Still a work in progress

We are marking lockfiles as unstable as they have not been fully implemented or thoroughly tested.
There are other commands like [`proto outdated`](/docs/proto/commands/outdated) and
[`proto status`](/docs/proto/commands/status) that are not lockfile aware yet, but will be in the
future.

But please, give them a whirl and let us know what you think!

## Unstable OCI registries for plugin storage

Another important feature that is necessary for proto's success is support for an official plugin
registry. Before we get to that, we need to lay the groundwork for how plugins are stored and
distributed. With this release, we're introducing unstable support for
[OCI registries](https://opencontainers.org/) as a storage mechanism for plugins. If you're
unfamiliar with OCI registries, they are a standard for storing and distributing container images
(Docker), but can also be used to store other types of
[artifacts](https://oras.land/docs/concepts/artifact), in this case, WASM plugins.

To support registries, we have introduced a new
[`settings.unstable-registries`](/docs/proto/config#unstable-registries) setting in `.prototools`,
which allows you to configure a list of registries to query for applicable plugins. For example:

```toml title=".prototools"
[settings]
unstable-registries = [
  { registry: "ghcr.io", namespace: "moonrepo" }
]
```

Additionally, we are introducing a new `registry://` plugin locator, which allows you to configure a
plugin by its OCI reference.

```toml title=".prototools"
[plugins]
# Longform with tag
bun = "registry://ghcr.io/moonrepo/bun_tool:v1.2.3"
# Longform without tag
bun = "registry://ghcr.io/moonrepo/bun_tool"
# Shortform with tag
bun = "registry://bun_tool:v1.2.3"
# Shortform without tag
bun = "registry://bun_tool"
```

### How it works

Using a container registry to store plugins seems odd at first, but it actually allows us to
leverage existing specifications, infrastructure, and tools to manage and distribute plugins. We
don't want to re-invent the wheel here, so why not use something that most of the industry is
already using?

With that said, how does this work in proto? Since we are not a container image, we use the
[artifact portion of the specification](https://oras.land/docs/concepts/artifact) instead.
Primarily, plugins are stored in layers! The blob/content of WASM, TOML, JSON, and YAML plugins are
stored in CAS, and referenced in layers by a sha256 digest.

As for annotations, we support the
[OCI standard annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md),
but will also support moonrepo-specific annotations in the future.

:::info

At this time, we do not provide a mechanism for uploading plugins to a registry. You'll need to do
that manually.

:::

### Official registry?

We do have plans to support an official moonrepo plugin registry, for both proto and moon. We are in
the process of investigating solutions to this and will provide more details soon.

## Other changes

View the [official release](https://github.com/moonrepo/proto/releases/tag/v0.51.0) for a full list
of changes.

- Removed `--canary` from `proto install`, just use `canary` as the version specifier instead.

## Looking for contributors

We have a lot of cool stuff planned for proto, like backend plugins, more official tools, improved
workflows, an official registry, and more! So if you're interested in Rust or WASM, we would love
and appreciate your help. Feel free to ping us on Discord!
