meta.json applications schema

Reference for the applications array in meta.json. This array declares one or more Viam Applications that Viam hosts at *.viamapplications.com after you upload the module. For the deployment workflow that produces and uploads meta.json, see Deploy a Viam application.

Complete example

{
  "$schema": "https://dl.viam.dev/module.schema.json",
  "module_id": "acme:dashboard",
  "visibility": "public",
  "applications": [
    {
      "name": "dashboard",
      "type": "multi_machine",
      "entrypoint": "dist/index.html",
      "fragmentIds": ["f0b5a1c2-..."],
      "allowedOrgIds": ["org-id-1", "org-id-2"],
      "logoPath": "static/logo.png",
      "customizations": {
        "machinePicker": {
          "heading": "Select your device",
          "subheading": "Choose a machine to monitor"
        }
      }
    }
  ]
}

Top-level module fields

These fields apply to the whole module, not to a specific application. They are required even when the module’s only purpose is to host an application.

FieldTypeRequiredNotes
$schemastringOptionalCanonical value: "https://dl.viam.dev/module.schema.json". Enables editor schema validation.
module_idstringRequiredFormat: <public-namespace>:<module-name>. Generated by viam module create.
visibilitystringRequiredMust be "public" for modules with applications. Private modules cannot host Viam Applications.
applicationsarrayOptional at the module level, but required if the module has any application contentSee the application object fields below.

Application object fields

Each element of the applications array is an application object with the fields below.

name

Type: string. Required.

The application’s URL segment. Appears in the URL as {name}_{namespace}.viamapplications.com, where {namespace} is your organization’s public namespace.

Constraints:

  • Lowercase alphanumeric characters and hyphens only.
  • Cannot start or end with a hyphen.
  • Must be unique within your organization’s namespace.

Example: "dashboard" produces dashboard_acme.viamapplications.com (if the namespace is acme).

type

Type: string. Required.

Declares how the application accesses machines. Two valid values:

ValueBehavior
"single_machine"The application operates on one machine at a time. Viam injects that machine’s API key and hostname into browser cookies.
"multi_machine"The application can access any machine the logged-in user has permissions for. Viam injects the user’s access token into a browser cookie.

See Authentication for what gets injected and how your app code reads the cookies.

entrypoint

Type: string. Required.

Path to the HTML entry point, relative to the root of the uploaded archive. This is where the hosting platform’s proxy looks for the first HTML file to serve.

Example: "dist/index.html" for a Vite build that outputs to dist/.

The path must match what your build produces. If your bundler writes build/index.html instead of dist/index.html, use "build/index.html".

fragmentIds

Type: array of string. Optional. Single-machine applications only.

List of fragment IDs that restrict which machines appear in the machine picker. A machine is selectable only if its configuration includes every fragment in this list. Use this to scope a single-machine application to machines provisioned for a specific customer or device model.

If the array is empty or omitted, any machine the user has access to is selectable.

allowedOrgIds

Type: array of string. Optional.

List of organization IDs that are allowed to use this application. If set, users who belong to organizations not in this list cannot access the application even if it is public.

If the array is empty or omitted, any organization with access to the application can use it.

logoPath

Type: string. Optional. Single-machine applications only.

Path to a logo image to display on the machine picker screen. Two forms are accepted:

  • A path relative to the uploaded archive root, such as "static/logo.png".
  • An absolute URL, such as "https://example.com/logo.png".

Relative paths are served from the application’s own archive; absolute URLs are loaded from the remote host you specify.

customizations

Type: object. Optional. Currently applies to the machine picker screen only.

Customizes user-facing text on Viam-rendered screens (the machine picker for single-machine applications, and potentially other screens in the future). Currently one subfield:

customizations.machinePicker

Type: object. Optional.

FieldTypeMax lengthNotes
headingstring60 charactersLarge title on the machine picker screen.
subheadingstring256 charactersSupporting text below the heading.

Example:

"customizations": {
  "machinePicker": {
    "heading": "ACME Warehouse Dashboard",
    "subheading": "Select a warehouse rover to monitor and control."
  }
}

Field summary

FieldTypeRequiredSingle-machine onlyNotes
namestringYes—URL segment, lowercase alphanumeric and hyphens
typestringYes—"single_machine" or "multi_machine"
entrypointstringYes—Relative path to HTML file
fragmentIdsarray of stringNoYesFilter machines by fragment
allowedOrgIdsarray of stringNo—Restrict access to specific orgs
logoPathstringNoYesPath or URL for machine picker logo
customizationsobjectNo—Custom headings for Viam-rendered screens

Related