The host harness, tools/vios_harness.py, connects your Mac to the board. It is the only program that opens the board's USB serial port. Everything else on the Mac reaches the board through it: the human CLI (tools/vios_cli.py), MCP clients such as Claude, and the on-board acceptance suite. VIOS runs fine without it. You need the harness only when you want to drive the board from the Mac.

How it fits together

  MCP client (Claude)   tools/vios_cli.py   acceptance scripts
        |  stdio              |  TCP               |  TCP
        |  (via nc)           |                    |
        +-------------+-------+--------------------+
                      |  newline-delimited JSON-RPC on 127.0.0.1:8765
              tools/vios_harness.py   (one process, one lock)
                      |  COBS/CRC frames, 115200 8N1
              /dev/cu.usbserial-XXX  (CH340 on the board)
                      |
              ESP32 USB multiplexer -> eZ80 Forth REPL, supervisor, events

• One serial owner. The harness opens the port once and keeps it open. All tool calls go through one lock, so requests from the CLI and from Claude never interleave on the wire. Do not open the port with anything else while the harness runs. That includes a serial terminal, esptool, tools/vios_firmware_ab.py and tools/vios_sd_refresh.py. The port is opened exclusively, so a second opener fails anyway.
• Opening the port resets the board. On this board, opening the USB serial device resets it. The first connect can therefore take a full boot (allow up to 120 s), and every harness restart is also a board restart. Unsaved RAM work is lost when that happens.
• Two front ends. With --tcp 127.0.0.1:8765 the harness serves newline-delimited JSON-RPC (one JSON object per line) on loopback TCP. Several clients can connect at once and share the board. Without --tcp it speaks MCP over its own stdin/stdout, and only that one client can use it.
• Loopback only, no authentication. The TCP server refuses any bind address other than 127.0.0.1. Anyone who can open a socket on your Mac can drive the board, so do not forward this port.
• The protocol. It is JSON-RPC 2.0 with MCP lifecycle version 2025-11-25. On TCP the transport is a plain line protocol, not MCP Streamable HTTP. Frames are limited to 1 MiB.
• JSON stays on the Mac. The board never parses JSON. Over USB the harness and the ESP32 exchange compact binary frames: console, control, events, host-file requests and link requests each have their own channel. See Architecture.

Starting the harness

Find the board's port first, then start the harness against it:

ls /dev/cu.usbserial-*
lsof /dev/cu.usbserial-210                 # must print nothing: nobody owns the port
lsof -nP -iTCP:8765 -sTCP:LISTEN           # must print nothing: no harness running

.venv/bin/python tools/vios_harness.py --backend resident \
    --port /dev/cu.usbserial-210 --tcp 127.0.0.1:8765

The harness prints VIOS /host/ serves /Users/you/VIOS-host and VIOS TCP listening on 127.0.0.1:8765 on stderr. It does not touch the board until a client calls connect.

Always pass --port. The default (/dev/cu.usbserial-224130) is a suffix from an earlier USB setup. The suffix changes with the USB socket or hub you use, so check ls /dev/cu.usbserial-* each time.

Stop the harness with Ctrl+C. When TCP clients disconnect, the harness and the board session keep running.

Connecting Claude (MCP)

The simplest arrangement is one TCP harness shared by you and Claude. Claude's MCP stdio is bridged to the running harness with nc. The bridge opens no serial port of its own:

{
  "mcpServers": {
    "vios": {
      "command": "/usr/bin/nc",
      "args": ["127.0.0.1", "8765"]
    }
  }
}

If no human CLI is needed, the harness can be the MCP server itself. Stop any TCP harness first, because two owners cannot share the port. Use absolute paths:

{
  "mcpServers": {
    "vios": {
      "command": "/path/to/agon-light-2/.venv/bin/python",
      "args": ["/path/to/agon-light-2/tools/vios_harness.py",
               "--backend", "resident", "--port", "/dev/cu.usbserial-210"]
    }
  }
}

The client's first board call must be connect. Listing tools does not open the port.

A raw TCP session looks like this, one JSON object per line:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"me","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"connect","arguments":{}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"evaluate","arguments":{"source":": SQUARE DUP * ;\n7 SQUARE . CR"}}}

Each tool result is a JSON document carried in one text content item. isError is true when the tool failed or the Forth code raised an error. Malformed requests or arguments get JSON-RPC errors. The schemas returned by tools/list are the authority for argument limits.

The CLI

tools/vios_cli.py is a plain terminal console that attaches to the TCP harness:

.venv/bin/python tools/vios_cli.py                 # harness on 127.0.0.1:8765
.venv/bin/python tools/vios_cli.py --port 8765 --timeout 30

Its --port is the TCP port of the harness (default 8765), not the serial device. The CLI has no serial code at all. The other flags are --timeout and --rpc-timeout. --timeout (default 15 s, at most 300) is how long one Forth line may run before the CLI reports it as pending. --rpc-timeout (default 130 s) is how long the CLI waits for any harness reply, and it covers a full board boot.

