How to Use AxiOwl Across Multiple Computers

AxiOwl is designed first as a local Windows coordinator for AI provider sessions. It discovers provider chats on the machine, records them in a registry, sends messages to named sessions, and exposes MCP tools so providers can reply with their real session identity. That local-first model matters when you start thinking about multiple computers: AxiOwl should not blur machines together or silently turn a local failure into a remote one.

The current codebase does contain remote-node machinery. It can register SSH-accessible nodes, verify them, install a Linux-side payload, and relay a delivery request over ssh into axiowl relay-session --stdio. The important operational boundary is that the current provider support matrix still marks remote as unsupported for local-provider remediation builds. In plain English: remote routing exists as an explicit path under development, not as a general replacement for normal local provider support.

That distinction is the safest way to use AxiOwl across multiple computers today.

The Mental Model

Think of each computer as a node.

Your Windows computer is the local coordinator. It owns the local registry, local logs, local runtime files, and local provider integrations. The Windows app can know about local provider sessions such as Codex, VS Code, Cursor, and Antigravity, depending on what is installed and selected.

A remote Linux machine is a separate node. In the current implementation line, the Linux role is a remote Codex endpoint. The Windows README describes the split directly: the Windows build is the local coordinator, registry owner, and outbound SSH remote provider; the Linux build is a remote Codex endpoint and relay-session receiver for Codex CLI delivery only.

That means cross-computer use is not "install AxiOwl everywhere and assume every provider works everywhere." It is closer to:

1. Install and validate AxiOwl locally.
2. Register a remote node only when you intentionally want one.
3. Verify SSH access to that remote node.
4. Ensure the Linux remote has AxiOwl and Codex support installed.
5. Register a remote target explicitly.
6. Send to the remote target and inspect the receipt/proof.

Start With Local AxiOwl

The standard local command surface is simple:

axiowl status
axiowl list agents
axiowl send --to "Target chat name" --body "Message text"

The architecture docs describe the normal send path as:

user / provider MCP call / CLI
  -> axiowl.exe
  -> MCP or CLI command handler
  -> MessagePipeline
  -> registry target and sender resolution
  -> targeted discovery repair when needed
  -> provider_edges dispatch
  -> provider-specific delivery
  -> delivery logs and provider proof

This is still the foundation when more computers are involved. The local Windows registry needs to know what the target is, which node owns it, which provider edge should handle it, and what provider session identifier should be used.

The registry model includes display_name, aliases, provider, provider_session_id, node_id, sendable, source, last_seen_at, last_verified_at, and last_error. For multi-computer operation, node_id becomes the key field that separates local sessions from remote sessions.

Register A Remote Node Explicitly

AxiOwl has a node registry command for SSH-accessible machines:

axiowl node add --id "front" --host "example.host.or.ip" --ssh-user "ubuntu" --key "C:\path\to\ssh-key.pem" --name "Front Linux Node"

The older registry form is also present in the CLI:

axiowl registry add-node --id "front" --host "example.host.or.ip" --user "ubuntu" --key "C:\path\to\ssh-key.pem"

The implementation requires a node id, host, and SSH user. A key path is optional in the command shape, but in real operations it is normally how the Windows coordinator gets noninteractive SSH access.

After adding a node, list it:

axiowl node list

Then verify it:

axiowl node verify --id "front"

The verify command runs SSH with batch mode and a connection timeout, then executes:

hostname; whoami; pwd; hostname -I

That is deliberately basic. Before AxiOwl treats another computer as reachable, it should prove which host answered, which user answered, which directory the remote shell starts in, and what IP addresses the host reports.

Install The Remote Linux Payload

The Windows desktop README describes an MSI path that can enroll configured remote nodes, deploy the packaged Linux payload over SSH/SCP, run the remote Linux installer, and run remote discovery. The native axiowl-installer.exe helper performs that installer runtime work.

The Linux installer script shows what the remote side expects:

• sudo
• install
• codex
• an axiowl binary payload
• the bundled axiowl-codex Codex plugin payload
• a plugin manifest and MCP config

The script installs /usr/local/bin/axiowl, verifies axiowl --version, installs the Codex plugin under a local AxiOwl Codex root, registers a local Codex plugin marketplace, runs codex plugin add "axiowl-codex@axiowl", and probes the MCP server to confirm that axiowl_send_message appears in tools/list.

That tells you something practical: a remote Linux node is not just an SSH target. It must have the AxiOwl binary installed, Codex available, and the AxiOwl Codex MCP plugin registered so remote delivery can produce more than a shell-level handoff.

Register A Remote Target

