openvibers/openvibe.link README.md
README.md
| 1 | # OpenVibe Link |
| 2 | |
| 3 | OpenVibe Link connects your computers, phones and robots to OpenVibe. |
| 4 | |
| 5 | **Live site:** https://openvibe.link · **API docs:** https://openvibe.services · **For AI:** https://openvibe.link/llms.txt |
| 6 | **Install:** `curl -fsSL https://openvibe.link/install | sh` |
| 7 | |
| 8 | One service for your computers, servers, Raspberry Pis, phones and robots: pair it once with OpenVibe and products |
| 9 | like **OpenVibe.Bot** (robots: drive, cameras, sensors, with safety) and **OpenVibe.Actor** (computer control for AI |
| 10 | agents, at the level you set on the machine) can use the device. It connects out, needs no open ports, and keeps a local kill switch. |
| 11 | |
| 12 | Every release is built by CI for every system: **Windows x64 and ARM64**, **macOS Apple silicon and Intel**, **Linux |
| 13 | x64 and ARM64** (`.deb`, `.rpm`, a tarball, and the `curl | sh` script), and the **Android APK**. The |
| 14 | [openvibe.link install page](https://openvibe.link/#install) picks the visitor's OS and offers the others; the |
| 15 | [install guide](docs/install.md) has the exact steps, including the home-screen web app for iPhone and iPad. |
| 16 | |
| 17 | On a robot's Raspberry Pi (or other Linux computer), the one command: |
| 18 | |
| 19 | ```sh |
| 20 | curl -fsSL https://openvibe.link/install | sh |
| 21 | ``` |
| 22 | |
| 23 | |
| 24 | It turns on I2C and SPI, installs the camera tools, finds the kit (an Adeept ADR036 4WD, a ROS 2 robot), shows a code |
| 25 | to approve at openvibe.bot/link, and pairs: the robot is made, drivable on its panel and, if you chose it, live on your |
| 26 | OpenVibe.Live channel ([docs/install.md](docs/install.md#the-one-command-raspberry-pi-and-other-linux-robots)). |
| 27 | |
| 28 | With a robot already added on openvibe.bot: |
| 29 | |
| 30 | ```sh |
| 31 | curl -fsSL https://openvibe.link/install | sh -s -- --robot rob_… --code ABCD-1234 --driver adeept |
| 32 | ``` |
| 33 | |
| 34 | openvibe.bot shows this command with the robot's id and a fresh code. `--driver` is `adeept`, `adeept-mecanum`, `cozmo`, `ros2`, |
| 35 | `looi` (the community's Generic LOOI driver, [docs/hardware-looi.md](docs/hardware-looi.md)) or `none` (dry run; the old `--robot adeept` form still works but is deprecated). A robot paired through |
| 36 | OpenVibe.Network gets `--network <URL> --pairing pair_… --code ABCD-1234` instead of `--robot`. Details, manual |
| 37 | install, Windows and configuration: [docs/install.md](docs/install.md). |
| 38 | |
| 39 | **Put a port on the web** with [OpenVibe Connect](https://connect.openvibe.website): `openvibe-link share 8790` |
| 40 | serves the share this computer was picked for at `https://<name>--<you>.openvibe.website` behind OpenVibe sign-in (or |
| 41 | `openvibe-link share --key ovc_… --port 8790` with a key), and `openvibe-link share add` keeps it up with the service; |
| 42 | `openvibe-link status` lists each share ([docs/connect.md](docs/connect.md)). |
| 43 | |
| 44 | **Host a shared party computer** with `openvibe-link party host <party-id>` from [openvibe.party](https://openvibe.party). Link shows the running desktop and its Stop action in its window ([guide](docs/party-desktop.md)). |
| 45 | |
| 46 | **Ask another machine for access:** `openvibe-link access request <machine> --scope screen,desk --for 1h`. The target owner approves on their machine; a signed, scoped grant controls each use. Turn on **Let my agents talk** to register local agent CLIs and give them Link's `openvibe-link mcp` tools. [Machine access and agent messages](docs/access-and-agents.md) explains scopes, approval, revocation, the inbox, and MCP setup. |
| 47 | |
| 48 | **Sell a local model** on [OpenVibe.Exchange](https://openvibe.exchange): |
| 49 | `openvibe-link exchange serve --model qwen3:32b --public-url https://gpu.example.com/v1`. It serves the model from the |
| 50 | local OpenAI-compatible server (Ollama by default at `127.0.0.1:11434`), registers the public https address through the |
| 51 | Exchange's endpoint-seller flow with your `OPENVIBE_DEVELOPER_KEY`, and removes the offer when you stop it with Ctrl-C. |
| 52 | The public URL must be reachable by the Exchange and is judged by its egress guard; keep it behind your own tunnel or |
| 53 | reverse proxy. The local listener has no buyer authentication (the Exchange's endpoint flow sends no buyer identity), so |
| 54 | bind it to loopback, which is the default. |
| 55 | |
| 56 | ```sh |
| 57 | openvibe-link # guided first run: pair, check the link, report this machine's first job |
| 58 | openvibe-link status # link, plugins, video, battery, shares, stop latch |
| 59 | openvibe-link stop # kill switch: stop every motor now and keep it stopped |
| 60 | openvibe-link resume |
| 61 | openvibe-link quit # end the node cleanly (nothing latched), e.g. from a stream launcher |
| 62 | openvibe-link approvals # the computer plugin at level ask: what waits; approve <id> / deny <id> |
| 63 | openvibe-link tray # the same in your notification area, with Approve/Deny notifications (Linux, Windows) |
| 64 | openvibe-link memory scan # what your coding tools remember: read-only, local, secrets removed |
| 65 | openvibe-link memory upload # send what they remember to your own memory store, after you say yes |
| 66 | openvibe-link memory sync # write your profile and rules back into the tools, one marked block per file, opt-in per tool |
| 67 | openvibe-link skills sync # write the skills and rules you chose at openvibe.codes/skills into each tool, with a dry run and undo |
| 68 | openvibe-link exchange serve --model qwen3:32b --public-url https://gpu.example.com/v1 # sell a local model |
| 69 | ``` |
| 70 | |
| 71 | ## What is in here |
| 72 | |
| 73 | - **Core** (Go, one static binary per platform): pairing, one outbound WebSocket to `wss://openvibe.bot/device` |
| 74 | (credential in the `Authorization` header only), heartbeats and a deadman, the safety rules (deadlines, owner limits |
| 75 | clamped before any driver sees a value, a persisted stop, the local kill switch), the plugin supervisor, WHIP video |
| 76 | publishing with pion, and the system service (systemd, launchd, Windows). |
| 77 | - **Plugins** (separate processes, JSON lines over stdin/stdout): [`dryrun`](plugins/dryrun), the Adeept 4WD Smart Car |
| 78 | Kit [`adeept_adr036`](plugins/adeept_adr036/README.md), [`cozmo`](plugins/cozmo/README.md) through PyCozmo, and |
| 79 | [`relay`](plugins/relay) for existing Live hardware clients, and [`ros2`](plugins/ros2/README.md) for ROS 2 robots |
| 80 | (`cmd_vel`, battery, scan/range, odometry and camera, as a node with rclpy or through rosbridge). LOOI's driver is the community's |
| 81 | ([docs/hardware-looi.md](docs/hardware-looi.md) is its contract). Each plugin stops its own actuators when stdin closes, |
| 82 | at a command's deadline and after 1 s without a heartbeat, so the core dying never leaves motors running. |
| 83 | - **ESP32 library** ([`esp32/`](esp32/README.md), `OpenVibeLink`): the device side of the protocol for ESP32 boards — |
| 84 | pairing, the control link, drive/actuator commands, telemetry, heartbeat, deadman and stop — but no jobs or video. |
| 85 | |
| 86 | **Community robots:** a profile people submit on openvibe.bot (`community.<name>`) is reviewed by an OpenVibe admin |
| 87 | and signed by Bot (Ed25519 over its canonical JSON). `openvibe-link profile verify community.<name>` checks that |
| 88 | signature against the key Bot publishes (`--key-id` pins one) and names the plugin the robots run; pairing with a robot |
| 89 | on a community profile runs the same check and warns when it fails. Install a community plugin only when it passes |
| 90 | ([docs/plugins.md](docs/plugins.md#community-plugins)). |
| 91 | |
| 92 | **Your computer for your agents:** `--computer observe|ask|trusted|full` adds the `computer` plugin (terminal, files, |
| 93 | screen, mouse and keyboard, and a browser of its own for OpenVibe.Actor), running as your own account, at the level you set on the machine; `ask` waits for |
| 94 | your answer in the tray, a notification's Approve button or `openvibe-link approve <id>` ([docs/computer.md](docs/computer.md)). |
| 95 | With it on, you can also watch the machine's screen live on openvibe.bot. Only you see it, it runs for up to 30 |
| 96 | minutes, and `openvibe-link stop` ends it at once ([the live screen](docs/computer.md#the-live-screen-screen_stream-node-v0120)). |
| 97 | |
| 98 | **Your own models for your OpenVibe work:** the `ai` plugin lets OpenVibe use a model you already run at home (Ollama, |
| 99 | LM Studio or llama.cpp's server) for your own work, at no cost and with no open port, once you turn on "Let my AI use |
| 100 | this computer's models" on openvibe.link/machines ([docs/ai.md](docs/ai.md)). The installer sets it up with `--ai`. |
| 101 | |
| 102 | **A machine that runs your jobs:** add it on openvibe.link/machines, which prints the same installer with `--worker`: the |
| 103 | job worker runs each job as an unprivileged user in a sandbox, and the OpenVibe.Codes job runner lets you start a coding |
| 104 | task on openvibe.codes/run from any browser and have this machine do it ([docs/worker.md](docs/worker.md)). Add |
| 105 | `--plan-logins` to use the coding plans you already signed in for here: it names those login files for your jobs, sets |
| 106 | the service's HOME to your home, and says how to sign in a tool that is not ready, without ever reading or printing a |
| 107 | login's content. |
| 108 | |
| 109 | **What the machine does for the network:** the owner sets the machine's roles on openvibe.link/machines |
| 110 | (`codes.worker`, `desks.host`, `ai.host`, `bot.robot`). Link reads them at its check-in, keeps them, and applies |
| 111 | the ones this machine was installed for: the job worker starts if the local configuration has it, and the machine says |
| 112 | plainly which role it could not honour. The local configuration always wins: a role never installs anything and never |
| 113 | turns on a feature you turned off here. |
| 114 | |
| 115 | **Link's own window:** the tray's **Open Link** (or `openvibe-link panel`) opens a small page on the machine itself |
| 116 | at `127.0.0.1` that shows what runs here, what this computer allows, your shares, the coding-agent CLIs and the Codes |
| 117 | tasks this machine ran today, and what happened, and lets you pause everything, stop one thing, turn a capability off, |
| 118 | share a port, or send a file, a note or copied text to another of your machines (sealed on this computer with |
| 119 | openvibe-sdk/locker; the other machine lists the sender and size and asks before saving). A transfer is uploaded in |
| 120 | parts, so a dropped connection continues where it stopped; on the same network it is handed over directly, and |
| 121 | otherwise the relay holds only ciphertext. Clipboard sharing is a per-machine switch, off by default and text only; |
| 122 | with auto-accept on, the daemon saves a received file to Downloads and puts received copied text on the clipboard |
| 123 | without needing the window open. It is served only on loopback, with a per-run token in the address fragment that |
| 124 | every API call must send; see [docs/panel.md](docs/panel.md) for the security rules. |
| 125 | |
| 126 | **Your machines:** [openvibe.link/machines](https://openvibe.link/machines) opens the signed-in machines hub: each |
| 127 | paired machine, whether it is online, the roles it plays (Codes jobs, desks, your own models, a robot), and pairing a |
| 128 | new one from [openvibe.link/pair](https://openvibe.link/pair). It is the same account page on openvibe.my, reached from |
| 129 | Link's own name. |
| 130 | |
| 131 | **Link on your phone (Android, v0):** the same pairing and connection as desktop Link, in an app: your agents' |
| 132 | approvals in your pocket (money, passwords, deletions and a send to a new recipient ask for a fingerprint first), the |
| 133 | Dock's activity read-only, and **Send to OpenVibe** from any app's share sheet to your Download drive. It pairs from |
| 134 | openvibe.bot/link/phone and shows up as a device of kind `phone`. No phone automation at all in this version: no |
| 135 | AccessibilityService, no screen capture. Build, install and the security notes: [docs/android.md](docs/android.md). |
| 136 | |
| 137 | **Git on this computer (Git plan G3):** `openvibe-link clone '<link>'` serves a "Clone to my computer" request from |
| 138 | git.openvibe.codes: it shows the repository and the folder, asks you, clones with your own git inside the root you |
| 139 | chose (`--root`, default `~/OpenVibe`), reports progress to the page, and refuses an expired request, a folder |
| 140 | outside the root, or a non-empty folder without a second answer. One clone runs at a time per machine. The page's |
| 141 | `openvibe-link://clone?url=…` deep link is the same request. `openvibe-link git connect '<link>'` publishes the |
| 142 | repositories under `--root` to OpenVibe Git, read-only, until Ctrl-C: the page lists them and browses tree, file and |
| 143 | log through the poll the Link opened. The same poll also carries a **"Clone to <this computer>"** from the repository |
| 144 | page: Link asks on this computer — a desktop prompt with Approve and Deny (a notification on Linux, a dialog on |
| 145 | macOS) and the same question with `y`/`N` in the terminal, whichever answers first — and nothing is written until |
| 146 | you approve (`--yes` answers for a script). Neither command opens a port on this computer; both connect out to Git. |
| 147 | |
| 148 | Docs: [protocol](docs/protocol.md) (the wire format with OpenVibe.Bot), [plugins](docs/plugins.md) (the driver |
| 149 | protocol, the bundled drivers, and where Actor's computer-control plugin attaches), [install](docs/install.md), |
| 150 | [panel](docs/panel.md) (Link's own window and its security rules), |
| 151 | [memory](docs/memory.md) (what the coding tools on a machine remember, how Link reads it and how it is uploaded to |
| 152 | your own memory store), [skills](docs/skills.md) (the skills hub: which folders each tool reads, the marked block, the |
| 153 | dry run and the undo). |
| 154 | Decisions: [ADR-043](docs/ADR-043-bot-devices-and-control.md). |
| 155 | |
| 156 | ## Development |
| 157 | |
| 158 | ```sh |
| 159 | go vet ./... && go test -race ./... # the end-to-end tests run the Python dry-run plugin |
| 160 | pip install pytest pillow numpy |
| 161 | for p in sdk dryrun adeept_adr036 cozmo relay ros2 computer; do python3 -m pytest -q plugins/$p/tests; done |
| 162 | scripts/dist.sh v0.0.0-dev # every binary, the plugin bundle and SHA256SUMS in dist/ |
| 163 | ``` |
| 164 | |
| 165 | `internal/fakebot` is a fake OpenVibe.Bot (pairing, device WebSocket, WHIP) used by the tests. Licence: AGPL-3.0 |
| 166 | ([LICENSE](LICENSE)). Security reports: [SECURITY.md](SECURITY.md). |
| 167 |