Connect any harness

The reference adapter uses Python 3.10+ and its standard library. Initial certificate generation requires the system openssl command. It executes only the three built-in protocol operations; it does not execute scripts, shell commands, or model-generated code.

From the directory where you saved companion.py:

python3 companion.py init
python3 companion.py serve

Configuration defaults to ~/.harness-companion (0700). The harness token, private key and SQLite database are private files (0600). Keep this directory outside source control and back it up securely. init requires an empty directory and never overwrites an existing identity. The certificate lasts 365 days; replacing it requires new pairing on each device.

For an iPhone or iPad, initialize with the Mac’s reachable LAN address and explicitly listen on the LAN. The device and Mac must be able to reach each other; no hosted relay is provided.

python3 companion.py --config ~/.companion-lan init --url https://192.168.1.2:8766
python3 companion.py --config ~/.companion-lan serve --host 0.0.0.0 --port 8766

In a separate terminal, request one worker credential:

python3 companion.py --config ~/.companion-lan pair

Paste the resulting pairing JSON into Harness Companion. This command intentionally displays the worker secret: do not publish it or paste it into a shared chat. Each pair creates a separate credential, permanently bound to the first device that registers with it. Forgetting a connection in the app creates a new device UUID for the next pairing. A new credential cannot take over an existing device UUID, even after revocation. A worker credential cannot submit jobs, list devices, or inspect other devices’ work. Start sharing in the app before submitting. Mobile sharing runs during the visible foreground session.

CLI lifecycle

All commands accept --config DIRECTORY before their subcommand. Responses are JSON; failures exit nonzero and print a safe message to stderr. serve and mcp never print credentials. Use a stable UUID with --id when retrying submission. Reusing an ID with altered input conflicts.

python3 companion.py devices
# Write {"text":"Hello world"} to input.json, then use an ID returned by devices:
python3 companion.py submit --device DEVICE_UUID --operation text.analyze --input input.json --id JOB_UUID
python3 companion.py status JOB_UUID
python3 companion.py artifact JOB_UUID
python3 companion.py cancel JOB_UUID
python3 companion.py revoke DEVICE_UUID

--input - reads JSON from stdin. --id is optional; omission generates a UUID. Operations: text.analyze, text.chunk, and image.ocr. The exact input formats and limits are specified in the protocol. Only operations advertised by the target device are accepted. Devices become offline after 15 seconds without registration/polling.

A lease lasts 60 seconds and progress renews it. Out-of-order valid progress reports renew the lease while retaining the highest reported progress. An expired lease can be reissued on the next poll with a fresh lease ID and reset progress. Old workers cannot complete or modify that lease. Cancellation is terminal and wins over subsequent completion. Revocation invalidates the worker credential and cancels its queued/running jobs; historical results remain in the local database. To erase all local records, stop the broker and delete its private configuration directory; this also destroys its identity and invalidates existing pairings.

Artifacts include SHA256 of canonical UTF-8 JSON output: sorted keys, no spaces, Unicode unescaped, no floating point output. The broker and CLI verify the digest. The broker also recomputes text analysis counters and text chunks from the stored input, rejecting forged output even with a matching digest. OCR results must have exactly text and lines fields, with text equal to the lines joined by LF; the broker does not independently rerun Vision. A digest proves content integrity, not that the result independently establishes factual truth.

MCP stdio

Configure the harness’s MCP server launcher with an absolute Python executable, script path, and private config path. For harnesses accepting the common mcpServers configuration shape:

{
  "mcpServers": {
    "companion": {
      "command": "/usr/bin/python3",
      "args": ["/absolute/path/companion.py", "--config", "/absolute/path/.harness-companion", "mcp"]
    }
  }
}

Choose a Python 3.10+ installation on your machine. The adapter communicates using newline delimited JSON-RPC on stdin/stdout and exposes companion_devices, companion_submit, companion_status, companion_cancel, and companion_artifact. Submit arguments are {id,deviceId,operation,input}; status/cancel/artifact arguments are {id}; devices takes {}. It supports initialize, initialized notification, ping, tools/list and tools/call. Configuration syntax differs by harness; this protocol adapter has been tested directly, without implying independent certification of every Codex, Claude Code, or OpenClaw version.

Both the CLI and app pin the exact broker leaf certificate. The CLI checks the pin before sending a bearer credential and follows no redirects. Never disable pin checks to work around a connection failure. JSON request/response size is limited to 2 MiB.

Verification

The release tests exercise a real HTTPS broker and native Swift client, authorization, role/device isolation, pin and redirect rejection, lease expiry, cancellation, payload bounds, artifact hashes and MCP framing.