Upload your own modules to the Viam registry
Once you have created a custom module, use the Viam CLI 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.
Once uploaded, you can also update your modules.
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 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 thevisibility
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: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.
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.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 theviam module create
command).Caution
The
module_id
uniquely identifies your module. Do not change themodule_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 theviam 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
andmodel
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 theupload
command, provide the path to the entry point file contained within that directory.For example, the following represents the configuration of an example
my-module
public module in theacme
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
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.Run
viam module update
to register the configuration changes you just made tometa.json
with the Viam registry. Run this command from within the same directory as yourmeta.json
file:viam module update
On a successful update, the command will return a link to the updated module in the Viam registry.
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 run.sh requirements.txt src
Where
run.sh
is your entrypoint file,requirements.txt
is your pip dependency list file, andsrc
is the source directory of your module.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 subsequentviam module upload
commands. See Using the--version
argument for more information.platform
: provide the system architecture your custom module supports. You can only provide oneplatform
argument at a time to theviam 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 oneplatform
argument at a time. If you would like to upload your module with support for multiple platforms, you must run a separateviam module upload
command for each platform. Use the same version number when running multipleupload
commands of the same module code if only theplatform
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 localbin
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.
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 any needed changes. For example, if you have altered your model’s name, or adjusted the endpoint name, you’ll need to updatemeta.json
with these changes.Run
viam module update
to register the configuration changes you just made tometa.json
with the Viam registry. Run this command from within the same directory as yourmeta.json
file:viam module update
On a successful update, the command will return a link to the updated module in the Viam registry.
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 run.sh requirements.txt src
Where
run.sh
is your entrypoint file,requirements.txt
is your pip dependency list file, andsrc
is the source directory of your module.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 theversion
of the module to version1.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), 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 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 you are ready to test the action, uncommentif: 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:
Follow the instructions to create an organization API key. These steps will return a
key id
and akey value
which together comprise your organization API key. If you have already created an organization API key, you can skip this step.In the GitHub repository for your project, select Settings, then Secrets and variables, then Actions.
Click the green New repository secret button, enter
viam_key_id
as the NAME, paste the value forkey id
from above into the Secret text field, then click Add secret.Then, click the green New repository secret button, enter
viam_key_value
as the NAME, paste the value forkey 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 will 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:
Naming your model: namespace:repo-name:name
If you are creating a custom module and want to upload that module to the Viam registry, ensure your model name meets the following requirements:
- The namespace of your model must match the namespace of your organization.
For example, if your organization uses the
acme
namespace, your models must all begin withacme
, likeacme:demo:mybase
. - Your model triplet must be all-lowercase.
- Your model triplet may only use alphanumeric (
a-z
and0-9
), hyphen (-
), and underscore (_
) characters.
For the middle segment of your model triplet repo-name
, use the name of the git repository where you store your module’s code.
The repo-name
should describe the common functionality provided across the model or models of that module.
For example:
The
rand:yahboom:arm
model and therand:yahboom:gripper
model uses the repository name yahboom. The models implement therdk:component:arm
and therdk:component:gripper
API to support the Yahboom DOFBOT arm and gripper, respectively:{ "api": "rdk:component:arm", "model": "rand:yahboom:arm" }, { "api": "rdk:component:gripper", "model": "rand:yahboom:gripper" }
The
viam-labs:audioout:pygame
model uses the repository name audioout It implements the custom APIviam-labs:service:audioout
:{ "api": "viam-labs:service:audioout", "model": "viam-labs:audioout:pygame" }
The viam
namespace is reserved for models provided by Viam.
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!