Edit

Upload your Own Modules to the Viam Registry

Once you have created a custom module, use the instructions on this page to upload it to the Viam registry as a public module that is shared with other Viam users, or as a private module that is shared only within your organization.

You can upload your module in one of two ways:

You can upload your module using the Viam CLI, ideal for testing or on-demand releases. You can also update your module using the CLI to push code changes as needed.
You can use a GitHub Action to automatically upload your module when you make a new GitHub release, ideal for continuous integration (CI) pipelines.

Upload a custom module using the CLI

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

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 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:
- Private
- Public
Get the org-id for your organization from your organization’s Settings page in the Viam App and run the following command from the same directory as your custom module to generate metadata for your module:
```
viam module create --name <your-module-name> --org-id <your-org-id>
```
If you later wish to make your module public, you can use the viam module update command.
Important
If you mark your module as public, you cannot change it back to private.
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, or by running the viam organizations list command.
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.

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

Name	Type	Inclusion	Description
`module_id`	string	Required	The module ID, which includes either the module namespace or organization-id, followed by its name (pre-populated using the `--name` you provided in the `viam module create` command). Caution The `module_id` uniquely identifies your module. Do not change the `module_id`.
`visibility`	string	Required	Whether the module is accessible only to members of your organization (`private`), or visible to all Viam users (`public`). You can later make a private module public using the `viam module update` command, but once you make a module public, you cannot change it back to private. 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. If you are publishing a public module (`"visibility": "public"`), the namespace of your model must match the namespace of your organization. For more information, see naming your model.
`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. If you are providing your module as a single file to the `upload` command, provide the path to that single file. If you are providing a directory containing your module to the `upload` command, provide the path to the entry point file contained within that directory.
`build`	object	Optional	An object containing the command to run to build your module, as well as optional fields for the path to your dependency setup script, the target architectures to build for, and the path to your built module. Use this with the Viam CLI's build subcommand.

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/acme-co-example/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"
}

Important

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.

For more information, see Naming your model.

See meta.json file for more information.

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 dist/main
```

Where dist/main is the packaged executable that runs the module at the entry point.

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

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.
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:
- 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

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.

Tip

If you would like to test your module locally against its intended target platform before uploading it, you can follow the steps for Iterative module development to verify that any code changes you have made work as expected on your target platform.

Update an existing module using the Viam CLI

To update an existing module in the Viam registry manually, you can use the Viam CLI.

Tip

If you intend to make frequent code changes to your module, want to support a variety of platforms, or otherwise want to streamline your module development workflow, consider using a GitHub action to update your module instead.

Edit your custom module code with the changes you’d like to make.
Update your custom module’s meta.json file with any needed changes. For example, if you have altered your model’s description, or adjusted the endpoint name, you’ll need to update meta.json with these changes.
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 -czf module.tar.gz dist/main
```
Where dist/main is your packaged executable.
Supply the path to the resulting archive file in the next step.
Run viam module upload to upload your custom module to the Viam registry:
```
viam module upload --version <version> --platform <platform> <module-path>
```
For example, the following command uploads a module compressed as an archive named my-module.tar.gz to the Viam registry, 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 module to check for common errors.

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 continuous integration (CI), you can use one of two Github actions. You can only use these GitHub actions if you have already created the module by running viam module create and viam module update. For most use cases, we recommend the build-action GitHub action which provides a simple cross-platform build setup for multiple platforms: x86, ARM Linux, and MacOS. However, if you already have your own CI with access to arm runners or only intend to build on x86 or mac, you may also use the upload-module GitHub action instead which allows you to define the exact build steps.

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 one of the following action templates into the edit window, depending on whether you are using the build-action or upload-module action:

CI with build-action
CI with upload-action

# see https://github.com/viamrobotics/build-action for help
on:
  push:
    tags:
      - "[0-9]+.[0-9]+.[0-9]+" # the build-action will trigger on tags with the format 1.0.0

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: viamrobotics/build-action@v1
        with:
          # note: you can replace this line with 'version: ""' if
          # you want to test the build process without deploying
          version: ${{ github.ref_name }}
          ref: ${{ github.sha }}
          key-id: ${{ secrets.viam_key_id }}
          key-value: ${{ secrets.viam_key_value }}

The build-action GitHub action relies on a build command that you need to specify in the meta.json file that you created for your module when you first uploaded it. At the end of your meta.json, add the build configuration:

{
  "module_id": "example-module",
  ...
  "build": {
    "setup": "./setup.sh", // optional - command to install your build dependencies
    "build": "./build.sh", // command that will build your module
    "path" : "dist/archive.tar.gz", // optional - path to your built module
    "arch" : ["linux/amd64", "linux/arm64"] // architecture(s) to build for
  }
}

Click to view example setup.sh

#!/bin/bash
set -e
UNAME=$(uname -s)

if [ "$UNAME" = "Linux" ]
then
    echo "Installing venv on Linux"
    sudo apt-get install -y python3-venv
fi
if [ "$UNAME" = "Darwin" ]
then
    echo "Installing venv on Darwin"
    brew install python3-venv
fi

python3 -m venv .venv
. .venv/bin/activate
pip3 install -r requirements.txt

Click to view example build.sh (with setup.sh)

#!/bin/bash
pip3 install -r requirements.txt
python3 -m PyInstaller --onefile --hidden-import="googleapiclient" src/main.py
tar -czvf dist/archive.tar.gz dist/main

Click to view example build.sh (without setup.sh)

#!/bin/bash
set -e
UNAME=$(uname -s)

if [ "$UNAME" = "Linux" ]
then
    echo "Installing venv on Linux"
    sudo apt-get install -y python3-venv
fi
if [ "$UNAME" = "Darwin" ]
then
    echo "Installing venv on Darwin"
    brew install python3-venv
fi

python3 -m venv .venv
. .venv/bin/activate
pip3 install -r requirements.txt
python3 -m PyInstaller --onefile --hidden-import="googleapiclient" src/main.py
tar -czvf dist/archive.tar.gz dist/main

You can test this build configuration by running the Viam CLI’s build local command on your development machine:

viam module build local

The command will run your build instructions locally without running a cloud build job.

For more details, see the build-action 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:

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
          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, such as invoking a makefile or running a shell script. When you are 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.

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:

Create an organization API key with the owner role, which the GitHub action will use to authenticate to the Viam platform, using one of the following methods:
- Use the Viam CLI to create an organization API key, which includes the owner role by default:
```
viam organizations api-key create --org-id <org-id> --name <key-name>
```
- Use the organizations page on the Viam app to generate a new organization API key. Make sure your organization API key is set to Role: Owner, or the GitHub action will not be able to successfully authenticate during runs. If you are using an existing organization API key which is not set to Role: Owner, you can change an API key’s permissions from the Viam app on the organizations page by clicking the Show details link next to your API key. The operator role cannot be used to authenticate GitHub action runs. For more information see Manage organizations.
Both methods return a key id and a key value which together comprise your organization API key.
Then, configure your GitHub repository to use your organization API key to authenticate during GitHub action runs, following the steps below:
1. In the GitHub repository for your project, select Settings, then Secrets and variables, then Actions.
2. 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.
3. 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 tag to your repo 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 will upload to the Viam registry with the appropriate version automatically.

Next steps

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!

Upload your Own Modules to the Viam Registry

Upload a custom module using the CLI

Important

Caution

Important

Important

Update an existing module

Tip

Update an existing module using the Viam CLI

Tip

Update an existing module using a GitHub action

Next steps