Your computer for your agents

Install it

On Your machines, choose Add a machine and run the second command it shows on the computer, from your own account (the installer uses sudo itself):

curl -fsSL https://openvibe.bot/install | sh -s -- \
  --network https://openvibe.network --pairing pair_… --code ABCD-1234 --computer ask

The Node then runs as you, never as root, and its only folder is your home folder. Linux for now; elsewhere, run the Node in your own session with the plugin in its config (computer.md).

Levels, set on the computer

• observe (the default): take a screenshot; list, inspect and read files inside its folders.
• ask: also run programs, write files there and use the mouse and keyboard, each only after you approve it on the computer (the approval says exactly what: "click at 640, 360", "type 12 characters", "press ctrl+s").
• trusted: run programs, write files inside its folders and use the mouse and keyboard without asking.
• full: as trusted, anywhere your account can reach.

A program is always a program and its arguments, never a shell line. It runs for at most the time you set (30 seconds by default), at most two at once, and its output is cut at 64 KB. A path is checked after links are followed, so a link out of a folder is outside it.

Approving on the computer

At level ask, a request waits up to two minutes for your answer. You can answer in three places:

• The tray (Linux and Windows). openvibe-node tray lists what waits, each with Approve and Deny, beside the stop and resume. It raises a notification with the same two buttons, and its icon turns amber while something waits. The installer starts it when you sign in.
• A notification or dialog from the Node itself when it runs in your session: buttons on Linux, a dialog whose default is Deny on macOS.
• The command line:

openvibe-node approvals          # what waits: id, kind, what it would do
openvibe-node approve cmd_01J…   # let it run
openvibe-node deny cmd_01J…      # refuse it
openvibe-node stop               # the kill switch: observe only until resume
openvibe-node tray               # the same in your notification area (Linux, Windows)

An approval is not taken while the agent is using the mouse or keyboard, nor for two seconds after, so a click the agent makes can never press Approve. Deny always goes through.

The local stop drops the computer to observe at once: what runs is killed, what waits is denied, and nothing runs or changes until you resume.

Your agent

On Your machines, Let my agent use this computer is off until you turn it on. With it on, a task you give OpenVibe.Actor, such as "what changed in ~/site today?", can list and read files, run programs and write files there, as you and at your level. The Console shows what waits for you. Turning the switch off stops it at once.

Let my watches check things from this computer is a separate switch. It lets OpenVibe.Watch probe your own network from the computer for your watches, for example "tell me when my NAS stops answering". It allows only probes: one GET or one TCP connect, to private addresses only.

Watch your screen live

On Your machines, Show my screen shows the computer's screen live, to you only, for 10 minutes (30 seconds to 30 minutes through the API).

• Private. It goes to a private stream of that computer's own: nothing is recorded, it never appears on OpenVibe Live, and only you can open it. Your agents, your watches and anyone else cannot start it.
• How it is captured. The computer takes a few pictures of its screen a second with the same tools as a screenshot. It needs OpenVibe Node v0.12.0 or newer, with the computer plugin running in your desktop session.
• It says so. The desktop shows a notice when it starts, and openvibe-node status shows it while it runs.
• Stopping it. Stop showing my screen ends it, and so do its time running out and openvibe-node stop on the computer, at once. To never offer it, set allow_screen_stream: false in the plugin's config.

From the API, with your own token: POST /api/v1/machines/:id/screen (seconds, fps from 1 to 5) starts it, GET answers signaling_url once the computer is sending, and DELETE stops it.

The API

Your own token reaches your own computers. The answer comes back in data:

curl -X POST https://openvibe.bot/api/v1/machines/dev_…/commands \
  -H "Authorization: Bearer $OPENVIBE_TOKEN" -H "Content-Type: application/json" \
  -d '{"kind": "exec", "value": {"argv": ["git", "status", "--short"], "cwd": "/home/you/site"}}'
# → {"machine_id": "dev_…", "result": "ack", "data": {"exit_code": 0, "stdout": " M index.html\n", …}}

• exec: argv, cwd, timeout_s, stdin → exit_code, stdout, stderr, truncated, timed_out.
• fs: op list, stat, read (offset, length), write (content_b64, mode create, overwrite or append) or mkdir, and an absolute path.
• screen: max_width → a JPEG in content_b64.
• browser: action, which is one of:
  • open a url;
  • click a CSS selector or the button or link showing text;
  • fill a field (selector and text);
  • press a key;
  • back, read, screenshot or close.
  The page answers with its URL, title, text and links. The browser is the agent's own, in a profile of its own on your computer; it never sees your browser's sessions. Reading, screenshots and closing run at every level; the rest are approved one by one at ask. Below full, open refuses an address on your own network. The audit keeps the host, the selector, the key and the number of characters filled, never the text.
• input: action (move, click, double_click, right_click at x, y; scroll by dy; type a text; key one key or chord such as ctrl+s), with width and height of the screenshot the coordinates come from; the computer scales them to its real screen. It acts, so your level decides: never at observe, approved one by one at ask. xdotool on Linux (X11), cliclick on macOS. The audit keeps the action and the number of characters typed, never the text.
• probe: target (http(s)://… or tcp://host:port on the computer's own network) → the status and body of one GET, or whether the port is open. It is read-only and runs at every level.

GET /api/v1/machines lists your machines with their level. A machine whose plugin is off answers 409 bot.computer_off; a refusal on the computer answers result: "nack" with the reason. The audit keeps the program name or the file and path, never its content.