On start the CLI calls connect and prints VIOS console — :help for commands. Then you type Forth lines. Each line is at most 235 printable ASCII bytes, and tabs become spaces. The prompt shows the session state:

Tab completes words from the live dictionary. Lines that start with : are CLI commands:

Two rules keep the CLI honest:

• It never retries. If a request fails halfway, the CLI says so and leaves the result marked uncertain. It never sends the request again.
• Pending execution blocks new source. KEY gets only the bytes you send with :input.

:recover differs with and without the ZDI wire. With the wire (dev boot), the supervisor halts the eZ80 and reloads the image embedded in the ESP firmware, so all RAM state is gone. Without the wire (untethered boot), the ESP cannot reset the eZ80. :recover then restarts only the ESP32: the resident keeps running with its RAM state, reports itself healthy again when the ESP comes back, and the harness reattaches. If the eZ80 itself is wedged, stop and restart the harness (opening the port resets the whole board) or press the board's reset button. See Troubleshooting.

MCP tool reference

The harness registers 72 tools. Tools marked wire need the ZDI recovery links (a dev boot). On an untethered board the ESP cannot reach the eZ80's debug port.

Session and recovery

Running Forth

Inspection

Modules and persistence

SD card

Workbench (text editor)

These are the headless equivalents of the workbench keys. Edits are checked against the draft revision so that a stale client cannot overwrite newer work.

ESP32 side (display, keyboard, audio, link)

These read the ESP32 directly over the control channel. The eZ80 keeps running and is not involved.

Sharing files with the board: /host/

While the harness runs with the resident backend, any path that starts with /host/ on the board refers to a file under --host-root on your Mac (default ~/VIOS-host, created if missing). You can edit on the Mac and run on the Agon:

LOAD /host/app.fth

OPEN, READ, WRITE and CLOSE work on /host/ paths too, like SD paths (see Handles, Pipes and Devices). The service has these limits:

• Paths are relative to the host root. Absolute paths, .. and symlinks that leave the root are refused.
• At most four host files are open at a time.
• Each board request carries at most 240 bytes and waits about one second for the Mac's reply.
• /host/ exists only while the harness is running and idle enough to answer. Without the harness the board reports an error for /host/ paths. Everything else keeps working.

Snapshots and resync

• snapshot (CLI :snapshot FILE) records what is live, dirty, staged and persisted: every module with its exact source, the editor draft, the stacks, BASE, the engine and the boot slot. Take one before anything risky, such as a reboot, a firmware install or an experiment. The persisted flag means the module's exact name and CRC32 are in the confirmed boot bundle on SD, so a power cycle brings it back. RAM-only definitions are not persisted.
• resync (CLI :resync) re-establishes framing when a reply was lost. One example is a byte from the physical keyboard merging into a request. It works only at a quiet idle prompt and never resends the request, because that request may or may not have run.

The USB link itself already recovers lost frames: the ESP numbers every frame it sends and resends frames on request (see Architecture). The harness also repeats one read-only tool once after a resync: snapshot, tasks, handles, last_error, sd_list, sd_get, boot_status, boot_manifest, esp_stats or esp_console. Such results carry wire_loss_recovered: true. Mutating tools are never repeated.

The on-board acceptance suite

tools/vios_board_suite.py runs the acceptance checks on the real board through the TCP harness on 127.0.0.1:8765. Start the harness first (as above), with the board booted into the GUI. The suite has no serial-port option of its own.

.venv/bin/python tools/vios_board_suite.py build/suite-$(date +%Y%m%d)
.venv/bin/python tools/vios_board_suite.py build/suite-gui --only gui,gui_tools
.venv/bin/python tools/vios_board_suite.py build/suite-soak --soak-minutes 30

Each check writes its own JSON report into the output directory. The runner writes suite.json with one status per check and exits non-zero if any check failed. Checks that need an idle task table pause and later restart a running AUTORUN task.

None of the default checks changes the boot slots, saved modules or the workbench draft. They define temporary RAM words, so take a snapshot first if your RAM session matters. --soak-minutes N adds tools/vios_soak.py afterwards. The soak repeats REPL arithmetic, a snapshot, a 1000-byte pipeline, an editor round trip and, every tenth iteration, an SD round trip, and it stops at the first failure. On firmware main-51 all nine default checks pass.

A few older drivers open the serial port themselves, so stop the harness before you run them. Each takes --port:

• tools/vios_resident_acceptance.py. Its boot phase changes the SD boot slots and refuses a card with a confirmed user bundle.
• tools/vios_resident_recovery.py --exercise-resets. This deliberately discards RAM state.
• tools/vios_coldboot_capture.py. This records cold boots without sending anything.