# 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.

```bash
vatio push
vatio status
vatio diff --env live
vatio publish
vatio rollback
```

`push` 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](#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](https://vatio.ai/docs/knowledge#preview-and-live)
entries it changed and the [secret](#secrets) 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](https://vatio.ai/docs/channels/inbox#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](https://vatio.ai/docs/improve) resolves as soon as `vatio eval` passes 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](https://vatio.ai/docs/improve#what-publish-checks).

## 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

```bash
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_KEY
```

Keys 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:

```bash
vatio secrets set ACME_API https://staging.acme.com --env preview
```

A **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.

```bash
vatio secrets set ACME_API https://staging.acme.com --tests
```

A 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](https://vatio.ai/docs/improve#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.