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

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"
    }
  ],
  "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 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.
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, and src 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 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.

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 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.
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, and src 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 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), 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, 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 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 with acme, like acme:demo:mybase.
Your model triplet must be all-lowercase.
Your model triplet may only use alphanumeric (a-z and 0-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 the rand:yahboom:gripper model uses the repository name yahboom. The models implement the rdk:component:arm and the rdk: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 API viam-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!

Upload your own modules to the Viam registry

Upload a custom module

Important

Caution

Important

Important

Update an existing module

Update an existing module using the Viam CLI

Update an existing module using a GitHub action

Naming your model: namespace:repo-name:name

Next Steps