Common First-Time AxiOwl Setup Problems

Common First-Time AxiOwl Setup Problems

AxiOwl setup is not just "install an app and send a message." The current C++ implementation is a local Windows coordinator that installs axiowl.exe, keeps a durable local registry, discovers supported provider sessions, configures selected provider integrations, and exposes both a CLI and an MCP server. First-time problems usually come from confusing one of those layers with another.

The good news is that AxiOwl is designed to leave evidence. The Windows install writes state under %LOCALAPPDATA%\AxiOwl, the CLI has direct inspection commands, and the receipt language separates "AxiOwl accepted the request" from "the provider actually replied." When a first setup does not work, start with those boundaries instead of guessing.

Problem 1: Expecting Every Provider Checkbox To Work Automatically

The Windows MSI has provider checkboxes, but those checkboxes are not magic support switches. The installer docs say provider checkboxes should be selected from discovery: the provider app or CLI must be detected, the required install path must exist, and the provider-specific support gate must allow that feature.

This matters because AxiOwl's provider support bar is higher than "a config file was written." Current supported surfaces include Codex agents, Codex CLI, VS Code native agents, VS Code Copilot through the bridge extension, Cursor agents, and Antigravity agents. Several CLI surfaces are still listed as target, meaning intended or partially implemented support exists but the current test bar is not fully met.

If a provider is not preselected, first assume discovery did not find a safe install target. You can manually select a provider feature, but the user docs are clear that a selected provider can still fail if the provider app, CLI, auth state, or required version is missing.

After install, use:

axiowl status
axiowl list agents
axiowl discover all --json

Those commands tell you more than the checkbox screen. status summarizes the local AxiOwl state, list agents reads the local registry, and discover all --json asks the discovery layer to refresh what it can see.

Problem 2: Thinking A Successful MSI Install Proves Message Delivery

A successful install proves selected install actions completed. It does not prove that a provider can receive a message, process it, and reply through AxiOwl MCP.

The repo draws this line repeatedly. AxiOwl has receipt states such as accepted_by_axiowl and provider-side proof such as accepted_by_provider, but the strongest end-to-end proof is a provider reply through AxiOwl MCP with correct sender identity. The MCP tool description in the implementation says the axiowl_send_message success is a handoff receipt only; provider delivery and reply are not implied.

So a first-time validation should not stop at "installer completed." A better sequence is:

axiowl status
axiowl list agents
axiowl send --to "Target chat name" --body "Please reply through AxiOwl with a short setup test response." --from "Known sender"

For provider-hosted replies, prefer the axiowl_send_message MCP tool rather than asking the provider to invent raw CLI arguments. The MCP path carries provider/session identity metadata, which AxiOwl needs to route replies correctly.

Problem 3: Sending To A Name That Is Not In The Registry

AxiOwl sends to named provider sessions through its registry. The architecture docs describe the registry as the map from human-readable agent names and aliases to provider, provider session id, node id, sendability, and discovery source.

If the target name is missing or stale, the message pipeline runs one targeted discovery repair. The implementation logs that repair as targeted_discovery_once. That is useful, but it is not a promise that the target exists. Discovery can find candidate sessions; it cannot invent a real provider session.

The practical fix is to inspect the registry before sending:

axiowl list agents

Then send to a displayed name or alias that AxiOwl actually knows:

axiowl send --to "Exact agent name from list agents" --body "Setup test." --from "Known sender"

If a provider session was opened after install, run the relevant discovery scope:

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

Use axiowl discover all --json when you do not know which provider surface should own the session.

Problem 4: Missing Sender Identity

First-time CLI tests often fail because they specify a target and body but do not give AxiOwl a real sender. The message pipeline can reject a send with an error shaped like "send requires explicit –from sender identity" when sender identity cannot be resolved.

That behavior is intentional. AxiOwl appends reply instructions only when it knows who the recipient should reply to. The developer docs say provider replies must include enough metadata for AxiOwl to identify the sender session, and the MCP server should fail loudly when metadata is missing.

For a raw CLI test, pass a sender that exists in the registry:

axiowl send --to "Target chat name" --body "Setup test." --from "Sender chat name"

For multiline content, use stdin so quoting does not damage the body:

@'
Please run a first-time AxiOwl setup test.
Reply through AxiOwl if your MCP tool is available.
'@ | axiowl send --to "Target chat name" --stdin --from "Sender chat name"

For provider-to-provider replies, use the MCP tool path. The current MCP server exposes axiowl_send_message, and its implementation uses the host MCP session id as the stable sender identity key. That is the right path for real replies because the provider host supplies identity metadata that a plain terminal command cannot infer.

Problem 5: Forgetting To Restart The Target Provider

Some integrations are installed into provider configuration or provider extension locations. The Windows desktop README notes that after install, users should restart the target app or open a new chat/thread before using the AxiOwl MCP tool.

