Deploy a module

A module that only runs locally on your development machine is useful for testing but limits what you can do. Deploying through the Viam module registry lets you:

• Install on any machine in your organization (or publicly) through the Viam app – no SSH or manual file copying.
• Update over the air – release a new version and machines pick it up automatically within minutes.
• Target multiple platforms – cloud build compiles for every architecture you need so you don’t have to cross-compile locally.

For background on the module registry, versioning, and cloud builds, see the overview.

Steps

1. Review meta.json

The generator creates a meta.json file in your module directory. Open it and review each field:

{
  "module_id": "my-org:my-sensor-module",
  "visibility": "private",
  "url": "https://github.com/my-org/my-sensor-module",
  "description": "A custom sensor module that reads temperature and humidity from an HTTP endpoint.",
  "models": [
    {
      "api": "rdk:component:sensor",
      "model": "my-org:my-sensor-module:my-sensor"
    }
  ],
  "entrypoint": "run.sh",
  "build": {
    "setup": "./setup.sh",
    "build": "./build.sh",
    "path": "dist/archive.tar.gz",
    "arch": ["linux/amd64", "linux/arm64"]
  }
}

Visibility options:

• private – only your organization can see and use the module.
• public – all Viam users can see and use it. Requires your organization to have a public namespace.
• public_unlisted – any user can use the module if they know the ID, but it does not appear in registry search results.

Common api values:

• rdk:component:sensor for sensors
• rdk:component:camera for cameras
• rdk:component:motor for motors
• rdk:component:generic for generic components
• rdk:service:vision for vision services

2. Review the generated build scripts

The generator creates build and setup scripts for your module. Review them and customize if needed:

Make sure all scripts are executable:

chmod +x setup.sh build.sh run.sh

3. Write a README (recommended)

Document your module and its models so users know how to configure and use them. If you plan to make your module public, a good README is essential.

# `my-sensor-module`

