osmatrix-setup: host prerequisites, creating guests, troubleshooting

osmatrix gives agents local guests (an ubuntu container, windows/macos VMs, or any machine over ssh) and local GitHub Actions runs with act. This skill covers getting guests ready. Sibling skills in the same plugin: osmatrix-ci (run workflows locally) and osmatrix-guests (run commands, copy files, forward ports and drive the GUI inside a guest).

Use the MCP tools (host_doctor, env_setup, ...) when they are available: they are the supported interface, and their safety annotations let the client ask for confirmation where it matters.

If the osmatrix MCP tools are missing from this session, tell the user before doing anything else. Say that the osmatrix MCP server isn't loaded, so you'll use the osmatrix CLI instead, and suggest the likely fix: enable or restart the osmatrix MCP server in the client's MCP/plugin settings (a server that failed once may stay failed until it is toggled off and on). Then continue with the CLI: every tool has a matching command (see references/reference.md); add --json for machine output. Check osmatrix --version first; if the command isn't found, npx -y osmatrix@0 <command> works once osmatrix is published on npm. Otherwise tell the user it isn't installed, and stop.

First use

1. host_doctor (CLI: osmatrix doctor) checks prerequisites and explains why a guest can't run on this host (no Docker, no KVM, not Apple Silicon, ...). Each guest also has a compatibility: tested, untested (supported, but nobody has reported on this kind of host yet) or unsupported (see the matrix in references/reference.md). Mention an untested guest to the user before relying on it. Guests a host can't run may be configured as ssh guests pointing at another machine (below).
2. env_status (osmatrix status) lists the guests and their state.
3. Inside a devcontainer, Codespace or against a remote Docker daemon, host_doctor reports nesting. If the daemon is outside this environment (Docker-outside-of-Docker), local guests are refused because their ssh ports and bind mounts land on the Docker host, not here. Don't work around the refusal. Tell the user, and offer two options: an ssh guest (a real machine; works from anywhere), or running osmatrix on the Docker host. Linux CI legs still run, but artifact/cache steps may fail there. See "Devcontainers and remote Docker" in references/reference.md.

Guest states