Skip to content

Component Registry

The Run 2.0 registry allows you to publish, share, and install WASI components.

Official Registry

The official registry is hosted at:

Package Naming

Packages follow the format:

namespace:package@version

Examples:

  • wasi:http@0.2.0
  • myorg:utils@1.0.0
  • alice:calculator@2.1.3

Installing Packages

From run.toml

Add dependencies to your run.toml:

[dependencies]
"wasi:http" = "0.2.0"
"myorg:utils" = "1.0.0"

Then install:

run v2 install

Direct Install

Install a specific package:

run v2 install wasi:http@0.2.0

Install as dev dependency:

run v2 install test:mock --dev

Update Packages

Update all dependencies:

run v2 update

Update specific package:

run v2 update wasi:http

Publishing Packages

1. Configure Authentication

Get a token from the registry administrator, then set it:

export RUN_AUTH_TOKEN=your-token-here

run v2 publish --token your-token-here

[registry]
auth_token = "your-token-here"

Warning

Don't commit tokens to version control.

2. Configure Project

Ensure your run.toml has required metadata:

[project]
name = "myorg"           # This becomes the namespace
version = "1.0.0"
description = "My awesome component"
license = "MIT"
repository = "https://github.com/myorg/mypackage"

[[component]]
name = "calculator"      # Package name: myorg:calculator
source = "src/lib.rs"
language = "rust"
wit = "wit/calculator.wit"

3. Publish

Build and publish:

run v2 publish --build

Or publish pre-built components:

run v2 build --release
run v2 publish

Publish specific component:

run v2 publish --component calculator --build

4. Verify

Check your package on the registry:

# CLI
run v2 info myorg:calculator

# Web
open https://registry.esubalew.dev/browse/myorg:calculator

Registry API

The registry provides a REST API:

Endpoint Method Description
/packages GET List all packages
/browse GET Browse packages (HTML)
/browse/:name GET Package detail (HTML)
/api/v1/packages POST Publish package
/api/v1/packages/:name/versions GET List versions
/api/v1/packages/:name/:version GET Get metadata
/api/v1/search?q=query GET Search packages
/api/v1/stats GET Registry statistics
/health GET Health check

Examples

List packages:

curl https://registry.esubalew.dev/packages

Search:

curl "https://registry.esubalew.dev/api/v1/search?q=http"

Get package info:

curl https://registry.esubalew.dev/api/v1/packages/wasi:http/0.2.0

Self-Hosted Registry

You can run your own registry server.

Deploy to Render

  1. Fork the run repository
  2. Create a new Web Service on Render
  3. Connect to the registry-server/ directory
  4. Set environment variables:
  5. REGISTRY_ADMIN_TOKEN: Admin token for publishing
  6. PORT: Server port (Render sets this automatically)
  7. DATA_DIR: Data directory (default: ./data)

Environment Variables

Variable Description
PORT Server port
DATA_DIR Data storage directory
REGISTRY_URL Public base URL for download links (critical for hosted deploys)
MAX_UPLOAD_MB Max upload size (default: 50)
REGISTRY_ADMIN_TOKEN Admin token (can publish to any namespace)
REGISTRY_TOKENS Namespace tokens (format: ns1:token1,ns2:token2)

Token Types

Admin Token:

  • Set via REGISTRY_ADMIN_TOKEN
  • Can publish to any namespace
  • For registry administrators

Namespace Tokens:

  • Set via REGISTRY_TOKENS
  • Format: namespace:token,namespace:token
  • Each token can only publish to its namespace

Example:

REGISTRY_TOKENS=alice:secret1,bob:secret2,acme:secret3
  • alice token can publish alice:* packages
  • bob token can publish bob:* packages
  • acme token can publish acme:* packages

Verify Integrity

Verify installed packages against the lockfile:

run v2 verify

This checks SHA256 hashes of all cached components.

Custom Registry URL

Use a custom registry:

run.toml
[registry]
url = "https://my-registry.example.com"

Or via environment:

export RUN_REGISTRY_URL=https://my-registry.example.com
run v2 install mypackage

Or per-command:

run v2 publish --registry-url https://my-registry.example.com