How to Install AxiOwl for the First Time

How to Install AxiOwl for the First Time

AxiOwl is installed as a local coordinator for supported AI provider sessions. On Windows, the current first-time install path is the AxiOwl MSI. That installer places the AxiOwl runtime on the machine, adds the command-line tool, writes local state under the user's AxiOwl data directory, and installs only the provider integrations that are selected during setup.

The important thing to understand before installing is that AxiOwl is not a replacement for Codex, Cursor, VS Code, Antigravity, Claude Code, or other provider surfaces. It connects supported provider sessions so they can discover each other, send messages, and reply through the AxiOwl MCP path when that provider has been configured correctly.

Before You Run the Installer

Start with the Windows MSI built by the AxiOwl project. In the current repo, the MSI artifact is named:

release\axiowl-activation-windows-installer.msi

The build proof in the repo identifies the current activation package as 2.0.30, built from the Windows desktop target. The installed command-line executable itself reports axiowl 0.1.0 in the current CLI source, so do not treat the CLI version string and MSI package version as the same thing.

Before running the MSI, decide which provider integrations you actually want AxiOwl to configure. The installer is designed around provider checkboxes. Core AxiOwl installs once, but each provider feature is supposed to behave like its own install unit.

Current provider surfaces in the support matrix include supported paths for Codex agents, Codex CLI, VS Code agents, Copilot in VS Code, Cursor agents, and Antigravity agents. Several CLI surfaces, including Claude Code CLI, OpenCode CLI, Copilot CLI, Antigravity CLI, and Hermes-related work, are marked as target rather than fully supported. That distinction matters: a provider being present in the installer or CLI help does not automatically mean its full send, receive, MCP reply, and sender-identity path has met the current support bar.

What the MSI Installs

The core install places AxiOwl under:

%LOCALAPPDATA%\AxiOwl

The documented core payload includes:

%LOCALAPPDATA%\AxiOwl\bin\axiowl.exe
%LOCALAPPDATA%\AxiOwl\manifest.json
%LOCALAPPDATA%\AxiOwl\logs
%LOCALAPPDATA%\AxiOwl\registry
%LOCALAPPDATA%\AxiOwl\runtime

The runtime code also uses these local state paths:

%LOCALAPPDATA%\AxiOwl\registry\agents.tsv
%LOCALAPPDATA%\AxiOwl\registry\nodes.tsv
%LOCALAPPDATA%\AxiOwl\logs\events.jsonl
%LOCALAPPDATA%\AxiOwl\logs\delivery.jsonl
%LOCALAPPDATA%\AxiOwl\logs\create-lifecycle.jsonl
%LOCALAPPDATA%\AxiOwl\license\activation.json
%LOCALAPPDATA%\AxiOwl\logs\activation.jsonl

Depending on the selected provider features, the MSI can also install or configure MCP entries, bridge extensions, provider patches, CLI config, discovery records, and AxiOwl-owned wrapper or config files. For example, the installer behavior matrix lists separate feature handling for Codex plugin support, VS Code bridge extensions and MCP definitions, Cursor bridge and patch support, Antigravity/Gemini MCP config, Claude MCP config, Copilot CLI patch work, and remote features.

Remote features exist in the installer surface, but the matrix says remote is unchecked by default and is not part of the local-provider remediation path. For a first install focused on local provider messaging, keep remote unchecked unless you are intentionally configuring remote nodes.

Choosing Provider Checkboxes

The installer is designed to preselect provider checkboxes based on discovery, not stale assumptions. A checkbox should be selected when the provider app or CLI is detected, the required install path exists, the support gate allows the feature, and the feature is not remote-only or unsupported by default.

Manual selection is still possible, but it is not magic. If you select a provider that is missing its app, CLI, authentication, version, or required local state, that provider integration may fail loudly. That is expected behavior. The installer's job is not to pretend a provider is available; it should either configure the selected path safely or make the failure visible.

The installer safety rules are also explicit about what unchecked providers should not experience. An unchecked provider feature should not be installed, patched, closed, restarted, removed, or cleaned up as collateral damage. The safety checks in the repo verify that unchecked providers do not schedule provider removal actions and that provider-specific install steps require explicit selected-module flags.

Practically, first-time users should follow this rule:

