Schedule automated jobs on machines

Viam’s machine job scheduler allows you to configure automated jobs that run on your machines at specified intervals. This enables you to automate routine tasks such as data collection, sensor readings, maintenance operations, and system checks.

The job scheduler is built into viam-server and executes configured jobs according to their specified schedules. Each job targets a specific resource on your machine and calls a designated method at the scheduled intervals.

Configure a job

{
  "components": [ ... ],
  "services": [ ... ],
  "jobs": [
    {
      "name": "hourly-job",
      "schedule": "0 * * * *",
      "resource": "<resource-name>",
      "method": "<method-name>"
    },
    {
      "name": "daily-job",
      "schedule": "0 8 * * *",
      "resource": "<resource-name>",
      "method": "<method-name>"
    },
    {
      "name": "periodic-job",
      "schedule": "15m",
      "resource": "<resource-name>",
      "method": "<method-name>"
    },
    {
      "name": "do-command-job",
      "schedule": "0 2 * * 0",
      "resource": "<resource-name>",
      "method": "DoCommand",
      "command": {
        "key": "calibrate",
        "mode": "full"
      }
    }
  ]
}

{
  "components": [
    {
      "name": "temp-sensor",
      "model": "fake",
      "type": "sensor"
    },
    {
      "name": "camera1",
      "model": "webcam",
      "type": "camera"
    }
  ],
  "services": [
    {
      "name": "data_manager",
      "type": "data_manager"
    }
  ],
  "jobs": [
    {
      "name": "hourly-sensor-reading",
      "schedule": "0 * * * *",
      "resource": "temp-sensor",
      "method": "GetReadings"
    },
    {
      "name": "daily-camera-capture",
      "schedule": "0 8 * * *",
      "resource": "camera1",
      "method": "GetImage"
    },
    {
      "name": "periodic-sync",
      "schedule": "15m",
      "resource": "data_manager",
      "method": "Sync"
    },
    {
      "name": "custom-maintenance",
      "schedule": "0 2 * * 0",
      "resource": "temp-sensor",
      "method": "DoCommand",
      "command": {
        "action": "calibrate",
        "mode": "full"
      }
    }
  ]
}

Job configuration

Jobs are configured as part of your machine’s configuration. Each job requires the following parameters:

ParameterTypeRequiredDescription
namestringRequiredUnique identifier for the job within the machine.
schedulestringRequiredSchedule specification using unix-cron format or Golang duration. Accepts
  • Unix-cron expressions for time-based scheduling:
    • "0 */6 * * *" - Every 6 hours
    • "0 0 * * 0" - Every Sunday at midnight
    • "*/15 * * * *" - Every 15 minutes
    • "0 9 * * 1-5" - Every weekday at 9 AM
  • Golang duration strings for interval-based scheduling:
    • "5m" - Every 5 minutes
    • "1h" - Every hour
    • "30s" - Every 30 seconds
    • "24h" - Every 24 hours
Job schedules are evaluated in the machine’s local timezone.
resourcestringRequiredName of the target resource (component or service).
methodstringRequiredgRPC method to call on the target resource.
commandobjectOptionalCommand parameters for DoCommand operations.

Monitoring and troubleshooting

Monitor job execution through viam-server logs. Look for rdk.job_manager:

8/19/2025, 7:38:59 PM info rdk.job_manager.periodic-job   jobmanager/jobmanager.go:160   Job succeeded   response map[action:true]
8/19/2025, 7:38:59 PM info rdk.job_manager.periodic-job   jobmanager/jobmanager.go:155   Job triggered
8/19/2025, 7:51:33 PM warn rdk.job_manager.periodic-job   jobmanager/jobmanager.go:151   Could not get resource   error could not find the resource for name generic-2

Limitations

  • There is no timeout on job’s invocations of gRPC requests.
  • Jobs only run when viam-server is running.
  • If a unix-cron job is scheduled to start but a previous invocation is still running, the job will be skipped. The job will next run once the previous invocation has finished running and the next scheduled time is reached.
  • If a Golang duration job is scheduled to run but a previous invocation is still running, the next invocation will not run until the previous invocation finishes, at which point it will run immediately.
  • Jobs run locally on each machine and are not coordinated across multiple machines.
  • Job execution depends on viam-server running.
  • Failed jobs do not retry.

Previous

Deploy software

Next

Update software