Module developer reference

This page is a reference for module developers. For step-by-step instructions, see Write a Module and Deploy a Module.

Module configuration

For details on configuring modules and modular resources on a machine:

• Environment variables — custom env vars passed to your module
• Registry validation rules — valid API and model identifier formats
• meta.json schema — module metadata including visibility settings

Module lifecycle

Every module, local or registry, runs as a separate child process alongside viam-server, communicating over gRPC.

1. viam-server starts and checks for configuration updates (if online).
2. If the module has a first_run script that hasn’t succeeded yet, viam-server runs it before starting the module.
3. viam-server starts each configured module as a child process, passing it a socket address.
4. The module registers its models and APIs with viam-server through the Ready RPC.
5. For each configured resource, viam-server calls ValidateConfig to check attributes and discover dependencies.
6. viam-server starts required dependencies first. If a required dependency fails, the resource that depends on it does not start.
7. viam-server calls AddResource to create each resource. The module’s constructor runs and reads config.
8. The resource is available for use.
9. When the user changes configuration, viam-server closes the existing resource instance and calls AddResource again with the new config. The constructor runs a second time. This must complete within the per-resource configuration timeout (default: 2 minutes, configurable with VIAM_RESOURCE_CONFIGURATION_TIMEOUT).
10. On shutdown, viam-server sends RemoveResource for each resource, then terminates the module process.

First-run scripts

If your module needs one-time setup (installing system packages, downloading models, etc.), set the first_run field in meta.json to the path of a setup script inside your archive.

• The script runs before the module entrypoint, with the same environment variables available to the module.
• If the script exits with a non-zero status, reconfiguration is aborted. Currently running modules continue with their previous configuration.
• On success, a .first_run_succeeded marker file is created next to the module binary. The script will not re-run unless this marker is deleted or a new module version is installed.
• The default timeout is 1 hour, configurable through first_run_timeout in the module config.

Crash recovery

If a module process crashes, viam-server automatically restarts it:

1. viam-server detects the exit and marks the module as failed.
2. The machine’s status changes to initializing.
3. viam-server retries every 5 seconds.
4. On success, viam-server re-adds all resources in dependency order.
5. The machine returns to running.

If the module keeps crashing, viam-server retries indefinitely. Check the LOGS tab for crash tracebacks.

Communication

By default, modules communicate with viam-server over a Unix domain socket with a randomized name.

TCP mode is used automatically on Windows or when the Unix socket path would exceed the OS limit (103 characters on macOS). Force TCP mode by setting "tcp_mode": true in the module config or setting VIAM_TCP_SOCKETS=true.

Data directory

Every module receives a persistent data directory at ~/.viam/module-data/<robot-id>/<module-name>/. The path is available inside the module through the VIAM_MODULE_DATA environment variable. This directory persists across module restarts and reconfigurations.

Timeouts

Resource interfaces (Go)

Config validation

type ConfigValidator interface {
    Validate(path string) (requiredDependencies, optionalDependencies []string, err error)
}

Return required dependency names in the first slice. viam-server ensures they are ready before calling your constructor. Return optional dependency names in the second slice. These are passed to the constructor if available, but their absence does not block startup.

Resource interface

Every resource must implement:

type Resource interface {
    Name() Name
    DoCommand(ctx context.Context, cmd map[string]interface{}) (map[string]interface{}, error)
    Close(ctx context.Context) error
}

Plus the methods defined by the specific API (for example, Readings for sensor, GetImages for camera).

Constructor signature

func(ctx context.Context, deps resource.Dependencies,
    conf resource.Config, logger logging.Logger) (ResourceT, error)
}

Helper traits

Embed these in your resource struct to get default implementations:

Useful functions

Resource interfaces (Python)

Config validation

@classmethod
def validate_config(cls, config: ComponentConfig) -> Tuple[Sequence[str], Sequence[str]]:
    # Return (required_deps, optional_deps)
    return [], []

Constructor

@classmethod
def new(cls, config: ComponentConfig,
        dependencies: Mapping[ResourceName, ResourceBase]) -> Self:
    instance = cls(config.name)
    # Parse config and resolve dependencies here.
    # new() runs on initial creation and on every config change.
    return instance

Close

async def close(self):
    # Clean up connections, stop background tasks, release hardware.
    # Must be idempotent (safe to call multiple times).
    pass

The default close() on ResourceBase is a no-op.

EasyResource base class

For simple modules, inherit from both the API base class and EasyResource to get default new(), validate_config(), and automatic model registration:

from viam.components.sensor import Sensor
from viam.resource.easy_resource import EasyResource
from viam.module.module import Module

class MySensor(Sensor, EasyResource):
    MODEL = "my-org:my-module:my-sensor"

async def get_readings(self, **kwargs):
        return {"temperature": 23.5}

if __name__ == '__main__':
    import asyncio
    asyncio.run(Module.run_from_registry())

Useful functions

Python and Go defaults

The default behavior when you don’t implement a method:

Logging

From modules you can log at the resource level or at the machine level. Resource-level logging is recommended because it makes it easier to identify which component or service produced a message. Resource-level error logs also appear in the Error logs section of each resource’s configuration card.

# Resource-level logging (recommended):
self.logger.debug("debug info")
self.logger.info("info")
self.logger.warn("warning info")
self.logger.error("error info")
self.logger.exception("error info", exc_info=True)
self.logger.critical("critical info")

For machine-level logging instead of resource-level:

from viam.logging import getLogger

LOGGER = getLogger(__name__)

LOGGER.debug("debug info")
LOGGER.info("info")
LOGGER.warn("warning info")
LOGGER.error("error info")