Select only the provider surfaces you want AxiOwl to integrate on this machine.

If you use Codex and Cursor, select those. If you use VS Code with Copilot, select the relevant VS Code option. If you do not use a provider, leave it unchecked.

Running the Install

For a normal first-time install, run the MSI and follow the provider setup dialog. Windows may ask for elevation because some provider actions, especially patch-sensitive editor or CLI work, can require elevated installer custom actions.

The repo also contains a headless installer wrapper for development and automation:

.\apps\windows-desktop\installer\install-axiowl-headless.ps1

That wrapper starts an elevated worker and shows one UAC prompt. The elevated worker can build or reuse the local build output, stage axiowl.exe, axiowl-installer.exe, VS Code bridge payloads, optional Codex plugin payloads, and then run native helper install steps such as prepare, local-exe, path, mcp-wrapper, provider-specific extension/MCP/patch steps, local-discovery-core, and finalize.

For ordinary users, the MSI is the supported shape. The headless script is useful context for what the installer does internally, but it is not the clearest first-install path unless you are developing or testing the installer itself.

Verify the Install

After the MSI finishes, open a new PowerShell window so any PATH change is visible, then run:

axiowl status

The status command reports the state root, registry path, node registry path, evidence log, delivery log, create lifecycle log, artifact manifest, artifact source commit, package version, product code, installed executable path, installed executable hash, license state, activation endpoint, local service endpoint, runtime role, registered agent count, and registered node count.

You can also confirm the CLI is available:

axiowl --version

And you can inspect discovered provider rows:

axiowl list agents

If you need to refresh discovery for a provider, the CLI supports discovery scopes such as:

axiowl discover codex
axiowl discover codex-cli
axiowl discover vscode-native
axiowl discover vscode-copilot
axiowl discover cursor
axiowl discover antigravity
axiowl discover all

The command surface also includes:

axiowl doctor inventory
axiowl provider smoke-test --all-local --report

Those commands matter because installation is not the same thing as end-to-end provider proof.

What a Successful Install Does Not Prove

The AxiOwl docs are careful about receipts. A successful MSI install proves that selected install actions completed. It does not prove that every provider displayed a message, processed a message, or replied correctly.

Likewise, an accepted_by_axiowl receipt means AxiOwl accepted the request and handed it to the delivery layer. It does not, by itself, prove that the target provider displayed or processed the message.

The stronger proof is a provider reply through AxiOwl MCP with the correct sender identity. The support matrix defines the full support bar as discovery, selected integration install/config, send to a named provider session, provider receive, provider MCP reply, and correct provider-owned sender identity.

That is why a first install should end with a real provider test, not just a green installer screen.

Sending a First Message

Once at least one provider session has been discovered and registered as sendable, the basic command form is:

axiowl send --to "Target chat name" --body "Message text"

For longer text, use stdin:

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

The CLI also supports an explicit sender:

axiowl send --to "Target chat name" --body "Message text" --from "Sender chat name"

Provider sessions can also reply through the axiowl_send_message MCP tool when the provider integration exposes it. That MCP reply path is preferred for provider replies because it carries provider/session identity metadata.

Where to Look if Something Fails

Start with the local AxiOwl state directory:

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

For MSI-level diagnosis, collect a verbose installer log:

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

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

Those are operational signals, not reasons to guess. The logs and registry files are designed to make the state inspectable.

Closing Checklist

For a clean first install, use the MSI, select only the provider integrations you want, and verify the result from PowerShell.

The minimum practical checklist is:

1. Run the Windows MSI.
2. Review provider checkboxes before continuing.
3. Let the installer complete selected provider setup.
4. Open a new PowerShell window.
5. Run axiowl status.
6. Run axiowl list agents.
7. Run discovery or inventory doctor if expected providers are missing.
8. Send a real test message.
9. Confirm the provider can reply through AxiOwl MCP when that provider path supports it.

AxiOwl's install process is intentionally concrete: it installs a local runtime, records local registry and evidence files, configures selected provider surfaces, and gives you CLI commands to inspect what happened. Treat the installer as the setup step, then use discovery, inventory, logs, and a real reply test to prove the machine is ready for AxiOwl messaging.

Tagged , , , , , , ,