feat: mise backend plugin for OCX

[michael-herwig]

Value

mise (~26k GitHub stars, rapidly replacing asdf) is the natural frontend partner for OCX's backend. An official mise backend plugin would let mise users install any OCI-hosted tool via OCX, giving OCX access to mise's large user base with minimal effort. The integration surface is already designed — ocx exec and ocx env are programmatic-first.

Context

mise's backend plugin system uses three Lua hooks (BackendListVersions, BackendInstall, BackendExecEnv) that map 1:1 to OCX's existing CLI surface. No existing OCI-registry backend for mise exists — this would be first-of-kind. The mise community is actively discussing offline/vendoring (mise vendor proposal, March 2026), which aligns with OCX's content-addressed offline model.

Key research findings:

• mise is consolidating the dev-tools space — replaces asdf + direnv + make in a single tool
• The Lua backend plugin contract is minimal: three hooks, each a single file
• The ocx: prefix in mise.toml would namespace OCX-managed tools cleanly
• aqua (another binary installer) is already integrated as a native mise backend — precedent exists

Scope

In scope:

• Lua backend plugin following mise-backend-plugin-template
• backend_list_versions.lua → delegates to ocx index list <registry>/<repo>
• backend_install.lua → delegates to ocx install <registry>/<repo>:<version>
• backend_exec_env.lua → delegates to ocx env --json <registry>/<repo>:<version>
• metadata.lua with plugin description
• Documentation for mise users
• Identifier mapping: ocx:ocx.sh/shellcheck at 0.11 in mise.toml

Out of scope:

• Native Rust backend compiled into mise core (wrong integration level — OCX handles the hard parts)
• Digest pinning in mise.toml (covered by mise.lock; OCX plugin just exposes versions)
• Changes to OCX core for mise compatibility

Design

# .mise.toml
[tools]
"ocx:ocx.sh/shellcheck" = "0.11"
"ocx:ocx.sh/cmake" = "3.28"
"ocx:ghcr.io/myorg/internal-tool" = "1.5"

graph LR
    A[".mise.toml"] -->|"ocx:ocx.sh/cmake"| B["mise backend plugin<br/>(Lua)"]
    B -->|"ocx index list"| C["OCX CLI"]
    B -->|"ocx install"| C
    B -->|"ocx env --json"| C
    C -->|OCI pull| D["Registry<br/>(ocx.sh, ghcr.io, ...)"]
    C -->|content store| E["~/.ocx/objects/"]

Loading

Open question: mise expects tools at a predictable install_path it controls. OCX's content-addressed store uses its own path layout. The plugin needs to either (a) symlink the OCX install into mise's directory, or (b) tell mise to use OCX's install path directly via the BackendExecEnv hook. Needs a spike.

Acceptance Criteria

• mise install ocx:ocx.sh/shellcheck@0.11 installs via OCX backend
• mise ls shows OCX-installed tools with correct versions
• mise exec -- shellcheck --version runs the OCX-installed binary
• Plugin works with private registries (passes through OCX auth)
• Plugin listed in mise registry / community backends

Dependencies

• None — can be built against OCX's current CLI surface
• Benefits from ocx.toml (feat: project-level toolchain config (ocx.toml + ocx.lock) #33) for the project config story but doesn't require it