Upload your own modules to the Viam registry

Once you have created a custom module, you can use the Viam CLI to upload it to the Viam registry.

With the CLI, you can register your module with the Viam registry to share it with other Viam users, or upload it as a private module that is shared only within your organization.

For more information, see the viam module command.

Upload a custom module

To upload your custom module to the Viam registry, either as a public or private module, use the Viam CLI commands create, upload, and update following the instructions below:

First, install the Viam CLI and authenticate to Viam, from the same machine that you intend to upload your module from.
Next, run the viam module create command to select a new custom module name and generate module metadata.
1. If you haven’t already, create a new namespace for your organization. If you have already created a namespace, you can find it on your organization’s Settings page in the Viam App.
2. To generate metadata for your module using your public namespace, run the following command from the same directory as your custom module:
```
viam module create --name <your-module-name> --public-namespace <your-unique-namespace>
```
This command creates a new meta.json metadata file in your current working directory, which serves as a template on which to base your custom configurations. Editing and then uploading the meta.json file sets important configuration information about your module, such as whether it will be publicly available to all Viam users, or only available within your organization.

Edit the newly-created meta.json file, and provide the required configuration information for your custom module by filling in the following fields. The name field is pre-populated using the --name you provided in the viam module create command, and visibility is set to private by default.

Name	Type	Inclusion	Description
`module_id`	string	Required	The name of the module, including its namespace
`visibility`	string	Required	Whether the module is accessible only to members of your organization (`private`), or visible to all Viam users (`public`). You can change this setting later using the `viam module update` command. Default: `private`
`url`	string	Optional	The URL of the GitHub repository containing the source code of the module.
`description`	string	Required	A description of your module and what it provides.
`models`	object	Required	A list of one or more models provided by your custom module. You must provide at least one model, which consists of an `api` and `model` key pair.
`entrypoint`	string	Required	The name of the file that starts your module program. This can be a compiled executable, a script, or an invocation of another program.

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

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

Important

If you are publishing a public module ("visibility": "public"), the namespace of your model must match the namespace of your organization. In the example above, the model namespace is set to acme to match the owning organization’s namespace. If the two namespaces do not match, the command will return an error.

See The meta.json file for more information.

Run viam module update to register the configuration changes you just made to meta.json with the Viam registry. Run this command from within the same directory as your meta.json file:
```
viam module update
```
On a successful update, the command will return a link to the updated module in the Viam registry.
Package your custom module to get it ready to upload to the Viam registry. Currently, the Registry only supports tar.gz or tar.xz format. Use the command below specific for the language of your module:
- To package a module written in Go, run the following commands from the same directory as your meta.json file:
```
go build -o bin/module ./module/main.go
tar -cxf module.tar.gz bin/module
```
  For more information, see Compile a module into an executable.
- To package a module written in Python, run the following command from the same directory as your meta.json file:
```
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 source directory of your module.
Run viam module upload to upload the updated custom module to the Viam registry:
```
viam module upload --version <version> --platform <platform> module.tar.gz
```
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 one of the following, depending on the platform you have built your custom module for (You can use the uname -m command to determine your system architecture):
  - darwin/arm64 - macOS computers running the arm64 architecture, such as Apple Silicon.
  - darwin/amd64 - macOS computers running the Intel x86_64 architecture.
  - linux/arm64 - Linux computers or boards running the arm64 (aarch64) architecture, such as the Raspberry Pi.
  - linux/amd64 - Linux computers or boards running the Intel x86_64 architecture.
- path - provide the path to the compressed archive, in tar.gz or tar.xz format, that contains your custom module code.
Important
The viam module upload command only supports one platform argument at a time. If you would like to upload your module with support for multiple platforms, you must run a separate viam module upload command for each platform. Use the same version number when running multiple upload commands of the same module code if only the platform support differs. The Viam registry page for your module displays the platforms your module supports for each version you have uploaded.
For example, the following command uploads the compressed module.tar.gz archive to the Viam registry when run in the same directory as the corresponding meta.json file:
```
viam module upload --version 1.0.0 --platform darwin/arm64 module.tar.gz
```
When you upload a module, the command performs basic validation of your packaged module to ensure it is compatible with the Viam registry.

For more information, see the viam module command

Update an existing module

You can update an existing module in the Viam registry in one of two ways:

Upload new versions of your module manually using the Viam CLI.
Automatically upload new versions of your module on release as part of a continuous integration (CI) workflow, using a GitHub Action.

Updating your module manually is appropriate for smaller projects, especially those with only one contributor. Updating your module automatically using CI is better suited for larger, ongoing projects, especially those with multiple contributors.

Update an existing module using the Viam CLI

To update an existing module in the Viam registry manually, use the Viam CLI:

Edit your custom module with the changes you’d like to make.
Update your custom module’s meta.json file with the changes, if any. For example, if you have altered your model’s name, or adjusted the endpoint name, you’ll need to update meta.json with these changes.
Run viam module update to register the configuration changes you just made to meta.json with the Viam registry. Run this command from within the same directory as your meta.json file:
```
viam module update
```
On a successful update, the command will return a link to the updated module in the Viam registry.
Package your custom module to get it ready to upload to the Viam registry. Currently, the Registry only supports tar.gz or tar.xz format. Use the command below specific for the language of your module:
- To package a module written in Go, run the following commands from the same directory as your meta.json file:
```
go build -o bin/module ./module/main.go
tar -cxf module.tar.gz bin/module
```
  For more information, see Compile a module into an executable.
- To package a module written in Python, run the following command from the same directory as your meta.json file:
```
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 source directory of your module.
Run viam module upload to upload the updated custom module to the Viam registry:
```
viam module upload --version <version> --platform <platform> <path-to-tar.gz>
```
For example, the following command uploads the compressed my-module.tar.gz archive to the Viam registry when run in the same directory, and increments the version of the module to version 1.0.1:
```
viam module upload --version 1.0.1 --platform darwin/arm64 my-module.tar.gz
```
When you upload a module, the command performs basic validation of your packaged module to ensure it is compatible with the Viam registry.

