Skip to main content
A deployed agent can run on a timer, with no one calling it. Viorant starts each run for you, and you read the results with vio runs and vio logs, as for any other run.
Needs vio 1.0.0 or later. Check with vio --version.
From the shell:
Or as a subcommand, which is what scripts and AI agents use:
Like the other deployment commands, vio schedule takes the short id vio list prints, the full id, a unique prefix of at least six characters, or the deployment’s exact name.

​
Set a schedule

Setting a schedule turns it on. A deployment has one schedule; setting it again replaces it. Leave out --input when you re-time a schedule and its saved input is kept.

​
Run inputs

A scheduled run gets no caller to fill in the agent’s inputs, so an agent that declares required inputs needs them in --input. Pass inline JSON, or keep the payload in a file:
If the agent’s run contract rejects the input, vio names the inputs it requires and shows both forms — for example This agent requires run inputs: topic. Pass them with --input '{"topic": …}' or --input @file.json. In the shell, use --input @input.json. /schedule splits its arguments on spaces and does not handle quotes, so inline JSON works there only when it has no spaces: --input {"topic":"notes"}.

​
See, pause, resume and clear

Showing a schedule prints whether it is on, its interval and time zone, when it runs next, how the last run ended, and how the runs are paid for. on, off and clear take none of the options above except --json.

​
How often you can schedule

Your plan sets the shortest interval between runs: Viorant enforces this, not vio. A schedule more frequent than your plan allows is refused with schedule.interval_below_plan, and the message points at vio upgrade (Your plan). If you move to a plan with a longer minimum, any schedule that is now too frequent pauses, and shows as off (plan limit).

​
What to expect

  • Only a running agent on Viorant Cloud can be scheduled. A stopped or failed deployment is refused with schedule.deployment_not_schedulable.
  • One run at a time. If a run is still going when the next one is due, that turn is skipped.
  • Three failures in a row pause it. After three failed runs in a row the schedule turns itself off, and shows as off (paused after 3 failed runs). Fix the agent, then turn it back on with vio schedule <id> on.
  • Older deployments may need a redeploy. If showing a schedule ends with Redeploy this agent to enable scheduling., run vio redeploy <id> first.

​
What scheduled runs cost

A scheduled run is an ordinary run of the agent:
  • An agent on Viorant credits spends credits from your wallet on every scheduled run. That is why vio help --json marks vio schedule as spendsCredits.
  • An agent on your own provider key runs on that key. vio shows a warning line for these: if the key is revoked, the scheduled runs fail with no one there to see it.

​
Error codes

With --json, a failure is {"error":{"code":"…","message":"…"}}: