# Vatio

> Vatio is a runtime for customer-facing AI agents: define the agent in `vatio.yml`, connect the tools and knowledge it needs, and deploy it to web chat, WhatsApp, and Instagram.

Everything below as a single file: https://vatio.ai/docs/docs.md

## Documentation

- [Changelog](https://vatio.ai/docs/changelog.md): What changed in Vatio, newest first. One entry per released version, covering the CLI and the platform together.
- [Introduction](https://vatio.ai/docs/index.md): The Vatio plugin for Claude Code builds a conversational agent for your existing app. Vatio runs it, your team supervises it in the inbox, and vatio-improve tests fixes from real conversations.
- [Claude Code](https://vatio.ai/docs/integrations/claude-code.md): Install the Vatio plugin in Claude Code, create an agent for your existing app with vatio-init, and improve it daily from real conversations with vatio-improve.
- [Inbox](https://vatio.ai/docs/channels/inbox.md): Where your team watches every conversation, takes one over from the agent, and hands it back.
- [Your daily improvement routine](https://vatio.ai/docs/improve.md): Supervisors flag wrong replies in the inbox and write what should have happened. Every flag is a test. Your coding agent fixes them, vatio eval proves the fix on preview, and vatio publish refuses a version that breaks what live gets right.
- [Connect Vatio to Claude Code](https://vatio.ai/docs/connect-claude-code.md): Step by step, from a Claude Code routine on claude.ai to an agent that hands work to it from WhatsApp, and tells you in the same chat what Claude did, pull request included.
- [Manual quickstart](https://vatio.ai/docs/quickstart.md): The manual CLI path for creating and publishing a Vatio agent. For the prompt-based path, start with the Claude Code plugin.
- [Teams](https://vatio.ai/docs/team.md): Invite developers, supervisors and read-only viewers to a workspace, what each role can do, the Activity log, and the workspace's two-step verification and retention settings.
- [Workspace and manifest](https://vatio.ai/docs/manifest.md): A workspace contains an agent, conversations, contacts, knowledge, secrets and channel connections. Its deployable configuration lives in vatio.yml.
- [Agents](https://vatio.ai/docs/agents.md): Configure an agent's instructions, personality, tools and knowledge.
- [Tools](https://vatio.ai/docs/tools.md): Tools let the agent call your APIs. A tool is one HTTP request, described in YAML, with placeholders for parameters, secrets, the verified identity and the contact.
- [Knowledge bases](https://vatio.ai/docs/knowledge.md): A knowledge base holds entries of Markdown that you write, and your agent answers from them.
- [Links](https://vatio.ai/docs/links.md): Declare the static destinations an agent may hand out, with placeholders expanded at deploy time.
- [Human in the loop](https://vatio.ai/docs/handoff.md): When a person takes over — handoff on the agent gives it the tool and the conditions, and the business hours a supervisor sets in the inbox say whether anyone is on duty.
- [Safeguards](https://vatio.ai/docs/safeguards.md): Vatio checks draft replies for empty content, generated media and unauthorized links. These checks run for every agent and cannot be disabled.
- [Models and data](https://vatio.ai/docs/model.md): Which models answer for a Vatio agent, how every request reaches them through OpenRouter with zero data retention, and how to ask for a different one.
- [Retention and deletion](https://vatio.ai/docs/data.md): How long Vatio keeps conversations and logs, how a workspace sets its own retention, and how to export or delete everything about one person.
- [Authentication](https://vatio.ai/docs/authentication/index.md): You sign a JWT saying who the visitor is. Vatio verifies it with your public key and passes it to your tools — it can never mint one.
- [Identity flows](https://vatio.ai/docs/authentication/flows.md): A sequence diagram of how Vatio learns who a visitor is on the web, and which key signs each credential.
- [Sessions and channels](https://vatio.ai/docs/authentication/sessions.md): How a signed token reaches Vatio — rendered onto the widget, handed over mid-conversation, or brought back from your sign-in page on WhatsApp and Instagram.
- [Private tools](https://vatio.ai/docs/authentication/tools.md): What a private tool sees of the verified visitor, and the one rule that matters — never take the user's id as a parameter.
- [Channels](https://vatio.ai/docs/channels/index.md): The same agent serves web chat, WhatsApp, Instagram and CLI conversations. What differs between them is delivery, not the agent.
- [Web widget](https://vatio.ai/docs/channels/widget.md): Embed Vatio chat on your own site with one script tag, themed from the inbox or overridden per page.
- [WhatsApp](https://vatio.ai/docs/channels/whatsapp.md): Test on Vatio's shared preview number without a Meta account, then connect your own business number for live traffic.
- [Instagram](https://vatio.ai/docs/channels/instagram.md): Test DMs on Vatio's shared preview account, then connect your own professional account for live DMs.
- [Integrations](https://vatio.ai/docs/integrations/index.md): The services Vatio connects to — Supabase for signed-in users, Claude Code for your coding agent, and WhatsApp and Instagram as channels. One page each.
- [Supabase](https://vatio.ai/docs/integrations/supabase.md): If your users sign in with Supabase Auth, name the project in vatio.yml. The widget picks up their session on its own, WhatsApp and Instagram sign in through your own login page, and your tools read their rows under Row Level Security.
- [Claude Code routines](https://vatio.ai/docs/integrations/claude-routines.md): Give your agent a Claude Code routine as a tool. When someone you trust asks for work on your code, the agent hands the conversation to Claude, which reads it with a server key and tells the agent what came of it.
- [Deployments](https://vatio.ai/docs/deployments.md): Preview and live, draft and published, what vatio publish checks before a version goes live, and the secrets tools read.
- [Troubleshooting](https://vatio.ai/docs/troubleshooting.md): Symptoms and what to check, and where to report a bug or request a feature.

## CLI

- [CLI](https://vatio.ai/docs/cli/index.md): The npm package is @vatio-ai/cli and its installed executable is vatio. Install it globally, or run it through npx.
- [Workspace and account](https://vatio.ai/docs/cli/workspace.md): Create a workspace, authorize this machine, read the docs, and check what the CLI thinks it is talking to.
- [Deployments](https://vatio.ai/docs/cli/deploy.md): Push the workspace to preview, publish it to live, roll back, inspect both environments, and compare local files with a deployment.
- [Chats](https://vatio.ai/docs/cli/chat.md): Talk to a deployment as the developer holding the token, and read any chat back with every tool call it made.
- [Flags, evals and tools](https://vatio.ai/docs/cli/improve.md): Read what supervisors reported and how your tools' backend has been answering as documents for your coding agent, and prove a fix by testing every report against preview before publishing.
- [Knowledge bases](https://vatio.ai/docs/cli/knowledge.md): Create bases, write and read entries on preview or on live, and publish changes.
- [Business](https://vatio.ai/docs/cli/business.md): Read and set the business the agent works for — name, description and opening hours — from a terminal.
- [Secrets](https://vatio.ai/docs/cli/secrets.md): Manage the workspace secrets your tools read as $env.KEY, everywhere or for one environment.
- [Publishable tokens](https://vatio.ai/docs/cli/tokens.md): Mint and revoke the vatpub_ tokens a page carries, and set the origins each one accepts.
- [Server keys](https://vatio.ai/docs/cli/keys.md): Create and revoke the vsk_ keys your backend calls the server API with, such as to have the agent write to a contact first.
- [Templates and webhooks](https://vatio.ai/docs/cli/webhooks.md): Create and list the WhatsApp templates your backend can send, and manage the webhooks Vatio calls with what happened to each message.
- [Routines](https://vatio.ai/docs/cli/routines.md): Connect a Claude Code routine your agent can hand work to, say whose conversations may use it, and see each run with the link to its Claude session.
- [Channels](https://vatio.ai/docs/cli/channels.md): WhatsApp and Instagram are set up in the inbox; vatio whatsapp and vatio instagram print the link to the right page.
- [Authentication keys](https://vatio.ai/docs/cli/auth.md): Generate the keypair that signs the JWT saying who a visitor is.
- [Configuration and uploads](https://vatio.ai/docs/cli/configuration.md): Where the CLI keeps credentials, which environment variables override them, and exactly what a push sends.

## SDK

- [Browser SDK](https://vatio.ai/docs/sdk/index.md): Build your own chat UI against @vatio-ai/sdk — a dependency-free npm package with types included.
- [SDK reference](https://vatio.ai/docs/sdk/reference.md): Every method on Vatio and on a chat, the options Vatio.chat accepts, and what the SDK stores in the browser.
- [Limits and delivery](https://vatio.ai/docs/sdk/limits.md): Rate limits the SDK is subject to, what the origin allowlist does and does not prove, and the three reply styles.
- [iOS SDK](https://vatio.ai/docs/sdk/ios.md): Put a Vatio agent inside your iOS app with a Swift package that gives you the conversation as observable state and leaves the UI to you.
- [Android SDK](https://vatio.ai/docs/sdk/android.md): Put a Vatio agent inside your Android app with a Kotlin library that gives you the conversation as StateFlows and leaves the UI to you.
- [Ruby gem](https://vatio.ai/docs/sdk/ruby.md): vatio-sdk signs and verifies your users' JWT, renders the widget tag, signs WhatsApp and Instagram contacts in, and calls the server API to message them first.

## API Reference

- [API Reference](https://vatio.ai/docs/api/index.md): Everything a Vatio developer token opens, over HTTP. Base URL https://vatio.ai, paths relative to /api/developer/v1/:slug.
- [Errors](https://vatio.ai/docs/api/errors.md): The shapes a Vatio API error takes, what each status code means, and which field carries the reason.
- [Device authorization](https://vatio.ai/docs/api/device-authorization.md): How vatio login works, and how a custom CLI obtains a developer token without a browser of its own.
- [Deployments API](https://vatio.ai/docs/api/deployments.md): Validate a file bundle, deploy it to preview, publish it live once its tests allow it, roll back, and read both environments over HTTP.
- [Secrets API](https://vatio.ai/docs/api/secrets.md): List, set and remove the workspace secrets tools read as $env.KEY, for both environments or for preview only. Values are write-only.
- [Knowledge bases API](https://vatio.ai/docs/api/knowledge.md): Create bases, write and read entries in preview or on live, and publish preview's changes over HTTP.
- [Business API](https://vatio.ai/docs/api/business.md): Read and set the business the agent works for — name, description and opening hours.
- [Publishable tokens API](https://vatio.ai/docs/api/tokens.md): Mint and revoke the vatpub_ tokens a page carries, set the origins each one accepts, and read the widget configuration.
- [Channels API](https://vatio.ai/docs/api/channels.md): WhatsApp and Instagram are set up in the inbox; the API tells you where.
- [Chats API](https://vatio.ai/docs/api/chats.md): Start, read and delete your own developer conversations. Not a way to impersonate a customer.
- [Contacts API](https://vatio.ai/docs/api/contacts.md): Export everything Vatio keeps about one contact, or delete it for good, from your own backend.
- [Messages API](https://vatio.ai/docs/api/messages.md): Send WhatsApp messages from your own backend with a server key. Your own text, a message the agent writes from a brief, or an approved template when the 24-hour window is closed, and signed webhooks for what happened.