# Vltra | agent instructions

Vltra sends your messages to the user's iPhone, iPad or Mac, and can bring
their answer back to you. Use it when the user is away from the screen: a long
task finished, something failed, or you need a decision to go on.

Server: https://vltra.gzor.es
Auth:   Authorization: Bearer <key>. The user gives you a key that starts
        with vk_live_. It can only send messages and read answers to your own
        questions. Never print it in full, never commit it.

## Fast setup (do this first)

If Node.js is available, run:

    npx -y vltra init --key vk_live_xxxxxxxx --server https://vltra.gzor.es

It detects Claude Code, Codex and Gemini CLI and adds three things:
1. Hooks, so the user is alerted when you stop or wait for input, even if you
   forget to call Vltra.
2. The Vltra MCP server, with the tools vltra_notify, vltra_ask and
   vltra_progress.
3. A short note in CLAUDE.md / AGENTS.md / GEMINI.md that tells you when to
   use them.
Then it sends a test message. Tell the user to check their phone.

Without Node: pip install vltra && vltra init --key ... (same result), or use
the HTTP API below directly.

## When to send

- Finished a task that took more than a couple of minutes: priority normal.
- Blocked, need a decision, tests broke, deploy failed: priority high.
- Something is on fire, or a question that blocks all work: priority urgent.
- Progress worth knowing but not worth a buzz: priority low.
Do not send a message for every small step. One clear message beats five.
Write like a short text to a colleague: what happened, and what you need.
Markdown works (code blocks, tables, lists, Mermaid).

## Send a message

    curl -s https://vltra.gzor.es/v1/messages \
      -H "Authorization: Bearer $VLTRA_KEY" \
      -H "Content-Type: application/json" \
      -d '{"project":"my-app","title":"Tests pass","message":"All 214 tests pass on main.","priority":"normal"}'

Fields: message (required), title, project (one chat thread per project; use
the repo or folder name), priority (urgent | high | normal | low), link
(http URL), image (base64 or data: URI, up to 10 MB), image_url, agent
(e.g. "Claude Code"), model, branch. Files: send multipart/form-data with a
"json" part holding the fields above plus file parts (up to 25 MB each).

Shortest form, plain text, project from the path:

    curl -s -H "Authorization: Bearer $VLTRA_KEY" -d "Build done" https://vltra.gzor.es/my-app

Headers for the plain form: X-Title, X-Priority, X-Link, X-Agent.

## Ask a question and wait for the answer

    curl -s "https://vltra.gzor.es/v1/ask?wait=120" \
      -H "Authorization: Bearer $VLTRA_KEY" \
      -H "Content-Type: application/json" \
      -d '{"project":"my-app","question":"Deploy to production?","options":["Deploy","Wait"],"timeout_min":30}'

The user taps a button or types a reply. options: 2 to 6, up to 40 characters
each. allow_text: true lets them type (default when there are no options).
The response has "state": pending | answered | expired, and "reply" with
"option" or "text". If it is still pending after the wait, poll:

    curl -s "https://vltra.gzor.es/v1/messages/<id>/reply?wait=120" -H "Authorization: Bearer $VLTRA_KEY"

Each call waits up to 120 seconds. Repeat until answered or expired. With the
MCP tool vltra_ask this loop is done for you.

## Live progress

    curl -s https://vltra.gzor.es/v1/progress -H "Authorization: Bearer $VLTRA_KEY" \
      -H "Content-Type: application/json" \
      -d '{"project":"my-app","step":"Running tests","percent":40}'

Shows on the lock screen as a Live Activity. Send "done":true at the end.

## Errors

Every error is JSON: {"error": "...", "hint": "...", "docs": "https://vltra.gzor.es/"}.
Read the hint; it says how to fix the call.
- 401: bad or revoked key. Ask the user for a new one (Vltra app > Agents).
- 402: the free week of Vltra Cloud ended. Tell the user; do not retry.
- 429: too many messages. Wait for the Retry-After seconds. Limits: 60 per
  minute per key, 5000 per day per account.

## Privacy

Messages are kept for 30 days by default (the user can change it) and
deleted for real when the user deletes them. Do not send secrets, passwords
or keys in messages.

App: Vltra on the App Store. Self-host: github.com/Locotir/vltra (AGPL-3.0).
This text is also at https://vltra.gzor.es/llms.txt.