Configuration

Complete reference for telemetry.config.json.

Overview

Every TelemetryOS application must include a telemetry.config.json file at the root of the project. This file defines your application's metadata, mount points, workers, containers, and development settings.

Required Fields

{
  "name": "my-application",
  "version": "1.0.0",
  "mountPoints": {
    "render": "/render"
  }
}

name

Type: string (required)

Unique identifier for your application. Must match the value passed to configure() in your SDK initialization.

// telemetry.config.json
{
  "name": "weather-widget"
}

// Your code
configure('weather-widget');  // Must match

Rules:

Use lowercase with hyphens
No spaces or special characters
Must be unique within your account
Cannot be changed after deployment

version

Type: string (required)

Application version following semantic versioning (semver).

{
  "version": "1.2.3"
}

Format: MAJOR.MINOR.PATCH

MAJOR - Breaking changes
MINOR - New features (backward compatible)
PATCH - Bug fixes

mountPoints

Type: object (required)

Defines the URL paths for your application components. At minimum, must include render.

{
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"
  }
}

Standard Mount Points:

Mount Point	Required	Description
`render`	Yes	Content displayed on devices
`settings`	No	Configuration UI in admin portal

Path Format:

Must start with /
Can be any valid URL path
Typically /render and /settings

Optional Fields

displayName

Type: string (optional)

Human-readable name shown in the admin interface.

{
  "displayName": "Weather Widget"
}

If not provided, name is used instead.

description

Type: string (optional)

Description of your application shown in the admin interface.

{
  "description": "Display weather forecasts for configured cities"
}

workers

Type: array (optional)

Background scripts that run continuously, even when application isn't visible.

{
  "workers": [
    {
      "script": "./workers/background-sync.js"
    },
    {
      "script": "./workers/monitor.js"
    }
  ]
}

Worker Object:

Field	Type	Description
`script`	string	Path to worker script (relative to app root)

Multiple Workers:

Each runs independently
All have SDK access
Share storage with main application

containers

Type: array (optional)

Docker containers to run alongside your application on devices.

{
  "containers": [
    {
      "name": "api-server",
      "image": "myapp/backend:latest",
      "port": 3000
    },
    {
      "name": "redis",
      "image": "redis:7-alpine",
      "port": 6379
    }
  ]
}

Container Object:

Field	Type	Description
`name`	string	Container hostname (lowercase, no spaces)
`image`	string	Docker image name and tag
`port`	number	Internal port container listens on

Important:

Containers only run on physical devices (not in admin portal)
Container name becomes hostname: http://container-name
Images must be publicly accessible or pre-loaded

devServer

Type: object (optional but recommended)

Configuration for local development with tos serve.

{
  "devServer": {
    "runCommand": "vite --port 3000",
    "url": "http://localhost:3000"
  }
}

devServer Object:

Field	Type	Description
`runCommand`	string	Command to start local dev server
`url`	string	URL where dev server will be accessible

Common Commands:

// Vite
"runCommand": "vite --port 3000"

// Webpack Dev Server
"runCommand": "webpack serve --port 3000"

// Create React App
"runCommand": "react-scripts start"

// Next.js
"runCommand": "next dev --port 3000"

Complete Example

{
  "name": "restaurant-menu-board",
  "version": "2.1.0",
  "displayName": "Restaurant Menu Board",
  "description": "Dynamic digital menu board with real-time price updates and promotional content",

  "mountPoints": {
    "render": "/render",
    "settings": "/settings"
  },

  "workers": [
    {
      "script": "./workers/price-sync.js"
    },
    {
      "script": "./workers/inventory-monitor.js"
    }
  ],

  "containers": [
    {
      "name": "menu-api",
      "image": "restaurant/menu-api:v2.1.0",
      "port": 3000
    },
    {
      "name": "redis-cache",
      "image": "redis:7-alpine",
      "port": 6379
    }
  ],

  "devServer": {
    "runCommand": "vite --port 3000",
    "url": "http://localhost:3000"
  }
}

Minimal Example

{
  "name": "simple-clock",
  "version": "1.0.0",
  "mountPoints": {
    "render": "/render"
  }
}

Validation

The TelemetryOS platform validates your configuration on upload:

Required Checks:

✅ name field exists and is valid
✅ version field exists and follows semver
✅ mountPoints.render is defined
✅ Mount point paths start with /
✅ Worker scripts paths are relative
✅ Container names are valid hostnames

Warnings:

⚠️ No settings mount point (app not configurable)
⚠️ Container images may not be accessible
⚠️ Worker scripts not found (checked at build time)

Best Practices

Versioning

// Good - semantic versioning
"version": "1.0.0"
"version": "2.1.3"

// Bad - non-standard formats
"version": "v1.0"
"version": "latest"
"version": "1.0"

Naming

// Good - lowercase with hyphens
"name": "weather-widget"
"name": "inventory-dashboard"

// Bad - spaces, uppercase, special chars
"name": "Weather Widget"
"name": "inventory_dashboard"
"name": "My App!"

Mount Points

// Standard convention
"mountPoints": {
  "render": "/render",
  "settings": "/settings"
}

// Valid but non-standard
"mountPoints": {
  "render": "/",
  "settings": "/config"
}

Container Names

// Good - valid hostnames
"name": "api-server"
"name": "redis"

// Bad - not valid hostnames
"name": "API_Server"
"name": "my cache"

Environment-Specific Config

The config file itself doesn't support environment variables, but your build process can:

package.json:

{
  "scripts": {
    "build:dev": "vite build --mode development",
    "build:prod": "vite build --mode production"
  }
}

Use environment variables in your application code:

const API_URL = import.meta.env.VITE_API_URL;

Deployment Workflow

Build - npm run build creates production files
Config Included - telemetry.config.json must be in build output
Platform Reads - TelemetryOS reads config on application upload
Validation - Platform validates schema and requirements
Deploy - Application becomes available for use

Common Issues

SDK Not Configured

// telemetry.config.json
{
  "name": "weather-app"
}

// ❌ Wrong - mismatch
configure('weather-widget');

// ✅ Correct - matches config
configure('weather-app');

Missing Render Mount Point

// ❌ Invalid - no render
{
  "name": "my-app",
  "version": "1.0.0",
  "mountPoints": {
    "settings": "/settings"
  }
}

// ✅ Valid - has render
{
  "name": "my-app",
  "version": "1.0.0",
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"
  }
}

Invalid Version Format

// ❌ Invalid
"version": "v1.0"
"version": "1"
"version": "1.0"

// ✅ Valid
"version": "1.0.0"
"version": "1.0.1"
"version": "2.1.3"

Schema Reference

interface TelemetryConfig {
  name: string;
  version: string;
  displayName?: string;
  description?: string;
  mountPoints: {
    render: string;
    settings?: string;
    [key: string]: string | undefined;
  };
  workers?: Array<{
    script: string;
  }>;
  containers?: Array<{
    name: string;
    image: string;
    port: number;
  }>;
  devServer?: {
    runCommand: string;
    url: string;
  };
}

Next Steps

Mount Points - Understand render, settings, workers, containers
Quick Start - Create your first application
Local Development - Use tos serve for development