Security documentation

Know who connects. Know what changed.

Install Airmsh, approve device and agent identities, pin MCP tool schemas, and enforce access rules on the agents that need them.

New to Airmsh? Start with one private service. Come back when you want to review device identities, agent permissions, or a changed tool.

Device identity

Approve the device key that may sign agent traffic.

Agent route

Bind every request to a device ID and agent tag.

MCP schema

Stop an unexpected tool-contract change before execution.

Local secrets

Keep database and MCP credentials on the destination device.

Install

Desktop and server installs require administrator or root permission so airmsh can create the local tunnel and background service.

macOS

Open the signed DMG, drag airmsh to Applications, launch it, and complete the permission screens. Approve the background service in System Settings when macOS asks.

Windows

Run the installer as administrator. It includes the app, background service, and required networking components. Allow private network access when Windows Firewall asks.

Linux server

Inspect the installer, then install with your account email. Enter the password only when prompted. The installer checks the Linux build, keeps an existing login, sets up private device access, and enables the service.

curl -fsSL https://airmsh.com/install-cli.sh | sudo sh -s -- --email you@example.com

Check with sudo airmsh-cli --version and sudo systemctl is-active airmsh-cli; the service should say active. The server should then appear in Devices. For manual packages, see Downloads; for a private service, follow the Endpoint guide.

Android and iPhone

Install Airmsh through the Google Play or App Store link on the Downloads page, then approve the system VPN permission when prompted. The destination device enforces access policies for services it hosts.

Agent policy

Identity checks always apply. The organization owner can turn on additional rules for each destination agent.

Always on

Base checks

The destination verifies the authenticated source device, target device ID and agent tag. Payload bounds and the destination service’s own authentication remain separate from policy.

Owner enabled per agent

Enforced policy

Apply user, group, device, resource and action rules, request limits, and sensitive-data decisions to this agent.

In Agents, choose the destination agent, open its policy, select Enforce policy for this agent, and save. Only the organization owner can edit that policy.

Identity pinning

An approved key helps answer one question: is this still the same device and agent identity?

The destination creates a separate signing key for agent requests. It is not the tunnel private key.

Only the public key is registered with the control service. The private key stays on the destination device.

Every agent request is checked against the approved device, agent, action, and access rules.

The destination first authenticates the mesh device, then checks the request signature against the approved key.

A valid network endpoint is never accepted as agent identity.

authenticated device
  -> target device + agent tag
  -> approved signing key and signed request
  -> access policy and limits
  -> local service authentication
  -> request sensitive-data checks
  -> execution
  -> response limits and sensitive-data checks
  -> signed audit

MCP schema pinning

This blocks a changed MCP tool contract from running silently.

Before pinning, an MCP agent can be tested with base identity checks. When the owner is ready, pin its current tools/list response so a later schema change is denied until it is reviewed.

airmsh> agent add mcp tools local-mcp http://127.0.0.1:9000/mcp mcp:tools
airmsh> agent pin tools
airmsh> agent list

What happens after pinning

The destination checks the approved tool schema before each MCP invocation. If it changes, the request is denied. Recheck the local MCP server and run the pin command again as the owner. Only the organization owner can approve a new schema pin.

Move and rotate

For a normal move, install airmsh on the new machine and register it as a new device. Do not copy the tunnel private key or agent signing key between machines.

If local state is restored or an agent signing key changes, the control service keeps the current key active and records the new key as pending. The organization owner reviews the device and approves the pending pin. Admin and support roles cannot approve it.

For an MCP update, deploy the new MCP server, inspect its tools and input schemas, then explicitly pin the new digest. A failed pin check is a security event, not an automatic update.