#Deployments
#Preview and live
A deployment is a saved configuration snapshot. An environment is a name
pointing to a deployment, and there are two: preview, the next version,
which vatio push updates; and live, what visitors talk to.
vatio push
vatio status
vatio diff --env live
vatio publish
vatio rollbackpush validates and updates preview, and runs no tests; it cannot target
live. publish promotes preview to live together with the knowledge changes
made in it, once its tests allow it (Publishing). The
Publish to live button on the inbox's Test page does the same, through
the same checks; it is not there while preview is already live's version,
when there is nothing to publish.
rollback restores the previous live configuration. diff --env live
compares your local directory with live, so push local edits before
publishing them. --env takes preview or live; staging and sandbox
are other names for preview, and any other name is an error.
Agents, tools, auth configuration, chats, and contacts belong to one environment. Preview also keeps the knowledge entries it changed and the secret values set only for it, and reads everything else from live. Channel connections and brand settings are workspace-wide. The widget's look is not part of a deployment: it is edited in Channels → Web widget in the inbox. Neither is the business — its name, description and opening hours are set on the Business page of the inbox. Both apply to both environments as soon as they are saved.
A deployment that has been live is a snapshot of the whole agent: its
configuration and the version of every knowledge entry it answered from. Live is a pointer to one, and everything that changes what live
answers from leaves a new one behind: a publish, and an edit in the inbox too
(it keeps live's configuration). vatio rollback
moves live to the previous snapshot, configuration and knowledge together;
run it again to go further back. Rollback does not restore secret values or undo actions a tool already performed.
Preview's chats, contacts and tokens exist to try the agent; visitors are on live.
#Draft and published
A workspace is a draft until its first vatio publish, and published
from then on.
- Draft: there is no live yet, so preview is the agent. A
flag resolves as soon as
vatio evalpasses it on preview, and the first publish has no checks to pass. - Published: visitors talk to live. A flag resolves when live passes it, and every publish of a new version goes through the checks below.
#Publishing
Every reply a supervisor flagged with a note is a test, and vatio eval
replays them all against preview, as does Run tests on the inbox's
Test page. Once the workspace is published, vatio publish looks at
preview's current version first:
vatio publish | |
|---|---|
| Already live's version | Nothing moves but preview's knowledge changes, with a notice saying so |
| Not tested | Refused, evals_missing: run vatio eval, then publish |
| Its run is still going | Refused, evals_running: vatio eval waits for it |
| A flag that passes on live fails on it | Refused, evals_regressed, naming each flag. --force publishes anyway |
| Otherwise | Publishes |
What vatio eval found on preview goes live with the version: the flags it
passed are resolved with the version's short sha, and live is not replayed
again. Flags that still fail do not block a publish, so a partial fix can go
live. A workspace with no flags publishes without a test. See
Improve your agent from flags.
#Working with others
There is one preview per workspace. Once the workspace is published, a
vatio push from a different git branch than the one preview's unpublished
version came from is refused with preview_has_unpublished_push: what is on
preview has not gone live yet, and the push would replace it. Publish it
first, or push with --force to replace it. Every version on preview is tried
on the inbox's Test page, open to the workspace's owner and developers.
#Secrets
vatio secrets set ACME_API https://api.acme.com
vatio secrets set ACME_API_KEY YOUR_BACKEND_KEY
vatio secrets list
vatio secrets rm ACME_API_KEYKeys use uppercase letters, digits, and underscores, starting with a letter;
keys starting with VATIO_, and DISPATCHER, are reserved for Vatio.
Tools read values with $env.KEY. Listing returns names, never
values. Changes take effect on subsequent calls without deploying. Rollback
does not restore old values.
A secret applies to both environments. With --env preview it applies to
preview only, replacing the value there — preview's tools can call staging
while live keeps calling production:
vatio secrets set ACME_API https://staging.acme.com --env previewA test value is the one preview uses, and every eval replay, live's included: one staging URL for everything that is not a visitor on live. Without one, the usual value is used.
vatio secrets set ACME_API https://staging.acme.com --testsA tool call from an eval replay also carries an X-Vatio-Test: 1 header, and a
write (any method but GET) whose URL has no test value is not sent: the agent
gets a success instead. See Eval runs.
A tool runs on Vatio's servers, so it cannot reach localhost; to test against
a backend on your machine, expose it through a tunnel and set that URL.
Keep credentials out of manifests, tool source, knowledge, and tool results. The workspace upload includes ordinary files, so keep private signing keys outside that directory.