AxiOwl Security Model Explained

AxiOwl is designed as a local coordinator for AI provider sessions. Its security model starts from that constraint: the tool should know which local provider sessions exist, route messages only to selected and registered targets, preserve enough identity metadata for replies, and make failures visible instead of pretending a weak path is supported.

That model matters because agent-to-agent messaging can easily become ambiguous. A display name can be stale. A chat session can move. A provider may accept a config file but still fail to receive a message. AxiOwl treats those cases as operational facts to prove, log, and surface, not as details to hide behind a generic success message.

Local First, Selected Integrations Only

The current AxiOwl runtime is centered on a Windows executable, axiowl.exe, with local registry, logs, runtime state, provider discovery, provider-specific delivery modules, and an MCP server. On Windows, local AxiOwl state lives under %LOCALAPPDATA%\AxiOwl; on non-Windows systems the source uses $XDG_STATE_HOME/axiowl or ~/.axiowl.

The security docs define what AxiOwl may read: provider session metadata, provider config files, chat/session indexes needed for discovery, AxiOwl registry/log/runtime files, selected provider install paths, activation state, and installer payload provenance. The same docs also define what AxiOwl may write: its installed binary, manifest, logs, registry, runtime files, selected MCP config, selected bridge extension files, selected patch changes, and AxiOwl-owned provider config entries.

The boundary is just as important as the allowed list. AxiOwl should not touch unrelated provider extensions, auth tokens, unrelated provider settings, unrelated workspace files, provider chats except by sending user-requested messages, unchecked provider surfaces, or remote configuration unless that remote behavior is explicitly selected.

Registry As A Routing Boundary

AxiOwl does not route only by whatever name a user typed most recently. It keeps a durable local registry of provider sessions in registry/agents.tsv. Registry rows include a display name, aliases, provider, provider-owned session id, node id, enabled/sendable flags, discovery source, timestamps, and the last known error.

That registry is a security boundary because it decides what is sendable. The developer docs are explicit: a row should not be marked sendable unless discovery or direct proof justifies it, and stale paths or stale display names should not become stronger than provider-owned session ids.

The implementation follows that idea when resolving send targets. A message must have a target and a non-empty body. AxiOwl looks for a registered target, runs one targeted discovery repair when needed, rejects targets that remain missing, and rejects known targets marked not sendable. This keeps discovery useful without letting discovery become a silent excuse for unsafe routing.

Sender Identity Is Required

Reply routing depends on knowing who sent the message. For MCP use, AxiOwl expects provider/session metadata from the host, not a guessed name. The MCP server instructions tell providers to use typed tools such as axiowl_send_message and not to construct raw send commands or invent a session id.

The architecture docs describe the sender identity priority: provider-owned MCP metadata first, then an explicit provider session id matching a registry row, then an explicit sender address or alias matching a registry row, then targeted discovery repair. The code also protects against raw session identifiers being mistaken for good human-facing names. If a sender session id cannot be resolved to a registered sender, the send is rejected rather than routed under a guessed identity.

This is why AxiOwl treats environment-only identity injection as insufficient for final CLI provider support. Environment variables can be useful during integration, but the support bar requires provider-owned metadata or an equivalent provider-supported path.

Receipts Are Scoped On Purpose

AxiOwl separates its own handoff receipt from real provider delivery proof. The architecture docs define accepted_by_axiowl as AxiOwl accepting and validating a request and handing it to the delivery layer. That is not the same thing as the target provider displaying or processing the message.

The code reinforces that boundary. The message pipeline records an "accepted" stage when a request enters the pipeline, then later records target resolution, route resolution, delivery worker handoff, and provider write stages. The MCP tool description for axiowl_send_message says success is an MCP-to-AxiOwl handoff receipt only; provider delivery and reply are not implied.

The strongest proof is a provider response through AxiOwl MCP with correct sender identity. That proves more than local acceptance: the provider received the message, had AxiOwl MCP available, replied through AxiOwl, and carried identity metadata that could be mapped back to the correct session.

Provider Features Are Isolated

The installer model is also part of the security model. The installer behavior matrix says the MSI installs AxiOwl once, but each provider feature should behave like a separate install unit. Provider checkboxes should come from discovery or explicit user selection, not stale assumptions.

Unchecked provider features should not be installed, patched, closed, restarted, removed, or cleaned as collateral damage. Selected provider actions should fail loudly if they cannot be installed safely. The implementation includes guard logic for provider feature ownership, selected-provider action gating, patch registry declarations, classify-before-write patching, idempotent patch behavior, and negative checks for untouched providers.

That matters because several provider surfaces require integration files, MCP config, extensions, or patch-sensitive private behavior. AxiOwl's security posture is not "patch everything and hope." It is selected-feature-specific, logged, tested, and expected to fail visibly when a provider surface is unsafe or unsupported.

Remote Is Explicit, Not A Fallback

AxiOwl has remote-related command surfaces and Linux relay code, but the current source is careful about scope. The Windows README describes a split where Windows acts as the local coordinator and outbound SSH remote provider, while the Linux side supports axiowl relay-session --stdio. The same README says the Linux remote app supports Codex CLI delivery only and does not support desktop GUI behavior, VS Code, Antigravity, tray behavior, or relay chaining.

The current provider dispatch code returns remote delivery as out of scope for the local-provider remediation build. The security docs add the policy reason: local provider support should remain local unless a remote feature is explicitly selected, and remote must not be used to hide local delivery failures.

For operators, that means a broken local provider route should be fixed as a local route. Remote delivery should be a deliberate node contract, not an invisible detour.

Logs And Evidence Make The Boundary Inspectable

AxiOwl records runtime and delivery evidence under its local state directory. The documented log locations include %LOCALAPPDATA%\AxiOwl\logs, %LOCALAPPDATA%\AxiOwl\registry, and %LOCALAPPDATA%\AxiOwl\runtime. The code writes event logs such as events.jsonl, delivery stages in delivery.jsonl, activation events, and worker request/result evidence.

Those files are not just diagnostics after something goes wrong. They are part of the operating model. A user or developer should be able to distinguish target resolution, route selection, local AxiOwl acceptance, background worker handoff, provider write success, provider rejection, unsupported provider state, and end-to-end reply proof.

Practical Takeaway

AxiOwl's security model is built around narrow authority and visible proof. It reads and writes the files needed to discover and route selected provider sessions. It keeps routing state in a local registry. It requires sender identity for meaningful replies. It distinguishes local handoff from provider proof. It gates installer actions by selected provider feature. It treats patch-sensitive surfaces as explicit risks. It keeps remote behavior explicit instead of using it as a fallback.

That makes the system more conservative than a simple "send this text somewhere" bridge. The payoff is operational clarity: when AxiOwl says a message was accepted, a provider was unsupported, a sender identity was missing, or a route needs discovery repair, those states mean different things and are recorded separately. For agent-to-agent workflows, that separation is the core of the security model.