Communication protocol

Pipe v0.50.5

Overview#

The backend listens on both at once:

1. A Unix socket (/tmp/vps-agent.sock) – for clients on the same server (the Telegram bot)
2. TCP 127.0.0.1:7379 – for an SSH tunnel from a laptop (CLI)

Communication uses a simple JSON lines protocol (one JSON line = one message). In Kubernetes mode kubectl port-forward svc/pipe 7379:7379 gives access to the TCP port.

Message format#

Request – user message#

{
  "message": "message text",
  "session_id": "uuid-per-user",
  "interface": "cli:<user>|telegram:<user_id>|web:<user>",
  "token": "secret-token",
  "attachments": [{"name": "screenshot.png", "mime": "image/png", "data": "<base64>"}]
}

attachments is optional (files, photos, screenshots); with attachments message can be empty. Limits: 10 MB per file, 20 MB and 10 files per message; exceeding them or bad base64 ends with an error frame without calling the agent. The backend determines the kind from the content: an image goes to the model as image_url, text is pasted into the message (after secret redaction), other files are saved in DATA_DIR/uploads/ and the agent gets the path. A request line can be up to 32 MiB (the server's READ_LIMIT).

Request – confirming an operation#

{
  "confirm": true,
  "session_id": "uuid-per-user",
  "token": "secret-token"
}

Request – client command#

The clients' "/" commands (Telegram, CLI) send {"command": ...}:

{
  "command": "run_skill",
  "session_id": "uuid-per-user",
  "interface": "cli:kuba",
  "name": "renew_certificate",
  "args": "only for example.com",
  "token": "secret-token"
}

The backend builds the message for the agent (scan_server, run_skill, investigate, a message action from the inbox); the client sends only the command. Messages built by the backend don't teach VIBE. A skill's command field is a name that follows Telegram's rules (lowercase letters, digits, _, up to 32 characters). It is empty when the skill name is reserved (status, mapa, server, skille, katalogi, vibe, alerty, cele, rutyny, zmiany, wykres, zdrowie, raport, koszt, cofnij, dziennik, audyt, ...) or collides with another skill after shortening.

Response#

{
  "response": "response text",
  "status": "ok|confirm|error",
  "done": false
}

The server sends many JSON lines (streaming). The last line has "done": true. A frame can additionally contain (then response is empty, so older clients skip it):

Attachment – a file for the user, for example a diagram:

{"response": "", "status": "ok", "done": false, "attachment": {
  "name": "infrastructure-map.png", "mime": "image/png", "caption": "Infrastructure map",
  "data": "<base64>", "source": "<Mermaid source>", "text": "<ASCII preview or empty>"}}

Progress – an intermediate status (for example what a worker is doing), to show live; it isn't part of the answer:

{"response": "", "status": "ok", "done": false, "event": {"type": "progress", "text": "web-1 $ uptime", "source": "worker:web-1"}}

Frames with diagrams are hundreds of KB, so the client must read lines with a larger limit than asyncio's default 64 KiB (open_connection(..., limit=32 * 1024 * 1024)).

Watcher events (subscribe)#

After {"command": "subscribe"} the server sends {"event": {"type": "subscribed", "lang": "pl|en", "lang_chosen": bool, "view": "simple|tech", "view_chosen": bool, "ts": 1761679200.5}} (lang_chosen – the language was chosen with the language command, and the client should adopt it; view_chosen – the same for the view), and then, without done:

{"response": "", "status": "ok", "done": false, "event": {"type": "language", "lang": "en", "at": "..."}}

(Pipe's language was changed from any channel, so the client switches its messages; the event doesn't go into the alerts history; likewise {"type": "view", "view": "simple"} after a view change)

{"response": "", "status": "ok", "done": false, "event": {
  "type": "alert", "id": "3f2a9c1d0b", "key": "disk:/", "severity": "warning|critical",
  "title": "Disk / is 93% full", "detail": "3.1 GB free of 40 GB (/dev/sda1)",
  "since": "2026-09-24 14:02", "state": "new|resolved|event", "history": "", "at": "2026-09-24 14:02"}}

{"response": "", "status": "ok", "done": false, "event": {
  "type": "routine", "name": "morning-review", "status": "OK|PROBLEM", "report": "...", "at": "..."}}

{"response": "", "status": "ok", "done": false, "event": {
  "type": "reminder", "id": "6d1546", "kind": "message|task", "text": "...", "report": "",
  "to": "telegram:123", "set_at": "2026-10-01 20:02", "due": "2026-10-01 20:02:42", "at": "..."}}

{"response": "", "status": "ok", "done": false, "event": {
  "type": "activity", "id": "<tool call id>", "phase": "start|wait|end", "tool": "execute_command",
  "label": "docker restart web", "nodes": ["c:web"], "ok": null, "entry": "", "workers": {},
  "output": "web", "full": "...", "code": 0, "auto": true}}

Every client gets activity events in a conversation stream (except the viewer role); they say what the agent is doing and on which nodes of the map (graph). wait = waiting for confirmation; end has ok (true/false/null after a refusal) and entry, the journal entry id when the change was made. For commands (execute_command, remote_exec, git_command, cron_manage, write_file) end also carries a fragment of the output: output (up to 3 lines: on an error the error lines and the last one, on success the end, plus a safety fuse alarm), full (up to 60 lines / 4000 characters, to expand) and code (the exit code). It is the same result the model got, already with secrets redacted; in the simple view these fields are absent. auto: true – a change made without asking (autonomy, docs/security.md). A client that knows only progress can skip activity events.

to is the interface that set the reminder; the client decides whom to show it to. For kind: task the report field contains the worker's report.

{"response": "", "status": "ok", "done": false, "event": {
  "type": "digest", "title": "Report vps1 -- 29.09.2026 07:00", "text": "<everything as text>",
  "sections": [{"title": "Health", "lines": ["..."]}, {"title": "Changes since yesterday", "lines": ["..."]}],
  "attachment": {"name": "load-chart.png", "mime": "image/png", "data": "<base64>", "...": "..."}, "at": "..."}}

{"type": "investigation", "key", "title", "report", "auto", "alert_id", "severity", "fix_message"} – the findings of a worker that investigated a critical watcher alert (AUTO_INVESTIGATE) or a webhook alert (WEBHOOK_INVESTIGATE=1) by itself; both go through one Watcher.auto_investigate(), and fix_message is the text of the Fix it button. history in an alert – the last occurrence of the same problem (incident memory).

{"type": "insight", "key", "kind", "severity": "info|warning", "title", "text"} – a suggestion without the LLM (disk full forecast, space to reclaim, container restarts, a pending server reboot, growing RAM). {"type": "notice", "title", "text"} – a summary of what waited during quiet hours. {"type": "login", "id", "code", "device", "ip", "title", "text"} – someone at the /web page asks for access; the inbox buttons (Let in, View only, Reject) call the web command. Always notified, administrators only.

The inbox. alert, insight, digest, welcome, routine, investigation and notice events land in the inbox and also carry feed_id, push (whether to notify now: level, quiet hours, the suggestion limit), held (waits for the end of quiet hours) and actions (buttons: index, label, kind, admin...). A client notifies only on push: true, and a button sends feed_act with feed_id and index. No push (an older backend) = notify.

{"type": "approval", "id", "command", "target", "requested_by", "reason", "plan", "status"} – an external agent (MCP) is waiting for admin approval; the client shows buttons and sends approve.

{"type": "welcome", "title", "sections", "score", "grade", "text", "attachment"?} – once after installation, when the first subscriber connects.

state: new – a new or escalated alert, resolved – the problem is gone, event – a one-off event (a new public port, a stopped container). investigate with an id asks the agent to investigate the alert. Alert keys have a group prefix: disk:, memory, load, container:, port: (every WATCH_INTERVAL) and cert:, site:, dns:, backup: (checks without configuration, every CHECKS_INTERVAL). vuln:system – urgent fixable vulnerabilities in system packages, vuln:images – in container images, vuln:servers – on remote servers (ssh targets), vuln:apps – critical ones in application dependencies (persistent; sent again when a new one appears). hook:<source>:<name> – webhook alerts (persistent until a resolved message). auth:ssh (a series of failed logins) is persistent; security:<section>:<key>, auth:breach:... and auth:login:... are one-off events. digest arrives once a day at DIGEST_TIME.

Token authorization#

The token field is required when any token is configured: AGENT_TOKEN (admin role), AGENT_VIEWER_TOKEN (viewer role) or client tokens (python3 -m backend.tokens add NAME --role admin|viewer, with only the SHA-256 hash in data/tokens.json). Without any token the backend accepts every request (admin role).

The viewer role (read only): {"confirm": true} and undo with execute are refused, tools that change state return a refusal to the model (the client never gets a YES question). A session belongs to the identity that created it (the admin token, the viewer token or a named token); a request with another token and the same session_id gets This session belongs to another client.

The token is checked for every request type, including confirmations (confirm), so an unauthenticated client can't approve an operation pending in someone else's session. With a wrong token the backend answers:

{"response": "Error: invalid authorization token.", "status": "error", "done": true}

Response states#

Session flow#

1. The client connects (Unix socket or TCP)
2. The client sends a request (a JSON line + \n)
3. The server answers with one or more JSON lines
4. The last line has "done": true
5. If "status": "confirm", the client asks the user for confirmation
6. The client sends {"confirm": true|false, "session_id": "..."}
7. The server continues processing and sends further responses

Python implementation#

import asyncio
import json

async def chat_with_agent(message: str, session_id: str) -> list[dict]:
    reader, writer = await asyncio.open_unix_connection("/tmp/vps-agent.sock", limit=32 * 1024 * 1024)

    request = {"message": message, "session_id": session_id, "interface": "my-client"}
    writer.write(json.dumps(request).encode() + b"\n")
    await writer.drain()

    responses = []
    while True:
        raw = await reader.readline()
        resp = json.loads(raw)
        if resp.get("attachment"):
            save(resp["attachment"])            # e.g. base64 -> PNG file
        elif resp.get("event"):
            show_progress(resp["event"])
        else:
            responses.append(resp)
        if resp.get("done"):
            break

    writer.close()
    return responses

Requirements for new clients#

• One session_id per user (for example str(user_id))
• Send interface (<client>:<user>); it identifies the user in the audit log and in VIBE
• Handle the confirm status: ask the user and send the answer
• Handle attachment (show the image or save the file) and event of type progress (show it live)
• Read lines with a limit >= 32 MiB
• Handle long answers: split them into smaller messages if the platform has a limit
• Alerts: a separate, permanent connection with subscribe and reconnecting after a disconnect; send "since" with the ts of the last event you saw, and the server first sends what you missed (e.g. the /update result, which arrives right after the backend restarts). pipe web does this with the SSE id: / Last-Event-ID

Webhooks (HTTP)#

A separate port (WEBHOOK_PORT, off by default) that accepts alerts from other systems:

POST /hook/alertmanager | /hook/grafana | /hook/uptime-kuma | /hook/github | /hook/generic
Authorization: Bearer <WEBHOOK_TOKEN>        (or ?token=..., or GitHub's X-Hub-Signature-256 signature)
Content-Type: application/json

202 {"ok": true, "alerts": 2, "events": 1}
GET /health -> 200 {"ok": true}

Generic format (/hook/generic): {"title", "message", "severity": "critical|warning", "status": "firing|resolved", "name"}. Body limit 1 MiB. Without WEBHOOK_TOKEN the webhook server doesn't start.

Edit this page on GitHub