# 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://docs.vatio.ai/docs.md

## Documentation

- [Changelog](https://docs.vatio.ai/changelog.md): What changed in Vatio, newest first. One entry per released version, covering the CLI and the platform together.
- [Introduction](https://docs.vatio.ai/index.md): Vatio is a runtime for customer-facing AI agents. Define your agent in vatio.yml, connect the tools and knowledge it needs, and deploy it to web chat, WhatsApp, and Instagram.
- [Quickstart](https://docs.vatio.ai/quickstart.md): Install the CLI, create a workspace, define an agent in vatio.yml, deploy it to a preview and publish it live.
- [Workspace and manifest](https://docs.vatio.ai/manifest.md): A workspace contains one agent and its conversations, contacts, knowledge, secrets and channel connections. Its deployable configuration lives in vatio.yml.
- [Agents](https://docs.vatio.ai/agents.md): The agent block describes an agent — its instructions, name, personality, tools, knowledge and links.
- [Several agents](https://docs.vatio.ai/multi-agent.md): One workspace can run more than one agent, each with its own instructions, tools and knowledge. An ordered entry table decides which one a visitor gets.
- [Tools](https://docs.vatio.ai/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://docs.vatio.ai/knowledge.md): A knowledge base holds entries of Markdown — ones you write, and ones a followed site writes for you and Vatio re-reads every night.
- [Links](https://docs.vatio.ai/links.md): Declare the static destinations an agent may hand out, with placeholders expanded at deploy time.
- [Human in the loop](https://docs.vatio.ai/handoff.md): Two blocks on the agent decide when a person takes over — handoff, which gives it the tool and the conditions, and hours, which says whether anyone is on duty.
- [Safeguards](https://docs.vatio.ai/safeguards.md): Vatio checks draft replies for empty content, generated media and unauthorized links. These checks run for every agent and cannot be disabled.
- [Authentication](https://docs.vatio.ai/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.
- [Sessions and channels](https://docs.vatio.ai/authentication/sessions.md): How a signed token reaches Vatio — rendered onto the widget on the web, or minted from your backend on WhatsApp and other channels with no session.
- [Private tools](https://docs.vatio.ai/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://docs.vatio.ai/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://docs.vatio.ai/channels/widget.md): Embed Vatio chat on your own site with one script tag, themed from the manifest or overridden per page.
- [WhatsApp](https://docs.vatio.ai/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://docs.vatio.ai/channels/instagram.md): Test DMs on Vatio's shared preview account, then connect your own professional account for live DMs.
- [Inbox](https://docs.vatio.ai/channels/inbox.md): Where your team watches every conversation, takes one over from the agent, and hands it back.
- [Deployments](https://docs.vatio.ai/deployments.md): Preview and live environments, named previews for branches, deploying from GitHub, and the workspace secrets tools read.
- [Troubleshooting](https://docs.vatio.ai/troubleshooting.md): Symptoms and what to check, and how to send a bug report or feature request from the CLI.

## CLI

- [CLI](https://docs.vatio.ai/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://docs.vatio.ai/cli/workspace.md): Create a workspace, authorize this machine, read the docs, and check what the CLI thinks it is talking to.
- [Deployments](https://docs.vatio.ai/cli/deploy.md): Validate the workspace, push it to a preview, promote a preview to live, roll back, and compare local files with a deployment.
- [Chats](https://docs.vatio.ai/cli/chat.md): Talk to a deployment as the developer holding the token, read the conversation back, and see every tool call it made.
- [Knowledge bases](https://docs.vatio.ai/cli/knowledge.md): Create bases, write and read entries, follow sites, and re-read them on demand.
- [Secrets](https://docs.vatio.ai/cli/secrets.md): Manage the workspace secrets your tools read as $env.KEY.
- [Publishable tokens and the widget](https://docs.vatio.ai/cli/tokens.md): Mint and revoke the vatpub_ tokens a page carries, and read back the widget configuration the manifest owns.
- [Channels](https://docs.vatio.ai/cli/channels.md): Connect, check and pause your live WhatsApp number and Instagram account, and manage the phones and handles on the shared preview.
- [Authentication keys](https://docs.vatio.ai/cli/auth.md): Generate the keypair that signs the JWT saying who a visitor is.
- [Configuration and uploads](https://docs.vatio.ai/cli/configuration.md): Where the CLI keeps credentials, which environment variables override them, and exactly what a push sends.
- [Connect MCP](https://docs.vatio.ai/cli/mcp.md): Vatio provides an MCP server over stdio. Point any MCP client at `vatio mcp` and it gets docs, deploys, chat, knowledge and channel management.

## SDK

- [Browser SDK](https://docs.vatio.ai/sdk/index.md): Build your own chat UI against @vatio-ai/sdk — a dependency-free npm package with types included.
- [SDK reference](https://docs.vatio.ai/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://docs.vatio.ai/sdk/limits.md): Rate limits the SDK is subject to, what the origin allowlist does and does not prove, and the three reply styles.

## API Reference

- [API Reference](https://docs.vatio.ai/api/index.md): Everything a Vatio developer token opens, over HTTP. Base URL https://vatio.ai, paths relative to /api/v1/:slug.
- [Errors](https://docs.vatio.ai/api/errors.md): The shapes a Vatio API error takes, what each status code means, and which field carries the reason.
- [Device authorization](https://docs.vatio.ai/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://docs.vatio.ai/api/deployments.md): Validate a file bundle, deploy it to a preview, publish it live, roll back, and read deployment history over HTTP.
- [Secrets API](https://docs.vatio.ai/api/secrets.md): List, set and remove the workspace secrets tools read as $env.KEY. Values are write-only.
- [Knowledge bases API](https://docs.vatio.ai/api/knowledge.md): Create bases, write and read entries, follow sites and queue re-crawls over HTTP.
- [Publishable tokens API](https://docs.vatio.ai/api/tokens.md): Mint and revoke the vatpub_ tokens a page carries, and read the widget configuration the manifest owns.
- [Channels API](https://docs.vatio.ai/api/channels.md): WhatsApp and Instagram connections, and the shared-preview phone and account registrations, over HTTP.
- [Chats API](https://docs.vatio.ai/api/chats.md): Start, read and delete your own developer conversations. Not a way to impersonate a customer.
- [Phone verification API](https://docs.vatio.ai/api/phone-verification.md): Verify a phone number through WhatsApp OTP from your own backend. No agent deployment required.