BMCoCo-Pi 0.1.0rc3 · Linux console and model downloads; Windows planned.
Optional AI-agent control: the XRoar-AI connection
BMCoCo-Pi is not just an emulator you operate manually. Its XRoar-AI foundation and separate Pi remote-control interface also let a suitably equipped external AI agent observe and operate the emulated computer. This can turn a report such as “my BASIC program behaves incorrectly” into a shared session where the agent enters commands, examines the result and helps you investigate.
This is optional. You can enjoy CoCo/MC-10 software, use the OSD and manage the card through the Web UI without an AI agent. No language model runs on the Pi, and no agent credentials or API key belongs on its SD card. External agents need appropriate host-side tools and your permission; an ordinary chat window does not gain access to the Pi merely by knowing its IP. Requirements for an agent's own software/services are separate from ordinary BMCoCo-Pi operation.
Status checked 2026-10-16: AI control is an advanced, tool-driven workflow, not a released one-click AI companion. The Linux SD setup console is separate from this AI workflow. There is no built-in Web chat, automatic agent pairing or packaged Windows/Linux AI-control client promised by the current Setup downloads.
What makes XRoar-AI powerful?
XRoar-AI extends desktop XRoar with a controlled interface for development agents and automation tools. Instead of relying solely on mouse clicks or your description of a problem, a host-side agent can ask the emulator for structured observations and perform defined input operations.
Its desktop documentation describes a useful loop:
- Build a CoCo or MC-10 program on the development computer.
- Establish the intended emulated machine and load the appropriate media.
- Enter commands and run the program.
- Capture the rendered display or wait for a bounded screen-change condition.
- If needed, coordinate with the desktop GDB debugger to inspect CPU registers, memory, breakpoints or execution traces.
- Revise the program, rerun the test and compare the evidence.
That is valuable for BASIC, machine-language and other guest software, repeatable tests, demonstrations and learning. It is not a promise of an autonomous game player, a universal repair tool or correct diagnoses without verification.
One documented desktop example correlated an Oregon Trail graphics failure with BASIC program growth overwriting part of a machine-language renderer. Another followed Rogue through actual input/display transitions and debugger inspection. These illustrate why observing and controlling the same session is more useful than guessing from a single screenshot. They are desktop XRoar-AI examples, not tests reproduced on BMCoCo-Pi or included game downloads.
Desktop XRoar-AI versus BMCoCo-Pi
BMCoCo-Pi uses the XRoar-AI emulator foundation, but it does not run the desktop application, its command-line launcher, or its complete agent server. The bare-metal Pi has its own Web/private-LAN control and storage adapters. The interfaces and available operations are not interchangeable.
| Task | Desktop XRoar-AI | Current BMCoCo-Pi |
|---|---|---|
| Inspect session/machine state | Structured agent status/capabilities | Pi/guest status through supported remote tools and Web UI |
| Enter guest commands | Agent keyboard text and named-key/chord operations | Bounded remote typing through the Pi tools; not identical key APIs |
| Pause/resume and change configuration/media | Agent operations, subject to authority and capabilities | Supported Pi control/profile/media operations and shared OSD/Web validation |
| See the guest | Rendered frames, hashes and bounded change/stability waits | Guest-image captures; not OSD, whole HDMI, TV overscan or every desktop observation API |
| Debug CPU/memory or measure routine cycles | Separate coordinated GDB/debug/profiling tools | No equivalent exposed desktop debugger, breakpoint/watchpoint or cycle-budget interfaces |
| Save/restore running emulator state | Confined machine-state snapshot operations where supported | Profiles store configuration, not running guest RAM; no equivalent state-snapshot feature claimed |
| Connect an agent | Opt-in local loopback agent listener | Separate trusted-internal-LAN Pi interface, not the desktop protocol/listener |
In some Pi tools the word snapshot means an immutable screen-image copy,
not a save-state file. It cannot restore a program or machine after a reset.
A profile likewise references ROM/media paths; it does not contain those files
or preserve unsaved guest work. See profiles and media.
Do not paste desktop xroar-ai -agent-control ... launch options into BASIC,
the OSD or config.txt. Those instructions start the separate desktop program,
not the bare-metal Pi. Check actual capabilities rather than assuming a feature
is available because the names share “XRoar-AI.”
A sensible first assisted session
Start with a working guest and network using first boot. Before giving an agent permission to change anything:
- Specify the exact Pi and task. Ask it to identify the running build and guest, inspect control ownership, and explain the tools it intends to use.
- Ask for an observation first: status or a guest capture, with no reset, profile replacement, file write or kernel operation. Some advanced capture paths briefly claim/pause and restore the guest; do not assume all observation paths have identical timing or ownership effects.
- If you want input, approve a bounded action. For example, at an idle CoCo
BASIC prompt, ask it to enter
PRINT 23*19, verify437and release control. That arithmetic result has been checked on a Pi400. - Have the agent report what was observed, what changed, what remains uncertain and whether it has released/detached. A command being accepted is not proof that the guest produced the intended result.
For development, separately authorize source edits/builds on the PC, media updates, guest resets and writable image changes. Running a program, saving configuration, modifying media, updating a kernel and rebooting the whole Pi are different actions. Preserve backups and unsaved work first.
The existing Pi control client lives in the engineering repository. A polished end-user installation/connection guide for an AI companion still needs a supported client package and platform testing. This overview explains the capability without pretending a new connection wizard has already shipped.
You remain in control
Keep one controlling client/transfer active at a time. The Pi's local keyboard and F12/OSD have priority over remote mutation; if you take local control, the agent should stop, inspect the new state and not repeatedly reclaim authority. Leave local OSD before deliberately handing control back to remote tools.
The desktop agent listener is opt-in and loopback-only at the reviewed source. The Pi's current LAN service is different and unauthenticated. Use only a trusted internal LAN; do not expose/forward it to the Internet or assume that control ownership is authentication. Tool access may permit file changes, updates and reboot, so grant an agent only the scope needed for the task.
Agents see requested observations, not a continuous live video feed. Guest-only captures cannot establish what an OSD menu, television, speaker or controller physically did. Keep human/real-hardware checks where they matter. AI assistance does not replace program tests, evidence review or your judgment.
Further reading
Continue with the user guide or first boot. A packaged AI-client connection guide is not available yet; ordinary use does not require access to a source repository or an AI service.
Guide edition: November 2, 2026.