Upload a module to the Viam Registry

1. Install the CLI

First, install the Viam CLI and authenticate to Viam, from the same machine that you intend to upload your module from.

brew tap viamrobotics/brews
brew install viam

sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-arm64
sudo chmod a+rx /usr/local/bin/viam

sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-amd64
sudo chmod a+rx /usr/local/bin/viam

brew tap viamrobotics/brews
brew install viam

go install go.viam.com/rdk/cli/viam@latest

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc

For more information see install the Viam CLI.

Authenticate your CLI session with Viam using one of the following options:

viam login

viam login api-key --key-id <api-key-id> --key <organization-api-key-secret>

2. Generate a metadata file

Next, run the viam module create command to choose a custom module name and generate the required metadata for your module. By default, a new module is created as private, meaning that it is only accessible to members of your organization, but you can choose to set the visibility of your module to public to make it accessible to all Viam users.

Select the private or public tab for instructions to upload your module with the respective visibility setting:

viam module create --name <your-module-name> --org-id <your-org-id>

This command creates a new meta.json metadata file in your current working directory, which serves as a template.

3. Edit the metadata file

Edit the newly-created meta.json file, and provide the required configuration information for your custom module by filling in the following fields.

For example, the following represents the configuration of an example my-module public module in the acme namespace:

{
  "module_id": "acme:my-module",
  "visibility": "public",
  "url": "https://github.com/<my-repo-name>/my-module",
  "description": "An example custom module.",
  "models": [
    {
      "api": "rdk:component:generic",
      "model": "acme:demo:my-model"
    }
  ],
  "build": {
    "path": "dist/archive.tar.gz", // optional - path to your built module
    "build": "./build.sh", // command that will build your module
    "arch": ["linux/amd64", "linux/arm64"] // architecture(s) to build for
  },
  "entrypoint": "dist/main" // path to executable
}

{
  "module_id": "acme:my-module",
  "visibility": "public",
  "url": "https://github.com/<my-repo-name>/my-module",
  "description": "An example custom module.",
  "models": [
    {
      "api": "rdk:component:generic",
      "model": "acme:demo:my-model"
    }
  ],
  "entrypoint": "my-module.sh" // path to executable
}

See meta.json file for more information.

4. (For Python) Package module as an archive

For modules written in Python, you should package your module files as an archive first, before uploading. Other languages can proceed to the next step to upload their module directly. To package a module written in Python, run the following command from the same directory as your meta.json file:

tar -czvf dist/archive.tar.gz <PATH-TO-EXECUTABLE>

where <PATH-TO-EXECUTABLE> is the packaged executable that runs the module at the entry point. If using PyInstaller, by default this would be dist/main.

For a Python module built using the venv approach, the command might look like this:

tar -czf module.tar.gz run.sh requirements.txt src

Where run.sh is your entrypoint file, requirements.txt is your pip dependency list file, and src is the directory that contains the source code of your module.

Supply the path to the resulting archive file in the next step.

5. Upload your module

Run viam module upload to upload your custom module to the Viam registry. Specify the path to the file, directory, or compressed archive (with .tar.gz or .tgz extension) that contains your custom module code:

viam module upload --version <version> --platform <platform> <module-path>

where:

• version: provide a version for your custom module, using semantic versioning (example: 1.0.0). You can later increment this value with subsequent viam module upload commands. See Using the --version argument for more information.
• platform: provide the system architecture your custom module supports. You can only provide one platform argument at a time to the viam module upload command. See Using the --platform argument for the full list of supported architectures.
• module-path: provide the path to the file, directory, or compressed archive (with .tar.gz or .tgz extension) that contains your custom module code.

For example:

• To upload a custom module that is defined in a single file named my-module-file in a local bin directory:

  viam module upload --version 1.0.0 --platform linux/amd64 ./bin/my-module-file
  

• To upload a custom module that includes multiple files, as well as a separate entry point file, all contained with a local bin directory:

  viam module upload --version 1.0.0 --platform linux/amd64 ./bin
  

• To upload a custom module that has been compressed as an archive named packaged-module.tar.gz:

  viam module upload --version 1.0.0 --platform linux/amd64 packaged-module.tar.gz
  

When you upload a module, the command performs basic validation of your module to check for common errors.

For more information, see the viam module command.