How an agent that its provider will not let keep a Fossil login key, such as one of OpenAI's or Anthropic's, works on a project through OCX: it reaches OCX's MCP tools through its provider's tunnel, which connects out from the agent machine, so no inbound port is opened, and OCX syncs its work for it, as its own Fossil user. The plan behind it is PLAN.md, "Agents on protocol v1"; the tools' common shape is USAGE.md.

MCP for a remote agent

• ocx2 --mcp-http HOST:PORT serves MCP over HTTP on this host's loopback alone, each JSON-RPC message posted to /mcp, for a client beside it such as a provider's tunnel.
• ocx2 --mcp-tunnel TUNNEL-ID is OCX's own client of OpenAI's Secure MCP Tunnel, long-polling the tunnel's control plane and connecting out alone, its key in OCX_TUNNEL_KEY, which its run's node fills from the run's secret.
• In a clone, as a run's process is, the MCP server answers for its user as the server grants that user, asked of the server's receipt, not as the clone lists its cloner, setup.

Set a secret a run may use

secret NAME VALUE sets the repository's ocx-secret-NAME setting for a user with admin or setup, never over MCP. Settings do not sync, so set it on the node's clone with ocx2 --repository CLONE secret NAME VALUE on the agent machine; one set on the served web page reaches no run. No answer, log or page shows its value. A run an admin sends names it as $$secret:NAME$$ in its process's env. The clone a run's steps make for its user holds no secret, so the watcher reads it from the node's clone and fills it in that environment alone. started and kept logs show its name where its value would be (protocol v2).

Sync an agent's work through the call

An agent working in a run's checkout, on any node, needs none of this section: its run's clone is made as its run's user and remembers that user's password, on its agent machine (protocol v2), so its commits push as it makes them, and fossil push sends one that did not. Only an agent outside every run's checkout that keeps no Fossil password uses sync.

sync BRANCH, for an agent that keeps no Fossil login key, through its run's MCP (ocx_sync) or in a clone's checkout: the agent commits in its own clone on its working branch, never trunk, each comment with Intent, Expression and Demonstrates lines, runs fossil bundle export push.bundle --branch BRANCH --standalone, and gives the file base64 as bundle. Each check-in is read before anything is imported, and one off the branch or unstated refuses the whole bundle; the rest are imported into the run's clone and pushed as the run's user, whose capabilities the server holds them to. Its answer names each check-in pushed as the server holds it: its hash in full, its link, and the user the server's receipt says sent it. With have, a check-in the agent holds, the clone pulls and answers a bundle of every check-in after it, which the agent applies with fossil bundle import pulled.bundle --publish. receipt in a run's clone asks the server's own receipt tool, as anyone may, and says so.

commit_and_sync_guide BRANCH, offered everywhere, says those steps as commands for the agent's own shell, filling the stated message from the title, intent, expression and demonstrates it gives. commit_and_sync takes them, for an agent running ocx2 --mcp on its own machine: it commits its checkout's changes on its working branch with that message, without syncing, and answers the branch's bundle for ocx_sync; called remotely, through a tunnel, MCP over HTTP or the web page, it does nothing and points to the guide.

Edit the run's checkout

An agent with no clone of its own works on the run's checkout through its MCP (docs/agent-tools-proposal.md says why each is shaped as it is): ocx_context, what the run is for and where its work stands; ocx_find, the lines holding a text; ocx_read, a file's lines exactly, their numbers apart; ocx_edit, a text that appears once replaced; ocx_test, one of the tests the project names in ocx-tests.json at its checkout's root, each a name and its command as a list of words; and ocx_save, every change committed on the working branch, agent/, the user and eight hex digits, once each test has passed with the checkout as it is, and pushed as the run's user. ocx_wiki_read and ocx_wiki_edit share wiki pages, a page changed as ocx_edit changes a file; ocx_unversioned_list, ocx_unversioned_get and ocx_unversioned_put share binaries as Fossil's unversioned files, base64. Every tool's answer begins with ok, and a refusal gives next_step, what to do instead.

The pattern run/mcp-tunnel

One run of it per remote agent brings that agent in: its process is OCX's tunnel client, in the run's own clone, acting as the run's user, the agent's own Fossil user. Save the block below, with a line saying what it is for, as the wiki page run/mcp-tunnel, as a user holding admin or setup.

{"workspace": [
   {"step": "directory", "at": "$$root$$/$$process_user$$/projects/$$repository_name$$/$$run$$"},
   {"step": "password"},
   {"step": "clone", "into": "$$workspace$$/clone"},
   {"step": "checkout", "of": "trunk", "into": "$$workspace$$/tree"}],
 "sandbox": {"uid": 1000, "gid": 1000, "linux_capabilities": [], "network": true, "isolate_terminal": true,
             "ends_with_parent": true,
             "read_only": ["/usr", "/bin", "/sbin", "/lib", "/lib64", "/etc/resolv.conf", "/etc/hosts",
                           "/etc/nsswitch.conf", "/etc/ssl", "$$release$$"],
             "read_write": ["$$workspace$$"], "homes": [],
             "created_files": [{"at": "/etc/passwd", "text": "$$process_user$$:x:1000:1000::$$workspace$$:/bin/sh\n"}],
             "proc": "/proc", "dev": "/dev", "tmp": "/tmp"},
 "limits": {"wall": "30d"},
 "process": {"command": ["ocx2", "--mcp-tunnel", "TUNNEL-ID"], "cwd": "$$tree$$",
             "env": {"HOME": "$$workspace$$", "USER": "$$process_user$$", "PATH": "$$release$$:/usr/bin:/bin",
                     "OCX_TUNNEL_KEY": "$$secret:SECRET-NAME$$"}}}

To bring an agent in:

1. In Fossil's Admin → Users, make the agent's user, holding what it may do, such as gio24 (clone, read code, check in, read the forum, post there).
2. In OpenAI's Platform, create a tunnel; note its id and its runtime key.
3. Set the key on the agent machine: ocx2 --repository CLONE secret NAME KEY, CLONE the node's clone, NAME such as chatgpt.
4. On the OCX page, create with the objective, pattern run/mcp-tunnel, user the agent's user, and fields {"process": {"command": ["ocx2", "--mcp-tunnel", "TUNNEL-ID"], "env": {"OCX_TUNNEL_KEY": "$$secret:NAME$$"}}} with the tunnel's id and the secret's name.
5. Give the agent the tunnel, by its id, as its MCP server: in a ChatGPT workspace, the tunnel alone is not enough: at https://chatgpt.com/plugins, Add a plugin that uses it, and the workspace's agent then lists OCX's tools. It learns the rest from tools/list, ocx_commit_and_sync_guide first.

A stop ends the run, and the tunnel with it. The tunnel offers the agent the tools of the release its node was running when the run started, since $$release$$ is fixed then; a release accepted later reaches the agent through the tunnel only with another run. Sent with the same user while this one runs, that run waits, and starts by itself once this one ends; so stop this one, and check the agent's tools/list after. Apart from the tunnel, an agent may clone OCX's own repository, https://ollama.openbeagle.org/ollama, build it, and call ocx2 --mcp on its own machine, beside its own clone: those tools are its own, whatever release the tunnel offers.