How to Connect AxiOwl to Your First Provider

How to Connect AxiOwl to Your First Provider

Connecting AxiOwl to a provider means more than adding a shortcut or writing a config file. In the current AxiOwl implementation, the Windows runtime discovers provider sessions, records reachable chats in a local registry, sends messages through provider-specific edges, and expects replies to come back through AxiOwl MCP with enough metadata to identify the sending session.

That distinction matters for a first setup. A successful installer run proves that selected install actions completed. A working provider connection is stronger: AxiOwl can discover the session, target it by name, deliver a message, and receive a reply through MCP with correct provider-owned identity.

Choose A Supported First Provider

The current provider support matrix marks these surfaces as supported:

Several other provider surfaces are present as targets, but they should not be treated as the easiest first connection. Antigravity CLI, Claude Code CLI, OpenCode CLI, Copilot CLI, and Hermes-related surfaces are documented as target work because final support depends on metadata proof or additional provider-specific work. Cursor CLI is explicitly not a supported surface in the current matrix.

For a first provider, pick one already installed and authenticated on the machine. Codex agents are a good starting point when a local Codex session exists. VS Code or VS Code Copilot are good starting points when the VS Code host and MCP APIs are available. Cursor agents can work, but the Cursor path depends on a bridge extension and private patch-sensitive internals, so it is less forgiving as a first diagnostic target.

Install Only The Provider Feature You Mean To Use

AxiOwl's Windows MSI installs the local runtime under %LOCALAPPDATA%\AxiOwl, including bin\axiowl.exe, runtime directories, registry directories, logs, and selected provider integration files. Provider features are meant to behave like separate install units even though they are packaged in one installer.

The installer model is deliberately scoped:

For Codex agents, the installer installs Codex plugin or skill support and MCP integration. For VS Code and Copilot-in-VS-Code, it installs the AxiOwl VS Code bridge extension and MCP server definition, with patch logic when that feature is selected. For Cursor agents, it installs the Cursor bridge extension, Cursor MCP config, bridge registry/config, and the Cursor patch required for the glass.axiowlSubmitToAgent command path. For Antigravity agents, it configures Antigravity/Gemini MCP integration.

After install, restart the target app or open a new chat/thread before using the AxiOwl MCP tool. The project docs call this out for Codex and MCP-enabled hosts because existing sessions can hold stale transport or workspace state.

Check The Local Runtime

Once AxiOwl is installed, confirm that the CLI is available and that the runtime can see its local state:

axiowl status

The Windows command surface also includes:

axiowl list agents
axiowl discover all --json
axiowl doctor inventory

The discover command can be narrowed to a single provider:

axiowl discover codex --json
axiowl discover vscode-copilot --json
axiowl discover cursor --json
axiowl discover antigravity --json

Discovery is useful because AxiOwl's registry is the durable map of reachable provider sessions. A registry row includes the display name, aliases, provider, provider session id, node id, sendability, discovery source, and timestamps. When discovery finds a session, AxiOwl merges that evidence into the registry rather than relying only on manual names.

Confirm A Sendable Agent

After discovery, list registered agents:

axiowl list agents

The target name shown by list agents is what you use with send:

axiowl send --to "Target chat name" --body "Hello from AxiOwl. Reply briefly through AxiOwl MCP."

For longer messages, use stdin instead of squeezing everything into one shell argument:

Get-Content .\message.txt | axiowl send --to "Target chat name" --stdin

AxiOwl can also create provider sessions for supported create paths:

axiowl create --provider codex --name "New Codex Chat" --body "Start a new chat and answer briefly."
axiowl create --provider antigravity --name "New Antigravity Chat" --body "Start a new conversation."
axiowl create --provider vscode-native --name "New VS Code Native Chat" --body "Start a new native VS Code chat."
axiowl create --provider vscode-copilot --name "New VS Code Copilot Chat" --body "Start a new Copilot-backed VS Code chat."

Creation support depends on the provider edge returning a stable provider session id. If a provider accepts a create request but does not return stable session identity, AxiOwl should not pretend it has a sendable registry row.

Understand The Receipt Boundary

AxiOwl has a clear receipt boundary. accepted_by_axiowl means the runtime accepted and validated the request and handed it to the delivery layer. It does not, by itself, prove that the provider displayed, processed, or answered the message.

The stronger proof is a provider reply through AxiOwl MCP. That reply proves the target provider received the message, the AxiOwl MCP tool was available in that provider session, and AxiOwl could identify the replying session from provider metadata.

This is why first-provider setup should end with a real response, not just a green installer result. The support bar in the repo is explicit: discovery, install/config, send, provider receive, MCP reply, and correct sender identity all matter.

Where To Look When The First Connection Fails

Start with AxiOwl's own proof locations:

%LOCALAPPDATA%\AxiOwl\logs
%LOCALAPPDATA%\AxiOwl\registry
%LOCALAPPDATA%\AxiOwl\runtime

For MSI-level failures, collect a verbose Windows Installer log:

msiexec /i path\to\axiowl-activation-windows-installer.msi /l*v install.log

Common first-provider problems usually fall into a few categories:

For VS Code and Cursor, also check the provider extension output channels where bridge activation and command logs appear. For Cursor, be especially careful: the supported agent path uses a command JSON file, a bridge command watcher, glass.axiowlSubmitToAgent, and the Cursor agent/composer. If the patch-provided command is missing, sends should fail loudly.

A Practical First-Provider Workflow

The most reliable first setup is:

  1. Install and authenticate the provider app first.
  2. Run the AxiOwl MSI and select only the provider feature you intend to test.
  3. Restart the provider app or open a new provider chat/thread.
  4. Run axiowl status.
  5. Run provider-specific discovery, such as axiowl discover codex --json.
  6. Run axiowl list agents and choose a sendable target.
  7. Send a short message asking for a reply through AxiOwl MCP.
  8. Treat the setup as complete only after the reply comes back with correct sender identity.

That workflow matches the implementation model in the AxiOwl repo. AxiOwl is not just wiring provider names together. It is maintaining a local registry, using provider-specific delivery edges, recording logs and evidence, and relying on MCP metadata so replies route to real sessions rather than guessed display names.

Closing

Your first AxiOwl provider connection should be small, explicit, and provable. Pick one supported provider surface, let the installer configure only that feature, run discovery, send to a named registry target, and verify the MCP reply path. Once that loop works, adding a second provider becomes an operational step instead of a guessing exercise: AxiOwl already has the runtime, registry, and receipt boundaries in place.

Tagged , , , , , , , ,