# Vibetron, for agents

You are an AI agent (or you build one). This file tells you what you can do with Vibetron
without a login: the public API, the public MCP server, and how to write a valid `.tron`.
Human docs: https://vibetron.ai/docs/api-public

## What Vibetron is

- A **tron** is several AI models wired into one machine: agents (each with a model and a
  system prompt, the *soul*), shared memories, arrows between agents, tools.
- A tron is a portable JSON document, the `.tron` file (format `vibetron.tron/2`). Its owner
  imports it in Vibetron, fills in their own provider keys (BYOK), and deploys it.
- You can design and validate a tron from outside, for free, with no account.

- A tron can run behind a **privacy proxy**: personal data (emails, phones, IBANs, Italian tax and VAT codes,
  cards, IPs, declared names) is replaced with placeholders like `[EMAIL_1]` before the model provider sees it,
  and images go to an image proxy its owner hosts. See https://vibetron.ai/docs/privacy-proxy .
  The reference image proxy is open source: https://github.com/aeratic/vibetron-image-redactor . It connects to
  Vibetron itself (`--connect`, a WebSocket to wss://api.vibetron.ai/redactor/connect): one command, no open ports.

## The flow

1. **Search** the catalogue: models, plugins, skills, MCP servers.
2. **Take the ids/refs** from the results. Never invent a model id or a plugin name.
3. **Write the .tron** against the schema, the guide and the examples.
4. **Validate** it (`POST /public/v1/validate`). Fix every `error` issue, re-validate.
5. **Hand the JSON to the owner**, who imports it (that step needs their account).

## Public API

Base: `https://api.vibetron.ai/public/v1`. No auth, CORS open, JSON.
`GET https://api.vibetron.ai/public/v1` returns the index (endpoints, counts, limits, flow).

Lists answer `{ items, next_cursor, total }`. `q` = words in name/description/tags (all must
match, as prefixes). `limit` default 20, max 50. Pass `next_cursor` as `cursor` with the same
`q` and filters. An unknown parameter is a `400`, never ignored.

### Models: `GET /models`, `GET /models/<provider>/<model>`

Filters: `provider`, `kind`, `capability` (`reasoning`, `tool_call`, `attachment`,
`structured_output`, `image_input`, `pdf_input`, `open_weights`). An agent with plugins,
skills with code or MCP servers needs `tool_call`. `id` is the exact `agents[].model.ref`.

```sh
curl "https://api.vibetron.ai/public/v1/models?q=claude&capability=tool_call&limit=2"
```
```json
{"items":[{"id":"anthropic/claude-fable-5","name":"Claude claude-fable-5","provider":"anthropic",
  "kind":"nanobot","capabilities":["reasoning","tool_call","..."],"context_tokens":1000000,
  "price":{"currency":"USD","input_per_mtok":10,"output_per_mtok":50}}, "..."],
 "next_cursor":"eyJvIjoyLCJr...","total":23}
```
```sh
curl "https://api.vibetron.ai/public/v1/models/anthropic/claude-sonnet-5"
```
```json
{"id":"anthropic/claude-sonnet-5","capabilities":["reasoning","tool_call","..."],
 "card":{"output_tokens":128000,"temperature_allowed":false,"...":"..."},
 "settings_offered":{"cache":{"choices":["..."]},"temperature":{"offered":false},"thinking":true},
 "tron_usage":{"model":{"ref":"anthropic/claude-sonnet-5"}}}
```

### Plugins: `GET /plugins`, `GET /plugins/<id>`

Executable tools. Filters: `category`, `provider`, `kind`. `ref` goes in
`agents[].plugins[].ref`; `version` and `sha256` pin a published version. The card lists
`required_keys` (vault entries the owner fills after import). Look up the card by `id`, not by `ref`.

```sh
curl "https://api.vibetron.ai/public/v1/plugins?q=airtable&limit=1"
```
```json
{"items":[{"id":"419c8952-b33f-4782-99e4-e725b348e951","ref":"airtable_base","name":"Airtable",
  "version":2,"sha256":"9e1a1191...","category":"database","provider":"vibetron",
  "description":"Full Airtable interface over the REST + metadata APIs."}],"next_cursor":null,"total":1}
```

### Skills: `GET /skills`, `GET /skills/<id>`

Instructions an agent reads when it needs them. Filters: `category`, `provider`. `ref` goes in
`agents[].skills[].ref`.

```sh
curl "https://api.vibetron.ai/public/v1/skills?limit=1"
```
```json
{"items":[{"id":"78d2f9f2-d84d-4fb3-ab85-c28cc6f6e509","ref":"customer-quotes","version":1,
  "sha256":"238708c0...","category":"productivity","provider":"vibetron","description":"..."}],
 "next_cursor":"...","total":2}
```

### MCP servers: `GET /mcp-servers`, `GET /mcp-servers/<namespace>/<name>`

Curated servers and the official MCP registry. Filters: `category`, `provider`, `kind`
(`curated`, `registry`). `ref` goes in `agents[].mcp_servers[].ref`. The card says how it is
installed (transport, url, headers, which are secret).

```sh
curl "https://api.vibetron.ai/public/v1/mcp-servers?q=context7&limit=1"
curl "https://api.vibetron.ai/public/v1/mcp-servers/io.github.upstash/context7"
```
```json
{"id":"io.github.upstash/context7","ref":"Context7","kind":"registry","version":"4.5.0",
 "install":{"transport":"http","url":"https://mcp.context7.com/mcp","headers":["..."]},"...":"..."}
```

### Writing the file

| Endpoint | Returns |
|---|---|
| `GET /tron-schema` | JSON Schema of `vibetron.tron/2`. Unknown fields are errors. Read it first. |
| `GET /image-redactor-schema` | The contract `vibetron.image-redactor/1.1`, compatible with 1 (JSON Schema and text): implement it to host an image proxy for the privacy proxy, connected to Vibetron or at an https endpoint. |
| `GET /guide` | The writing guide, Markdown: every field, secrets, souls, design choices, checklist. |
| `GET /examples` | Example documents: `{ items: [{ name, tron_name, agents, url }] }`. |
| `GET /examples/<name>` | One example `.tron`. |
| `GET /providers` | Model providers with endpoint host and jurisdiction. |
| `GET /plans` | Public plans (what an owner's plan allows). |

### Validate: `POST /validate`

Body: the `.tron` document itself (not wrapped), at most 256 KB. Creates nothing, calls no model.
Answers `{ ok, issues, report }`: `resolved`, `unresolved` (and why), `needs` (secret slots the
owner fills after import), `not_checked` (what only the owner's account can check).

```sh
curl -X POST https://api.vibetron.ai/public/v1/validate \
  -H "Content-Type: application/json" --data @my.tron.json
```
```json
{"ok":true,"issues":[],
 "report":{"format":"vibetron.tron/2",
  "resolved":{"models":[{"nucleus":"ASSISTANT","model":"anthropic/claude-sonnet-5","by":"ref"}],"...":[]},
  "unresolved":{"models":[],"plugins":[],"...":[]},
  "needs":[{"nucleus":"ASSISTANT","llm":"anthropic","vault_key":"ANTHROPIC"}],
  "not_checked":{"vault_keys":[{"nucleus":"ASSISTANT","vault_key_label":"ANTHROPIC"}],"tron_targets":[]}}}
```

## A minimal complete .tron

Schema: https://api.vibetron.ai/public/v1/tron-schema . This document validates (`ok: true`):

```json
{
  "format": "vibetron.tron/2",
  "name": "SIMPLE_ASSISTANT",
  "memory_mode": "session",
  "agents": [
    {
      "id": "a1",
      "name": "ASSISTANT",
      "model": { "ref": "anthropic/claude-sonnet-5" },
      "soul": "You are a concise assistant. Answer in the language of the question. Never invent figures or sources.",
      "trigger": { "mode": "on_message" },
      "memories": ["m1"],
      "vault_key": { "name": "ANTHROPIC" }
    }
  ],
  "memories": [
    { "id": "m1", "name": "CONVERSATION", "type": "window", "window_size": 20 }
  ]
}
```

References are by name (model `provider/model`, plugin/skill/MCP `ref`). Secrets never go in
the file: only the *names* of vault entries (`vault_key.name`), which the owner fills after import.

## Public MCP server

`POST https://api.vibetron.ai/public/mcp`: streamable HTTP, stateless, **no key**. Same
catalogue and validator as tools:

- `search_models`: search models; each `id` is the `agents[].model.ref`.
- `get_model`: full model card: capabilities, tokens, price, settings, `.tron` snippet.
- `search_plugins`: search public plugins; `ref`, `version`, `sha256`.
- `get_plugin`: plugin card: parameters, `required_keys`, versions, snippet.
- `search_skills`: search public skills.
- `get_skill`: skill card: required keys, compatibility, versions, snippet.
- `search_mcp_servers`: search curated and registry MCP servers.
- `get_mcp_server`: MCP server card: transport, url, headers, where to get a key, snippet.
- `get_tron_schema`: the JSON Schema of `vibetron.tron/2`.
- `get_image_redactor_schema`: the image proxy contract `vibetron.image-redactor/1.1` (compatible with 1).
- `get_guide`: the writing guide (Markdown).
- `list_examples`: example `.tron` documents.
- `get_example`: one example by name.
- `validate_tron`: validate a `.tron` (`{ "tron": { ... } }`), creating nothing.

Add it to a client:

- **Claude**: Settings → Connectors → Add custom connector → `https://api.vibetron.ai/public/mcp`.
- **ChatGPT**: developer mode → add a custom connector with the same URL.
- **Cursor** and any MCP client with a JSON config:

```json
{ "mcpServers": { "vibetron-catalog": { "url": "https://api.vibetron.ai/public/mcp" } } }
```

```sh
curl -X POST https://api.vibetron.ai/public/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Limits

- 60 requests per minute per IP across all of `/public` (API and MCP). A validation counts 5;
  every MCP message counts 1.
- At the edge, bursts above 20 requests in 10 seconds are refused.
- Over a limit: `429` with `Retry-After` (seconds). Wait, then retry.
- GET answers are cached 5 minutes (`Cache-Control: public, max-age=300`) and carry an `ETag`:
  send `If-None-Match`, a `304` costs nothing.
- `limit` ≤ 50, `q` ≤ 200 characters, request body ≤ 256 KB.

## What you cannot do without an account

Importing a tron, deploying it, filling keys, and talking to a deployed tron all happen in the
owner's account. For that there is the **account MCP server**, `POST https://api.vibetron.ai/mcp`:
it needs a personal MCP key the owner creates in Vibetron (Settings → API keys), and it acts as
them. Ask the owner for it; never ask for or handle their provider keys. Details:
https://vibetron.ai/docs

- Site: https://vibetron.ai
- Docs: https://vibetron.ai/docs
- Public API docs: https://vibetron.ai/docs/api-public
- Index for models: https://vibetron.ai/llms.txt