This module implements the [Viam sensor API](https://docs.viam.com/dev/reference/apis/components/sensor/) in a `my-org:my-sensor-module:my-sensor` model.
With this model, you can gather temperature and humidity data from a custom HTTP endpoint.

Navigate to the **CONFIGURE** tab of your machine's page.
Click the **+** button, select **Configuration block**, then select the `sensor / my-sensor-module:my-sensor` model provided by the [`my-sensor-module` module](https://app.viam.com/module/my-org/my-sensor-module).
Click **Add module**, enter a name for your sensor, and click **Create**.

## Models

This module provides the following model(s):

- [`my-org:my-sensor-module:my-sensor`](#my-sensor) - A custom sensor that reads temperature and humidity from an HTTP endpoint

# Model `my-org:my-sensor-module:my-sensor`

A description of what this model does and what hardware or services it supports.

## Configuration

The following attribute template can be used to configure this model:

```json
{
  "source_url": "<string>",
  "poll_interval": <float>
}
```

### Attributes

| Name            | Type   | Required | Description                                 |
| --------------- | ------ | -------- | ------------------------------------------- |
| `source_url`    | string | Yes      | The HTTP endpoint to read sensor data from  |
| `poll_interval` | float  | No       | Polling interval in seconds (default: 10.0) |

### Example Configuration

```json
{
  "source_url": "https://api.example.com/sensor/data",
  "poll_interval": 5.0
}
```

## DoCommand

If your model implements DoCommand, document each supported command.

### Example DoCommand

```json
{
  "command": "calibrate",
  "offset": 1.5
}
```

You can point your module’s registry page to a README by setting the markdown_link field in meta.json to a file path (for example, README.md) or a section anchor (for example, README.md#my-sensor).

4. Deploy with cloud build (recommended)

Cloud build is the recommended way to deploy modules. It uses GitHub Actions to compile your module for every target platform automatically, so you don’t need to cross-compile locally.

The generator creates the workflow file at .github/workflows/deploy.yml. To use it:

Push your code to GitHub:

cd my-sensor-module
git init
git add .
git commit -m "Initial module code"
git remote add origin https://github.com/my-org/my-sensor-module.git
git push -u origin main

Add Viam credentials as GitHub secrets:

1. In the Viam app, go to your organization’s settings.
2. Create an API key with organization-level access (or use an existing one).
3. In your GitHub repository, go to Settings > Secrets and variables > Actions.
4. Add two secrets:
   • VIAM_KEY_ID – your API key ID
   • VIAM_KEY_VALUE – your API key

Tag a release to trigger the build:

git tag v0.1.0
git push origin v0.1.0

The GitHub Action runs automatically. Monitor progress in the Actions tab of your GitHub repository. When it completes, your module is in the registry and ready to install on any machine.

You can also trigger a cloud build from the CLI:

viam module build start

viam module build start --ref master

5. Deploy manually (alternative)

If you cannot use cloud build, you can build and upload from the command line.

Build locally:

cd my-sensor-module
bash build.sh

cd my-sensor-module
# Cross-compile for the target platform
GOOS=linux GOARCH=arm64 go build -o dist/module cmd/module/main.go
tar -czf dist/archive.tar.gz -C dist module

Upload to the registry:

viam module upload \
    --version=0.1.0 \
    --platform=linux/arm64 \
    dist/archive.tar.gz

To support multiple platforms, cross-compile and upload once per platform:

# Build and upload for amd64
GOOS=linux GOARCH=amd64 go build -o dist/module cmd/module/main.go
tar -czf dist/archive.tar.gz -C dist module
viam module upload --version=0.1.0 --platform=linux/amd64 dist/archive.tar.gz

# Build and upload for arm64
GOOS=linux GOARCH=arm64 go build -o dist/module cmd/module/main.go
tar -czf dist/archive.tar.gz -C dist module
viam module upload --version=0.1.0 --platform=linux/arm64 dist/archive.tar.gz

6. Configure the module on a machine

Once your module is in the registry, any machine in your organization can use it.

1. In the Viam app, navigate to your machine’s CONFIGURE tab.
2. Click + and select Configuration block.
3. Search for your module by name or browse the registry.
4. Add the module and create a component (or service) instance.
5. Name the component and configure the attributes your module expects:

{
  "source_url": "https://api.example.com/sensor/data"
}

7. Click Save.

viam-server downloads the module from the registry, starts it, and makes the component available. Test it from the CONTROL tab.

7. Manage versions

Release a new version:

git add .
git commit -m "Add humidity calibration offset"
git tag v0.2.0
git push origin main v0.2.0

If using cloud build, the workflow runs automatically. For manual upload:

viam module upload --version=0.2.0 --platform=linux/amd64 dist/archive.tar.gz

Automatic updates: By default, machines track the latest version. When you upload v0.2.0, all machines update automatically within a few minutes.

Pin to a specific version:

1. In the Viam app, go to the machine’s CONFIGURE tab.
2. Find the module in the configuration.
3. Set the Version field to the specific version (for example, 0.1.0).
4. Click Save.

View module details:

You can view version history and details for your module in the Viam registry.

8. Keep meta.json in sync with your code

As you add models to your module, you can auto-detect them from a built binary instead of editing meta.json by hand:

viam module update-models --binary ./bin/module

This inspects the binary, discovers registered models, and updates the models array in meta.json.

Then push the updated metadata to the registry:

viam module update

9. Download a module

To download a module from the registry (for testing or inspection):

viam module download --id my-org:my-sensor-module --version 0.1.0 --platform linux/amd64 --destination ./downloaded-module

Platform constraints

When uploading, you can attach platform constraint tags that restrict which machines can use a particular upload. For example, to require Debian:

viam module upload \
    --version=0.1.0 \
    --platform=linux/amd64 \
    --tags=distro:debian \
    dist/archive.tar.gz

The machine must report matching platform tags for the constrained upload to be selected. If no constraints are specified, the upload is available to all machines on that platform.

Upload limits

The registry enforces these size limits:

Before uploading, the CLI validates that:

• The entrypoint executable exists in the archive
• The entrypoint has execute permissions
• No symlinks escape the archive boundaries

Use --force to skip these checks (not recommended for production uploads).

Try It

1. Review the generated meta.json and build scripts in your module directory.
2. Push your code to GitHub and add the Viam API key secrets.
3. Tag a release (v0.1.0) to trigger a cloud build.
4. Navigate to a machine in the Viam app and add your module from the registry.
5. Configure a component and set the required attributes.
6. Open the CONTROL tab and verify the component works.
7. Tag a new release (v0.2.0) and verify the machine picks it up automatically within a few minutes.

Troubleshooting