Once a node is known, AxiOwl can record an agent row that points at that node:

axiowl registry add-agent --name "Remote Codex" --provider remote --node "front" --session "Remote Codex Session"

In the Windows README, the example is:

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

The implementation expects a remote registry row to have:

• provider=remote
• node_id matching a node in the node registry
• provider_session_id containing the remote target name

If those values are missing, the remote provider returns explicit errors such as "remote target is missing provider_session_id," "remote node is not in node registry," or "remote node is missing host or ssh_user." That is the right behavior. Cross-computer routing should fail loudly when the addressing information is incomplete.

What Happens During Remote Send

The remote provider code on Windows builds a JSONL relay input file, then runs SSH into the remote machine:

axiowl relay-session --stdio

The relay frame includes the target name, body, strict flag, sender resolution fields, and optional direct target provider fields. The Linux-side relay process reads JSON lines from stdin, handles hello and deliver frames, routes the message through the local remote AxiOwl pipeline, and writes a deliver_result JSON line back to stdout.

When the Windows side sees a deliver_result, it reports the remote request id, remote message id, remote provider, and remote detail. If the remote side emits upstream messages, the Windows coordinator can route those back through the local pipeline as well.

This design is useful because the remote protocol is explicit. It is not an open public port. It is an SSH command execution path into a known node, using stdio as the relay channel.

Know What Is Not Supported

The current remote docs and provider support matrix are intentionally conservative. They say remote is unsupported for local-provider remediation builds and should not be used as a fallback to hide local provider failures.

The Linux remote app is Codex CLI delivery only. It does not support VS Code, Antigravity, desktop IPC, GUI behavior, tray behavior, or remote relay chaining. The provider code also returns explicit unsupported results for non-Codex-style remote Linux surfaces.

That means you should not diagnose a broken local VS Code, Cursor, or Antigravity integration by routing around it through remote. Fix the local provider path locally. Use remote only when the target itself is truly remote and the remote node has the expected contract.

Receipts Versus Proof

AxiOwl's docs make a sharp distinction between receipt and proof. accepted_by_axiowl means AxiOwl accepted the request and handed it to the delivery layer. It does not prove the target provider displayed or processed the message.

For local providers, the strongest proof is a provider reply through AxiOwl MCP with correct provider-owned sender identity. For remote use, apply the same discipline: a clean SSH relay and deliver_result are important, but the best confirmation is still an actual provider-side response that comes back through AxiOwl with the right identity.

When operating across multiple machines, inspect:

• axiowl status
• axiowl list agents
• axiowl node list
• axiowl node verify --id "<node>"
• %LOCALAPPDATA%\AxiOwl\logs
• %LOCALAPPDATA%\AxiOwl\registry
• %LOCALAPPDATA%\AxiOwl\runtime

Those paths are part of the documented Windows runtime layout. They are where you look when a node is registered but not verified, a remote target is registered but not sendable, or a receipt does not match provider behavior.

A Practical Multi-Computer Workflow

Use this workflow when you want to test AxiOwl across a Windows coordinator and a Linux Codex node:

1. Confirm local AxiOwl works.

axiowl status
axiowl list agents

2. Confirm SSH works outside AxiOwl.

ssh -i "C:\path\to\ssh-key.pem" [email protected] "hostname; whoami; pwd; hostname -I"

3. Add the node to AxiOwl.

axiowl node add --id "linux-codex" --host "example.host.or.ip" --ssh-user "ubuntu" --key "C:\path\to\ssh-key.pem"

4. Verify the node through AxiOwl.

axiowl node verify --id "linux-codex"

5. Ensure the remote Linux side has axiowl, Codex, and the AxiOwl Codex plugin installed.

axiowl --version
codex plugin list

6. Register the remote target.

axiowl registry add-agent --name "Remote Codex" --provider remote --node "linux-codex" --session "Remote Codex"

7. Send a small test message.

axiowl send --to "Remote Codex" --body "Reply through AxiOwl with a short confirmation."

8. Treat the result as provisional until you see the provider-side reply path work.

Why This Matters

Multi-computer agent work is powerful, but it can become confusing quickly if the routing layer guesses. AxiOwl's current design keeps the important facts visible: which node owns the target, which provider owns the session, which SSH destination was used, which command ran remotely, and whether the receipt is only an AxiOwl handoff or a stronger provider proof.

That is the right operating stance for distributed AI sessions. Use local AxiOwl for local providers. Add remote nodes deliberately. Verify SSH identity before delivery. Keep remote Codex separate from local desktop surfaces. Read receipts carefully. And do not let remote routing hide a local provider problem that should be fixed at the source.