func (c *component) someFunction(ctx context.Context, a int) {
  // Log with severity info:
  c.logger.CInfof(ctx, "performing some function with a=%v", a)
  // Log with severity debug (using value wrapping):
  c.logger.CDebugw(ctx, "performing some function", "a" ,a)
  // Log with severity warn:
  c.logger.CWarnw(ctx, "encountered warning for component", "name", c.Name())
  // Log with severity error without a parameter:
  c.logger.CError(ctx, "encountered an error")
}

To see debug-level logs, run viam-server with the -debug flag or configure debug logging for your machine or individual resource.

Common gotchas

Put config-reading in the constructor.viam-server rebuilds your resource on every config change, so the constructor runs on both initial creation and every reconfiguration. Read config fields and resolve dependencies there; don’t scatter that logic across multiple methods.

Clean up in Close(). If your resource starts background goroutines, opens connections, or holds hardware handles, Close() must stop them. Leaked goroutines accumulate across reconfigurations and can cause instability. In Python, close() must be idempotent (it may be called more than once).

Return the right dependency names from Validate. Dependencies listed as required in Validate (Go) or validate_config (Python) must match actual resource names in the machine config. If the name is wrong, viam-server waits for a resource that will never exist, and your resource will not start. Use optional dependencies for resources that improve functionality but aren’t strictly needed.

Module protocol

Modules communicate with viam-server over gRPC using the ModuleService defined in proto/viam/module/v1/module.proto:

All RPCs are initiated by viam-server and handled by the module:

The module also connects back to the parent viam-server to access other resources (dependencies) on the machine.

meta.json schema

Every module has a meta.json file that describes the module to the registry. The full schema is available at https://dl.viam.dev/module.schema.json.

{
  "$schema": "https://dl.viam.dev/module.schema.json",
  "module_id": "my-org:my-module",
  "visibility": "private",
  "url": "https://github.com/my-org/my-module",
  "description": "Short description of the module.",
  "models": [\
    {\
      "api": "rdk:component:sensor",\
      "model": "my-org:my-module:my-sensor",\
      "short_description": "A short description of this model.",\
      "markdown_link": "README.md#my-sensor"\
    }\
  ],
  "entrypoint": "run.sh",
  "first_run": "setup.sh",
  "markdown_link": "README.md",
  "build": {
    "setup": "./setup.sh",
    "build": "./build.sh",
    "path": "module.tar.gz",
    "arch": ["linux/amd64", "linux/arm64"]
  }
}

Applications

If your module provides a Viam application, define it in the applications array in meta.json.

Each application object has the following properties:

For example, if your organization namespace is acme and your application name is dashboard, your application is accessible at:

https://dashboard_acme.viamapps.com

Organization namespace

When uploading modules to the Viam Registry, you must set a unique namespace for your organization.

Create a namespace: In the Viam app, click your organization name in the top navigation bar, then click Settings, then click Set a public namespace. Enter a name and click Set namespace. Namespaces may only contain letters, numbers, and hyphens (-).

Rename a namespace:

1. Navigate to your organization settings page.
2. Click Rename next to your current namespace.
3. Enter the new namespace name and click Rename.
4. Update the module code and meta.json for each module your organization owns to reflect the new namespace.
5. (Recommended) Update the model field in machine configurations that reference the old namespace. Old references continue to work, but updating avoids confusion.

When you rename a namespace, Viam reserves the old namespace for backwards compatibility: it cannot be reused.

CLI commands

All module CLI commands are under viam module. You must be logged in (viam login) to use commands that interact with the registry.

Create and generate

generate flags: --generate-type (module, app, or module+app), --name, --language (python, go, or cpp), --visibility, --public-namespace, --resource-subtype, --model-name, --register, --app-name, --app-type, --dry-run.

Build

build start flags: --ref (git ref, default: main), --platforms, --token (for private repos), --workdir.

During builds, the environment variables VIAM_BUILD_OS and VIAM_BUILD_ARCH are set to the target platform. See Environment variables.

Upload and update

upload flags: --tags (platform constraints), --force (skip validation), --upload (path to archive).

Development loop

reload flags: --part-id (target machine part), --path (root of git repo to build), --annotation (text note describing the purpose of this reload build), --module (path to meta.json), --model-name (add a resource to config with this model triple), --resource-name (name the resource instance), --id (module ID), --cloud-config (path to viam.json, alternative to --part-id), --workdir (subdirectory containing meta.json).

reload-local flags: --part-id (target machine part), --no-build (skip build), --local (run entrypoint directly on localhost instead of bundling), --module (path to meta.json), --model-name (add a resource to config with this model triple), --name (name the added resource), --resource-name (name the resource instance), --id (module ID, alternative to --name), --cloud-config (path to viam.json, alternative to --part-id), --workdir (subdirectory containing meta.json), --home-dir (remote user’s home directory), --no-progress (hide transfer progress).

Environment variables

Runtime

These environment variables are available inside a running module process (including first-run scripts):

Cloud-connected

When the machine is connected to Viam Cloud, these additional variables are available inside the module process:

Custom environment variables can be added in the module’s machine config under the env field.

Build-time

The following variables are set during cloud builds, not at runtime:

Server-side

Environment variables that control how viam-server starts and manages modules, including VIAM_MODULE_STARTUP_TIMEOUT and VIAM_RESOURCE_CONFIGURATION_TIMEOUT, are documented in viam-server environment variables. viam-server reads these variables itself rather than setting them in a module’s process environment.

Supported platforms

Registry validation rules