Using AxiOwl for Cross-Node Deployment Workflows

Cross-node deployment work is where small mistakes become expensive. A command may start on a Windows workstation, hop over SSH to a Linux node, call a tool installed on that node, and then rely on a remote agent session to finish the job. AxiOwl is designed to make that kind of workflow less dependent on memory and ad hoc terminal notes by putting nodes, agents, delivery paths, and receipts into one explicit routing model.

In the current AxiOwl implementation, the Windows build acts as the local coordinator and registry owner. The Linux build is treated as a remote Codex endpoint: it receives relay sessions and delivers through Codex CLI on that machine. That split is important. AxiOwl is not trying to make every machine pretend to be the same environment. It keeps the coordinator role, the node registry, and the provider-specific delivery edge separate.

The Deployment Problem AxiOwl Targets

Many deployment workflows already use multiple agents informally. One agent inspects a frontend node. Another checks backend logs. A third works from the local workstation where the SSH keys and source checkout live. Without a routing layer, the operator has to remember which chat knows which machine, which terminal has the right key, and which agent can safely perform each step.

AxiOwl turns that into named routing. Its registry model maps a human-readable agent name to a provider, a provider session id, and a node id. The node registry separately stores remote node identity: node id, display name, aliases, host, SSH user, key path, enabled state, verification timestamps, and last error. That gives deployment work a durable inventory instead of a loose collection of shell history and chat titles.

The core user-facing send command stays small:

axiowl send --to "<agent>" --body "<message>"

For deployment instructions that contain multiline steps, JSON, quoted shell commands, or checklists, the documented pattern is stdin:

@'
<full deployment instruction>
'@ | axiowl send --to "<agent>" --stdin

That matters because deployment instructions are often damaged by shell quoting. AxiOwl's public contract keeps the message body as the sender's original content, then builds the final visible provider body inside the message pipeline.

Registering Remote Nodes Explicitly

The current CLI exposes remote node management commands:

axiowl node add --id <node-id> --host <host> --ssh-user <ssh-user> [--key <ssh-key-path>] [--name <display-name>] [--alias <alias>]
axiowl node list
axiowl node verify --id <node-id>

There is also a registry-compatible form:

axiowl registry add-node --id <node-id> --host <host> --user <ssh-user> [--key <ssh-key-path>] [--name <display-name>]

Verification is deliberately concrete. The node verification path runs an SSH command equivalent to:

hostname; whoami; pwd; hostname -I

If the SSH command succeeds, AxiOwl records the node as verified. If it fails, the node row keeps the failure reason in last_error. For deployment work, that is the difference between "I think this key works" and "this node was proven reachable through the configured route."

Routing a Deployment Task to a Remote Agent

Remote delivery uses a normal agent row with provider remote. The Windows README shows the manual setup pattern:

axiowl registry add-agent --name "Remote Test" --provider remote --node "front" --session "<remote agent name>"
axiowl send --to "Remote Test" --body "hello"

The remote agent row does not hide the real target. Its node_id points to the remote node, and its provider_session_id stores the remote target agent name or a provider-qualified remote address. When the Windows coordinator sends to that row, the remote provider code looks up the node in nodes.tsv, builds an SSH command with BatchMode=yes and a short connection timeout, and starts:

axiowl relay-session --stdio

on the remote machine.

The coordinator writes a temporary JSONL relay input file containing a hello frame and a deliver frame. The deliver frame includes the request id, target, final visible body, strict flag, and sender metadata when available. The remote side reads the frame from stdin, runs the local MessagePipeline, and returns a JSON deliver_result with fields such as state, target, provider, error, detail, and message id.

That relay design is useful for deployments because it preserves the operational boundary. The Windows coordinator does the routing and SSH hop. The Linux node performs local provider delivery using the provider sessions that actually exist on that node.

Installer Support for Remote Payloads

AxiOwl's Windows installer flow also has cross-node deployment behavior. The Windows desktop README states that the MSI installer enrolls configured remote nodes, deploys the packaged Linux payload over SSH/SCP, runs the remote Linux installer, and runs remote discovery. The implementation confirms the steps in native installer helper code rather than PowerShell glue.

The helper verifies remote node SSH access, adds verified nodes through AxiOwl's own node command, then checks that the packaged remote payload contains required files:

bin/axiowl
plugins/axiowl-codex/.codex-plugin/plugin.json
plugins/axiowl-codex/.mcp.json
installer/install-axiowl-remote-linux.sh

For each enabled node, it creates a tar archive, copies it to a temporary path on the remote host with scp, extracts it, runs the Linux installer script, and cleans the temporary stage afterward. This is not a replacement for a full infrastructure deployment system, but it is a concrete example of how AxiOwl treats remote nodes as managed targets rather than informal SSH destinations.

Discovery and Repair Across Nodes

AxiOwl does not rely only on manual registration. The message pipeline tries one targeted discovery repair when a target is missing from the registry. For remote Codex targets, discovery runs an SSH command against the node:

axiowl discover codex --json --target <target>

The remote discovery parser expects JSON lines with type equal to discovered_agent. It records discovered rows as provider remote, stores a provider-qualified session id, marks sendability only when the remote evidence supports it, and records evidence such as the remote provider and remote provider session id.

The important part is restraint. AxiOwl's developer docs say discovery should add and refresh sessions, enrich manual rows, and downgrade stale auto-discovered rows when proof disappears. It should not silently convert stale rows into sendable rows or hide provider delivery failures. That is exactly the posture deployment workflows need: repair what can be repaired, but make broken routing visible.

Receipts Are Operational Evidence, Not Wishful Thinking

AxiOwl's message pipeline uses explicit receipt states. The architecture docs distinguish between AxiOwl accepting a message, the provider accepting delivery, and a true response from the target agent. A send receipt must not claim that a recipient replied. A reply is a separate message.

For cross-node work, this distinction prevents false confidence. A remote send can fail because the node is missing from the node registry, the host or SSH user is empty, the SSH relay exits nonzero, the remote relay returns an error, or the remote provider fails. Those failures are surfaced in result state, error text, and evidence rather than being swallowed behind a generic success message.

The relay also supports upstream messages. If the remote side emits an upstream_message, the Windows coordinator can turn that into a local pipeline send back toward the original target. That creates a path for remote work to report back through AxiOwl instead of becoming a one-way instruction drop.

Current Boundaries Matter

The current source is explicit about what the Linux remote app supports: Codex CLI delivery only. It does not support VS Code, Antigravity, desktop IPC, GUI behavior, tray behavior, or remote relay chaining. The Windows coordinator has the outbound SSH remote provider. The Linux remote endpoint receives relay sessions and performs local Codex delivery.

Those boundaries are not a weakness in deployment operations. They are a safety feature. A cross-node deployment workflow should be able to say: this node can receive relay traffic, this provider edge is supported here, this target is sendable, and this failure is out of scope. Ambiguity is what causes the wrong machine to be changed.

A Practical Cross-Node Workflow

A realistic AxiOwl-assisted deployment workflow looks like this:

1. Register the Linux node with a stable node id, host, SSH user, and key path.
2. Verify the node through axiowl node verify --id <node-id>.
3. Register or discover the remote agent that will inspect or operate on that node.
4. Send the deployment instruction through axiowl send, using --stdin for multiline commands and checklists.
5. Read the receipt state and evidence before assuming the remote provider accepted the task.
6. Treat a response from the remote agent as a separate confirmation, not as something implied by the send command.

That workflow is intentionally plain. AxiOwl's architecture is built around one sender, one target, one body, one provider edge, and one receipt. Cross-node deployment does not need a hidden queue or a magical fallback to be useful. It needs a clear route, a verified node, a known provider session, and honest failure reporting.

Why This Helps Operators

The value of AxiOwl in deployment work is not that it replaces SSH, installers, or provider CLIs. It organizes them. SSH remains the transport for remote relay and remote payload installation. Codex CLI remains the Linux remote delivery provider. The registry remains the source of truth for names, node ids, provider session ids, and sendability.

For an operator, that means fewer manual hops and more inspectable state. You can list registered agents, list nodes, verify node reachability, send to a named remote target, and inspect the evidence log when something fails. For a developer, it means remote behavior lives behind a provider edge with a small contract instead of being scattered through unrelated scripts.

AxiOwl's cross-node deployment story is therefore practical: keep the coordinator local, make remote nodes explicit, use SSH for the relay boundary, run provider delivery on the node where the provider session lives, and return receipts that say exactly what happened. That is the kind of boring machinery deployment workflows need.