This is especially important for supported surfaces that depend on MCP config, a bridge extension, or provider-private patch behavior:

If AxiOwl installed cleanly but the provider cannot see the tool, restart the provider app or open a fresh chat/session before diagnosing deeper. Existing sessions can hold stale MCP transport or stale workspace state.

Problem 6: Looking In The Wrong Place For Logs

The current Windows state root is %LOCALAPPDATA%\AxiOwl. The repo's path code and installer docs identify these first diagnostic locations:

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

The concrete files include registry data such as:

%LOCALAPPDATA%\AxiOwl\registry\agents.tsv
%LOCALAPPDATA%\AxiOwl\registry\nodes.tsv

And runtime evidence such as:

%LOCALAPPDATA%\AxiOwl\logs\events.jsonl
%LOCALAPPDATA%\AxiOwl\logs\delivery.jsonl
%LOCALAPPDATA%\AxiOwl\logs\create-lifecycle.jsonl

For MSI-level diagnosis, the installer docs recommend collecting a verbose Windows Installer log:

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

That gives you two different views: Windows Installer action logs and AxiOwl's own runtime/provider evidence logs.

Problem 7: Treating Stale Provider State As An AxiOwl Delivery Failure

The installer docs call out a specific confusing symptom: an old folder appears in a new chat. That can be stale provider workspace/session state, stale config, or provider default behavior. It is not automatically proof that AxiOwl delivery failed.

The same applies to old extension folders, stale bridge entries, and old provider sessions. The MSI may remove stale AxiOwl-owned files such as old bridge extension folders or obsolete runtime artifacts, but it should not remove unrelated provider files, user chats, auth tokens, unrelated extensions, or unrelated settings.

That boundary is important. AxiOwl is supposed to clean up what it owns, not wipe out provider state. When a first setup looks stale, check:

axiowl status
axiowl list agents
axiowl discover all --json

Then inspect %LOCALAPPDATA%\AxiOwl\logs and provider extension output channels before assuming the send path is wrong.

Problem 8: Misreading Cursor Or VS Code Extension Warnings

Cursor and VS Code integrations are more fragile than simple CLI config because they can depend on editor extensions, MCP definitions, and patch-sensitive provider internals. The installer docs specifically mention an extension not found warning as a possible stale provider extension id/path or URI wake-up fallback behavior.

The provider support matrix also notes that Cursor URI wake-up can show false extension warnings and should remain fallback. Cursor's primary supported path is the bridge command-file watcher plus patch-provided commands; URI wake-up is not the ideal path when the watcher works.

For first-time setup, do not stop at one warning string. Check whether the provider actually receives the message and whether a reply returns through AxiOwl MCP. That is the support bar.

Problem 9: Using Remote As A Local Provider Fallback

Remote support is not a general fallback for local setup failures. The current provider support matrix lists remote as unsupported for local-provider remediation builds, and the CLI implementation reports remote discovery as out of scope for local all-provider discovery.

If local Codex, VS Code, Cursor, or Antigravity setup fails, fix that local provider path. Do not route around it through remote discovery unless you are intentionally testing the remote Linux package and its narrower contract.

A Practical First-Time Checklist

Use this sequence when setting up AxiOwl for the first time:

  1. Install the Windows MSI and select only the provider features you actually want to integrate.
  2. Restart the selected provider app, or open a new provider chat/thread.
  3. Run axiowl status.
  4. Run axiowl discover all --json.
  5. Run axiowl list agents.
  6. Send a small test to a known registry name.
  7. Confirm whether the result is only accepted_by_axiowl, provider-accepted, or a true reply through AxiOwl MCP.
  8. If it fails, read %LOCALAPPDATA%\AxiOwl\logs, %LOCALAPPDATA%\AxiOwl\registry, and %LOCALAPPDATA%\AxiOwl\runtime.
  9. For installer-level failures, collect an MSI verbose log with msiexec /l*v.

The key habit is to separate installation, discovery, registry resolution, provider delivery, and MCP reply proof. AxiOwl's implementation treats those as different stages, and first-time troubleshooting is much easier when you do the same.

Closing

Most first-time AxiOwl setup problems are not mysterious. They usually mean one of the required pieces is missing: the provider was not discovered, the provider feature was selected without a working provider install, the target name is not in the registry, the sender identity is unresolved, the provider session has stale MCP state, or the operator is reading a handoff receipt as an end-to-end reply.

AxiOwl gives you the tools to sort those out: axiowl status, axiowl discover, axiowl list agents, honest receipt states, and local evidence under %LOCALAPPDATA%\AxiOwl. Start there, and treat a provider reply through AxiOwl MCP as the real proof that setup is working.

Tagged , , , , , ,