For more information, see the viam module command

Update an existing module using a GitHub action

To update an existing module in the Viam registry using CI, use the upload-module GitHub action.

Edit your custom module with the changes you’d like to make.
Navigate to the Actions tab of the GitHub repository you are using for your module code. If you have already created GitHub actions for this repository, click the New workflow button to create a new one. If you have not yet created any GitHub actions, click the Set up a workflow yourself link. See the GitHub actions documentation for more information.

Paste the following action template YAML into the edit window.

on:
  push:
  release:
    types: [released]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: build
        run: echo "your build command goes here" && false # <-- replace this with the command that builds your module's tar.gz
      - uses: viamrobotics/upload-module@v1
        # if: github.event_name == 'release' # <-- once the action is working, uncomment this so you only upload on release
        with:
          module-path: module.tar.gz
          org-id: your-org-id-uuid # <-- replace with your org ID. not required for public modules
          platform: linux/amd64 # <-- replace with your target architecture, or your module will not deploy
          version: ${{ github.event_name == 'release' && github.ref_name || format('0.0.0-{0}.{1}', github.ref_name, github.run_number) }} # <-- see 'Versioning' section below for explanation
          key-id: ${{ secrets.viam_key_id }}
          key-value: ${{ secrets.viam_key_value }}

Edit the copied code to include the configuration specific to your module. Each item marked with a <-- comment requires that you edit the configuration values accordingly.
Set run to the command you use to build and package your module. When ready to test the action, uncomment if: github.event_name == 'release' to enable the action to trigger a run when you issue a release.
For guidance on configuring the other parameters, see the documentation for each:
- org-id - Not required if your module is public.
- platform - You can only upload one platform at a time.
- version - Also see Using the –version argument for more details on the types of versioning supported.
Create an organization API key and configure your GitHub repository to use it to authenticate during GitHub action runs, following the steps below:
1. Follow the instructions to Create an organization API key. These steps will return a key id and a key value which together comprise your organization API key. If you have already created an organization API key, you can skip this step.
2. In the GitHub repository for your project, select Settings, then Secrets and variables, then Actions.
3. Click the green New repository secret button, enter viam_key_id as the NAME, paste the value for key id from above into the Secret text field, then click Add secret.
4. Then, click the green New repository secret button, enter viam_key_value as the NAME, paste the value for key value from above into the Secret text field, then click Add secret.
For more information on GitHub secrets, see the GitHub documentation for Creating secrets for a repository.
Push a commit to your module or create a new release. The specific step to take to release your software depends on your CI workflow, your GitHub configuration, and the run step you defined earlier. Once complete, your module should upload to the Viam registry with the appropriate version automatically.

For more details, see the upload-module GitHub action documentation, or take a look through one of the following example repositories that show how to package and deploy modules using the Viam SDKs:

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!