# An AI agent for the app you're building

Vatio gives the app you're building with a coding agent — Claude Code, Cursor
or Codex, live or still in progress — an agent that knows the app and its
users. Your coding agent builds and tests it from your project through the
Vatio MCP; Vatio holds it and runs the conversations with visitor identity,
access controls, human handoff and tested changes.

There are no configuration files to keep in your repository: the agent lives
on Vatio. You decide what it may do. Your team has every change at once, and
your users get it once the tests that pass today pass on it.

## Get started

Two steps, from your app's project.

1. **Connect the Vatio MCP**, `https://vatio.ai/mcp`: the tools your coding
   agent builds and tests the agent with. In Claude Code, the next
   step adds it for you. In Cursor, Codex, claude.ai, ChatGPT or any other MCP
   client, add it as [Vatio in Claude and ChatGPT](https://vatio.ai/docs/mcp) says.
2. **Install the skills and run `/vatio-init`:**

   ```bash
   npx @vatio-ai/skills
   ```

   It copies the Vatio skills into the project and adds the MCP to its
   `.mcp.json`. Open Claude Code there, approve the **vatio** server it asks
   about, sign in to Vatio when it asks (or run `/mcp`), and run:

   ```text
   /vatio-init
   ```

   In Cursor, Codex or another coding agent, ask it to use vatio-init.

`vatio-init` reads your app, asks only what the code cannot answer, builds the
agent, writes the tests it must pass, puts it in your app and gives you a
link to try it. Signing in, with email, Google or GitHub, creates your
account; [the inbox](https://inbox.vatio.ai) is where the agent is tried,
connected and supervised. Every change after that reaches your users once its
tests pass ([Deployments](https://vatio.ai/docs/deployments)).
You need Node.js 20 or newer for the skills.

No app yet, or no code at hand: add the MCP as a connector in Claude, ChatGPT
or Cursor and ask for the agent you want, then try it in the inbox's
**Try the agent**.

In Claude Code you can also [install the skills as a plugin](https://vatio.ai/docs/integrations/claude-code),
which brings the MCP with it and keeps them up to date on its own.

- [The skills in your coding agent](https://vatio.ai/docs/integrations/claude-code) — Build with /vatio-init. Improve with /vatio-improve.
- [Supervise conversations](https://vatio.ai/docs/channels/inbox) — Read replies, take over and report what should have happened.
- [Your daily improvement routine](https://vatio.ai/docs/improve) — Run /vatio-improve; Vatio tests every fix before your users get it.

## Improve from real conversations

Report a wrong reply in the inbox and say what should have happened. Then run
`/vatio-improve` in your coding agent. It fixes the cause through the MCP (or
in your backend, when that is where it is). Your team has each fix at once,
and Vatio replays the reported cases and your tests against it: your users
get it once every test that passes today passes on it, and a test it breaks
holds it back from them ([Deployments](https://vatio.ai/docs/deployments)).

The daily email brings the command when new reports arrive. This is an owner-led
routine; Vatio does not rewrite your agent by itself. Tests cover
reported cases, not every possible conversation.

## Where to do what

- **Your coding agent**, through the [MCP](https://vatio.ai/docs/mcp): create the agent, change its
  behavior and connections, and write and run its tests.
- **Inbox** ([inbox.vatio.ai](https://inbox.vatio.ai)): follow conversations,
  reply as a person, report mistakes and read the knowledge. Whoever builds
  the agent also finds there **Try the agent** (talk to the newest version on
  the web, WhatsApp or Instagram) and the team's conversations, marked
  **Team** among the customers' in Conversations; where the newest change stands, and
  **Undo the last change**, in **Continuous improvement**; the agent itself in
  **Agent** (who it is, what it was told, what it knows and its tools, read-only);
  under **Channels**, **WhatsApp**, **Instagram**, **Web chat** (the widget and the
  business's name and brand) and **Integrations** (the SDKs); **API keys**, **Webhooks**, **Secrets**,
  and, for the owner, **Team** and **Security**. Supervisors and viewers get the conversations,
  improvement, analytics and knowledge sections; [Teams](https://vatio.ai/docs/team) has
  who sees what.

## Technical reference

The pages below are the contract your coding agent works from: the agent,
tools, knowledge, authentication, channels and APIs, each changed through the
[MCP](https://vatio.ai/docs/mcp)'s tools. The [quickstart](https://vatio.ai/docs/quickstart) walks through those tools
by hand. A team that keeps its agent as files in a repository (`vatio.yml`,
deployed with `vatio push`) uses the [CLI](https://vatio.ai/docs/cli/) and the
[manifest](https://vatio.ai/docs/manifest); commands written as `vatio` assume a global CLI
install, and `npx @vatio-ai/cli@latest` works in their place.

## Build

- [The MCP](https://vatio.ai/docs/mcp) — Every tool your coding agent builds and tests the agent with.
- [Tools](https://vatio.ai/docs/tools) — Give the agent your API. One HTTP request, described in YAML.
- [Knowledge](https://vatio.ai/docs/knowledge) — Entries your coding agent writes, versioned, and tested with every change.
- [Authentication](https://vatio.ai/docs/authentication/) — You sign a JWT saying who the visitor is; Vatio verifies it and never mints one.

## Connect

- [Web widget](https://vatio.ai/docs/channels/widget) — One script tag, themed from the inbox or per page.
- [WhatsApp](https://vatio.ai/docs/channels/whatsapp) — Test on the shared number in a minute; connect your own for your customers.
- [Instagram](https://vatio.ai/docs/channels/instagram) — Answer DMs with the same agent, on a professional account.
- [Browser SDK](https://vatio.ai/docs/sdk/) — Build your own chat UI against a dependency-free npm package.
- [iOS SDK](https://vatio.ai/docs/sdk/ios) — The conversation as observable state in a Swift package; the UI is yours.
- [Android SDK](https://vatio.ai/docs/sdk/android) — The conversation as StateFlows in a Kotlin library; the UI is yours.
- [Flutter SDK](https://vatio.ai/docs/sdk/flutter) — The conversation as a ChangeNotifier in a Dart package; the UI is yours.
- [Ruby gem](https://vatio.ai/docs/sdk/ruby) — Sign your users in and message them first from a Ruby or Rails backend.

## Source code

Everything you install is a public repository under
[github.com/vatio-ai](https://github.com/vatio-ai). Read the source there, and
open an issue in the repository of the package that misbehaved.

| Repository | What it is | Install |
|---|---|---|
| [vatio-ai/cli](https://github.com/vatio-ai/cli) | [The CLI](https://vatio.ai/docs/cli/) | `npx @vatio-ai/cli` |
| [vatio-ai/skills](https://github.com/vatio-ai/skills) | [Skills for coding agents](https://vatio.ai/docs/integrations/claude-code) | `npx @vatio-ai/skills` |
| [vatio-ai/widget](https://github.com/vatio-ai/widget) | [The web widget](https://vatio.ai/docs/channels/widget) | `npm install @vatio-ai/widget` |
| [vatio-ai/sdk](https://github.com/vatio-ai/sdk) | [Browser SDK](https://vatio.ai/docs/sdk/) | `npm install @vatio-ai/sdk` |
| [vatio-ai/ios](https://github.com/vatio-ai/ios) | [iOS SDK](https://vatio.ai/docs/sdk/ios) | Swift Package Manager |
| [vatio-ai/android](https://github.com/vatio-ai/android) | [Android SDK](https://vatio.ai/docs/sdk/android) | `com.github.vatio-ai:android` on JitPack |
| [vatio-ai/flutter](https://github.com/vatio-ai/flutter) | [Flutter SDK](https://vatio.ai/docs/sdk/flutter) | `flutter pub add vatio` from pub.dev |
| [vatio-ai/ruby](https://github.com/vatio-ai/ruby) | [Ruby gem](https://vatio.ai/docs/sdk/ruby) | `gem "vatio-sdk"` from RubyGems |

The widget, the skills and the gem are MIT. The CLI and the SDKs are
source-available under the license in each repository.

## For coding agents

This entire site is also one Markdown file: [`/docs.md`](https://vatio.ai/docs/docs.md), or
`vatio docs` from the terminal. Every individual page is available as Markdown
at its own path plus `.md` — [`/mcp.md`](https://vatio.ai/docs/mcp.md), for instance —
so an agent can read the one page it needs rather than the whole contract. The
index of them is [`/llms.txt`](https://vatio.ai/docs/llms.txt).

```bash
vatio docs --save vatio-docs.md
vatio docs tools                  # one page
vatio docs search request.requires
```

That fetches the documentation from your configured Vatio host. Run it again to
refresh the file; the CLI keeps no offline cache. `vatio docs PAGE` prints one
page, and `vatio docs search TERM` the sections that mention `TERM`, with
their page and the lines around each match; see
[Reading the docs](https://vatio.ai/docs/cli/workspace#reading-the-docs).

You build, test and change the agent with the Vatio [MCP](https://vatio.ai/docs/mcp)'s tools
(`list_workspaces`, `update_agent`, `chat_with_agent`, `add_test`…). Vatio
holds the agent: nothing about it goes into the app's repository except what
puts it in the app, and any endpoint of the app it calls. If you do not have
the tools, connect `https://vatio.ai/mcp` first ([Connect](https://vatio.ai/docs/mcp#connect)); a
person who must sign in does that step themselves. A person starts with
`npx @vatio-ai/skills` and `/vatio-init` ([Get started](#get-started)).
However they asked you, the procedures below are the ones `vatio-init`
follows. If the developer was added to someone else's workspace, start with
[Joining an existing workspace](#joining-an-existing-workspace).

### Starting a new agent

If you are a coding agent asked to build someone a Vatio agent, this is the
order that works:

1. **Install the skills.** Unless `.agents/skills/vatio-init` is already
   there, run `npx @vatio-ai/skills` from the root of the project. It copies
   the Vatio skills into `.agents/skills/` and `.claude/skills/`, so this
   procedure and the one for improving the agent are in the repository for
   the next session, whichever coding agent runs it, and adds the MCP to the
   project's `.mcp.json`. In Claude Code a server added during a session
   loads when it starts again.
2. **Look before creating.** `list_workspaces` lists every workspace the
   person reaches. Read the app too: what it does and for whom, the API an
   agent could call, how its users sign in, the docs or policies it could
   read, and whether Vatio is already in it (`cdn.vatio.ai`,
   `@vatio-ai/widget`, `data-workspace`, an SDK's setup) or a `vatio.yml` is
   (`git ls-files '*vatio.yml'`). If the app already has a workspace, follow
   [Joining an existing workspace](#joining-an-existing-workspace) instead.
   Tell the person you work for what you found and what you recommend the
   agent do before writing anything.
3. **Ask the owner, briefly, what the code does not answer.** What the business does
   and who writes in; what the agent must never say or promise; when it has to
   hand the conversation to a person; and which of their systems it should
   read from (an API, a calendar, a catalog) — those become
   [tools](https://vatio.ai/docs/tools). Do not invent business facts you were not given.
4. **Create the workspace and the agent.** `create_workspace`, then
   `update_agent` with `instructions` from the answers, the never-say rules as
   explicit rules. Anything long the agent should read rather than memorize is
   [knowledge](https://vatio.ai/docs/knowledge): `create_knowledge_base`, `write_knowledge_entry`,
   and the base in the agent's `knowledge`.
5. **Connect the app's backend.** `set_secret` for its URL and credential,
   from the app's `.env` and never repeated back; `set_backend` with a
   `base_url` and `headers` that read them as `$env.KEY`; one `set_tool` per
   endpoint ([Tools](https://vatio.ai/docs/tools)), and one that [asks for a person](https://vatio.ai/docs/handoff) for
   the human cases. A tool that writes needs a test value (`set_secret` with
   `tests: true`) so tests never write to production.
6. **Try it.** `chat_with_agent` a few representative conversations —
   including one that should hand off and one that asks for something it must
   not say — and read the tools each reply called.
7. **Write the tests.** `add_test` with a `question` and what the answer
   `should` do, for each question that matters: three or four, the hand-off
   and a must-not-say included. Each answers at once with a `chat_id`;
   `get_test` with it, a few seconds later, shows whether it passes now.
   `run_tests` replays them all, and from then on a change that breaks one
   that passes is held back from everyone ([Testing](https://vatio.ai/docs/improve)).
8. **Hand over the link.** `get_status` gives `try_it`: the inbox with
   **Try the agent** open, with a conversation right in the inbox, WhatsApp and Instagram. Report what
   you tried, how it answered and the tests.
9. **Put it in the app.** Once they have tried it, add it where the app's
   users will talk to it — the web widget, or the iOS, Android or Flutter SDK —
   and follow [Putting the agent in the app](#putting-the-agent-in-the-app).
10. **Say how changes reach people.** Tell the person you work for that
    there is nothing to publish: every change reaches the team at once and
    the app's users once the tests that pass today pass on it, a few minutes
    later. A test it breaks holds it back from them and emails whoever made
    it; `get_status` says where the newest change stands, and `rollback`
    undoes the last one ([Deployments](https://vatio.ai/docs/deployments)).
11. **Tell us how it went.** Before you finish, send the Vatio team a few
    sentences with the MCP's `send_feedback`: which step of setting up the
    agent took the most work, and why (a tool that refused something, an error
    that left you guessing, docs that were missing). Do it even when it all
    went smoothly, with no secrets or personal data. It is read by the people
    who write both the tools and these docs.

### Putting the agent in the app

If you are a coding agent asked to put a workspace's agent where the app's
users can talk to it, this is the order that works. It usually follows
[Starting a new agent](#starting-a-new-agent), once the person has tried the
agent.

1. **Find where it goes.** Read the project: a web app, an iOS app (an
   `.xcodeproj` or `Package.swift`), an Android app (a Gradle module with
   `com.android.application`), a Flutter app (a `pubspec.yaml` that depends on
   `flutter`), or several. For React Native or Expo there is no Vatio SDK yet:
   say so, and send `vatio feedback` that one was asked for, rather than
   improvising one.
2. **One publishable key.** `get_status` returns it in `put_in_the_app`:
   `publishable_key`, and `widget`, the widget's script tag with it. The same
   key serves development and release builds alike, from any site or app, so
   there are no origins to collect or set
   ([Publishable keys](https://vatio.ai/docs/channels/widget#publishable-keys)). Make no key of
   your own. A page served from the developer's own machine (`localhost`, a
   private address, a `.local` or `.test` name) talks to the newest version,
   the one the team has, and its conversations are the team's; everywhere
   else, the app talks to the version everyone has, a mobile app's
   development builds included.

   A `vatpub_` key is meant to ship in page source and inside an app, so put
   it in the app's configuration (an environment variable, a build setting).
   Never a `vat_` developer token.
3. **Add it.**
   - **Web:** the [widget](https://vatio.ai/docs/channels/widget), once for the whole app: its
     script tag in the layout every page shares, or `@vatio-ai/widget`
     mounted from the app's root (in React, in an effect that returns
     `widget.unmount`). Build your own interface with the
     [browser SDK](https://vatio.ai/docs/sdk/) only when asked to.
   - **iOS:** the Swift package [`vatio-ai/ios`](https://github.com/vatio-ai/ios)
     ([iOS SDK](https://vatio.ai/docs/sdk/ios)). It has no UI, so write the chat screen in the
     app's own style, starting from `Example/VatioExample/Views.swift` in
     that repository: the messages, a composer, the typing indicator, and
     `chat.resume()` when the screen appears. For a whole app (the
     conversation list, photos, voice notes, the feedback card, settings),
     [Vatio Chat for iOS](https://github.com/vatio-ai/vatio-chat-ios) has each in a file of its own.
   - **Android:** [`vatio-ai/android`](https://github.com/vatio-ai/android)
     from JitPack ([Android SDK](https://vatio.ai/docs/sdk/android)). Keep the chat in a
     `ViewModel` and close it in `onCleared()`, and write the screen starting
     from `example/src/main/kotlin/ai/vatio/example/Views.kt` in that
     repository. [Vatio Chat for Android](https://github.com/vatio-ai/vatio-chat-android) is a whole app on it, in
     Compose.
   - **Flutter:** the `vatio` package from pub.dev, with `flutter pub add vatio`
     ([Flutter SDK](https://vatio.ai/docs/sdk/flutter)). Keep the `VatioChat` with the app's
     long-lived services and `dispose()` it with them, and write the screen
     starting from `example/lib/views.dart` in
     [`vatio-ai/flutter`](https://github.com/vatio-ai/flutter). An Android
     release build needs the `INTERNET` permission in the main manifest.
4. **Say who is signed in**, when the agent must know (their orders, their
   account). Signed-out users get no token, and the agent answers them with
   its public tools. Make a keypair (`openssl genpkey -algorithm RSA -pkeyopt
   rsa_keygen_bits:2048 -out vatio-private.pem`, then `openssl pkey -in
   vatio-private.pem -pubout`) and `set_auth` with the public key. The app's
   backend signs a short-lived token for the signed-in user with the private
   key ([Authentication](https://vatio.ai/docs/authentication/)), kept in its secrets and never
   committed. The web renders it onto the widget as `data-visitor-token` or
   passes it to `identify()` ([Sessions and channels](https://vatio.ai/docs/authentication/sessions));
   a mobile app gets it from an endpoint of that backend that requires the
   app's own session, and passes it to `VatioChat` as `visitorToken`. The
   private key never goes into the app.

   A different user is a different conversation: create a new chat when
   someone signs in or out.
5. **Try it in a development build.** Run the app, open the chat, and ask
   something its knowledge answers and, signed in as a test user, something
   one of its private tools answers. The key works from any site or app;
   `origin_not_allowed` means the call sent no origin at all, while a browser
   and Vatio's SDKs always send one
   ([Publishable keys](https://vatio.ai/docs/channels/widget#publishable-keys)).
6. **Hand it over.** Say what you added and where the key lives. The app,
   once deployed, answers with the version everyone has, and each change
   reaches it once the tests that pass today pass on it.

### Joining an existing workspace

If you are a coding agent asked to get a developer working on a workspace
someone else added them to ([Teams](https://vatio.ai/docs/team)), this is the order that works:

1. **Sign in as the invited address.** Connect the MCP signed in with the
   email they were invited with: `list_workspaces` then shows the workspace
   and their role. Any other address is a different account that does not
   reach it.
2. **Explain the agent.** `get_agent` (what it is for, its tools, its
   knowledge, when it hands off) and `get_status` (where the newest change
   stands). `list_reports` says what supervisors have reported and which tests
   fail, and `get_tool_health` which tool calls are failing. Recommend from
   what you find: the reports are work for
   [Improve your agent from flags](https://vatio.ai/docs/improve), and a failing tool is a fix in
   the backend it calls.
3. **Change it like the rest of the team.** Every change builds on the
   newest version, which the whole workspace shares: the team has it at once,
   and everyone once the tests that pass today pass on it
   ([Deployments](https://vatio.ai/docs/deployments)). `run_tests` shows how the newest version
   does on every report and test.
4. **A `vatio.yml` in the repository** means the team kept the agent as files
   and deployed it with `vatio push`. The agent on Vatio is the one that
   counts. Changing it through the MCP is fine: their next `vatio push` is
   refused until `vatio pull` brings your changes into the files
   ([Edits made outside your files](https://vatio.ai/docs/cli/deploy#edits-made-outside-your-files)).
   If nobody needs the files any more, recommend removing `vatio.yml`,
   `tools/` and `identity.pub` from the repository, and do it only with their
   yes.

Once supervisors use it, `list_reports` is where improving it starts — see
[Improve your agent from flags](https://vatio.ai/docs/improve). The
[`vatio-ai/skills`](https://github.com/vatio-ai/skills) skills from step 1
carry both starting points and sharing a session, as a Claude Code plugin or,
for any coding agent, with `npx @vatio-ai/skills`
([Claude Code](https://vatio.ai/docs/integrations/claude-code)).

Release notes are in the [changelog](https://vatio.ai/docs/changelog).