Skip to content

steveseguin/vdoninja-connect

v0.3.0

Connect local agents and a human browser through VDO.Ninja peer rooms. Exchange messages, requests and selected files without a VDO.Ninja account.

GitHubOpen Website

VDO.Ninja Connect

Talk to an agent through a private P2P link, exchange selected files, and keep a Codex conversation available after closing the desktop app. No VDO.Ninja account is required.

Open the browser client on your computer or phone. Connect using a private invitation from your running agent service.

Start your background agent

Install Node.js 22 or newer and the Codex CLI, then sign in with codex login. In this folder:

npm ci --ignore-scripts
npm run background -- start
npm run background -- invite

Open the returned web_url on your phone or computer and click Connect to agent. The url address opens the locally served client on the service computer. Each invitation pairs one browser or agent; that device saves its replacement key for reconnecting. Each pairing gets its own persistent Codex conversation.

The service runs independently of the desktop app. Keep its computer awake and connected to the internet. Codex uses its configured account and usage allowance. This creates a separate conversation; it does not connect to an existing ChatGPT Dot thread.

npm run background -- status
npm run background -- stop

See background setup for Windows login startup, another device, agent clients, voice, files and revoking access.

Watch the browser walkthrough: turn selected notes into a checklist, download a file and continue the conversation after reconnecting.

Talk, share and listen

  • Send messages from the browser or a headless agent client.
  • Upload and download selected files up to 8 MiB. Select text or images to attach them to a message.
  • Dictate an editable draft or enable Read replies aloud using browser speech services.
  • Configure a transcription API key to send recorded voice messages.
  • Open the camera and attach a photo when you want the agent to see something.

The background assistant is configured for conversation and selected attachments. It has no remote shell command interface. Continuous audio/video calls are not supported; use recorded voice and selected photos.

Add the MCP tools

For temporary peer rooms or controlling background invitations from a local agent:

node scripts/setup-local.mjs

Reopen this trusted project in Codex to load its project MCP configuration. Other local MCP clients can launch node with the absolute path to src/server.mjs. Set a tool timeout of at least 35 seconds. Use either this MCP entry or the packaged plugin, so tools are not registered twice.

Ask: "Create a peer room and give me the browser link." Another agent can join with vdo_connect, exchange messages and selected files, and disconnect when finished. These temporary sessions end with their MCP process and do not start background model turns. Temporary room guide.

Hosted MCP connector

To connect a remote MCP client, deploy the hosted connector and register its HTTPS /mcp endpoint. It uses OAuth to pair with the background service and exposes selected tasks and text files. GitHub Pages hosts the browser client; the connector needs an always-on server.

Privacy and connections

Keep invitations and saved pairing keys private. Background messages and files use a separate encryption key for each pairing; revoke that pairing to stop access. Temporary rooms instead grant room access to anyone with their invitation, and peer names are self-asserted.

VDO.Ninja provides signaling, and TURN may relay encrypted traffic when a direct route is unavailable. Peers may learn each other's IP addresses. Messages and selected attachments sent to Codex reach its model provider. Recorded voice sent for transcription reaches OpenAI; browser dictation may use the browser vendor's service.

State and files are stored under ~/.vdoninja-connect/. Codex also retains its conversation history. Stop the service before removing its local data. Storage and operating details.

Package

npm run package:client
npm run package:plugin

The client command produces a standalone HTML client. The plugin command produces a source ZIP with its lockfile and manifests; install its dependencies before running it. Outputs default to ~/.codex/artifacts/vdoninja-connect/, or VDONINJA_PACKAGE_DIR. Distribution guide.