Automator Config V2 Reference

Preview

This format is for Surfmeter Automator 2.0, which is not released yet. For Automator 1.x, see the Automator Config Reference.

The automatorConfig.json file defines when studies run and which options they use. In the dashboard, it is called a schedule config. We recommend editing it in the dashboard. On the probe, the file is stored in ~/.surfmeter/config/.

The file is validated strictly: unknown keys, including unknown options, are errors. The JSON schema is available at https://aveq.info/jsonschema/AutomatorConfigV2.json.

Example File

{
  "$schema": "https://aveq.info/jsonschema/AutomatorConfigV2.json",
  "version": 2,
  "revision": "2026-11-02",
  "globalScheduleSettings": {
    "timeZone": "Europe/Vienna",
    "randomOffset": 5,
    "logFile": "$HOME/.surfmeter/logs/scheduled/studies.log",
    "env": {},
    "options": {
      "globalTimeout": 300
    }
  },
  "studySchedules": [
    {
      "id": "youtube-hourly",
      "description": "YouTube every hour",
      "studyId": "STUDY_YOUTUBE",
      "schedule": "0 * * * *"
    },
    {
      "id": "chain",
      "studyId": ["STUDY_DNS", "STUDY_YOUTUBE"],
      "interval": "30m",
      "options": {
        "sequential": true
      }
    }
  ],
  "updates": {
    "automator": {
      "schedule": "0 3 * * 0"
    }
  }
}

Root Properties

Property	Type	Required	Description
version	number	Yes	Version of the format. Must be 2.
$schema	string	No	URL of the JSON schema of this file, for editors
revision	string	No	A revision for the config file, such as a Git hash or a date
globalScheduleSettings	object	No	Settings for all schedules
studySchedules	array	No	The schedule entries
publicConfigFile	string	No	Path to the public config file to load, relative to the config directory
updates	object	No	Schedules for updates, with the keys automator and config
globalUpdateSettings	object	No	Settings for all updates
registrationKey	string	No	The key used for registering the client, if none is passed to surfmeter auth register

Schedule Entries

Each entry has id and studyId, and exactly one of schedule or interval.

Property	Type	Required	Description
id	string	Yes	Unique ID of the entry (case-insensitive), used by surfmeter daemon run. Up to 64 letters, digits, ., _, and -, starting with a letter or digit. The prefix system. is reserved.
studyId	string or array	Yes	The study from the public config, or a list of studies. A list runs in parallel, or one after the other with options.sequential.
schedule	string	One of	A cron expression with 5 fields, or 6 fields with a leading second, or a macro: @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly. @reboot is not supported. A run that is due while the previous one is still active is skipped.
interval	string	One of	Time between the end of one run and the start of the next: a positive whole number followed by s, m, h or d, such as 30s, 15m, 2h, 1d.
validFrom	string	No	Earliest time this entry can run (inclusive), in ISO 8601 format, such as 2026-03-01T00:00:00Z
validUntil	string	No	Latest time this entry can run (inclusive), in ISO 8601 format. It must not be before validFrom.
description	string	No	A description of the entry
logFile	string	No	Append the output of the runs to this log file, instead of the global one
env	object	No	Environment variables for the run, merged with the global ones. Values may use the same variables as a log file.
options	object	No	Options for the study, merged with the global ones

Parametrized Entries

An entry can choose a study ID at runtime, for example to select a random study. Set these two properties to generate the ID used for the run instead of the fixed studyId:

• studyIdReference: The study ID with variables, such as STUDY_${type}_${n}
• studyIdVariables: The value for each variable

Each variable is one of these:

• { "type": "literal", "value": "VIDEO" }: a fixed value
• { "type": "randomInt", "min": 1, "max": 10 }: a random integer from min to max, both inclusive

{
  "id": "random-video",
  "studyId": "STUDY_VIDEO_1",
  "studyIdReference": "STUDY_VIDEO_${n}",
  "studyIdVariables": {
    "n": { "type": "randomInt", "min": 1, "max": 10 }
  },
  "schedule": "0 * * * *"
}

Global Schedule Settings

Property	Type	Description
timeZone	string	IANA time zone for all cron schedules in this config, including update schedules, such as UTC or Europe/Vienna. Default: the host's time zone.
randomOffset	number	The maximum of a stable random offset per client and entry, in minutes (at least 1/60, and less than 60). For an interval entry, it only delays the first run. Update schedules are not offset.
logFile	string	Append the output of the studies to this log file
env	object	Environment variables for all entries
options	object	Options for all entries

An entry's logFile replaces the global one. Automator merges env and options key by key, with entry values taking priority.

Study Options

The options correspond to the command-line options of surfmeter study start, for example:

{
  "options": {
    "globalTimeout": 300,
    "studyTimeout": 120,
    "sequential": true,
    "enableScreenRecording": true,
    "metadata": { "site": "probe-042" }
  }
}

metadata and extraHeaders can be JSON objects here.

Update Settings

updates.automator schedules updates of Automator, and updates.config schedules updates of the configuration. Without any other setting, both come from the Surfmeter server that the client is registered with.

Property	Type	Description
schedule	string	A cron expression, as for a schedule entry. See below for what happens if it is empty or missing.
url	string	Download the update from this URL instead of the server. An http(s) URL to a file or a Git repository (ending in .git), or a file:// URL.
filename	string	The file name of the download, if the URL does not end in one
auth	object	Basic authentication for url, with the keys username and password. This overrides globalUpdateSettings.auth.
logFile	string	Append the output of the update to this log file

For updates.config, a registered client downloads the configuration every 15 minutes if there is no schedule. An empty schedule turns this off. For updates.automator, the client does not update itself unless a schedule is set.

Global Update Settings

Property	Type	Description
logFile	string	Append the output of the updates to this log file
auth	object	Basic authentication for the url of each update that does not set its own auth

Log Files

Paths for log files and values in env can use these variables: $HOME, $TMP, $USER, and $UID.

Differences to Version 1

• cronSchedule is now schedule.
• cronLogFile is now logFile.
• interval, globalScheduleSettings.timeZone, revision, and updates.*.url are new.
• cmdSuffix, updates.extension, logNetworkRequests, live, and the deprecated options were removed.
• id is enforced as unique, and can only contain the characters listed above.
• validFrom and validUntil are now applied.
• Unknown keys and options are errors.

Automator converts a local V1 file when it reads it. Run surfmeter config migrate to save it in the new format. V1 files downloaded from a server are rejected. See Migrating from Automator 1.x.