How IT-AI works

IT-AI has three parts. A hub you run on your own server. An agent on each Windows, macOS or Linux device. And the controllers: the hub's web dashboard, the it-ai-mcp MCP server your AI talks to, and the itai command-line client.

The relay: devices dial out

The agent connects out to the hub over HTTPS and holds the connection open (a long poll on the hub's normal port). The hub sends each request back down that connection, and the agent answers it. So a managed device needs no inbound port, no public address and no VPN, and it works behind NAT and CGNAT.

The agent has no hardcoded hub or vendor address. The hub URL and the token are parameters you pass when you enroll the device.

Enrollment and per-device secrets

1. In the hub dashboard, Register a device mints a personal enrollment token (htok_…) for your account and shows the command to run.
2. The agent enrolls with that token. On its first hello (agent 3.7 or later, hub 3.16 or later) it asks the hub for its own device secret (hdev_…) and uses that for every later relay call. The enrollment token is then dropped.
3. The secret is stored in ~/.it-ai/relay.cred (mode 0600 in a 0700 directory), not on a command line or in an autostart entry. The hub keeps only its SHA-256 hash.
4. A device secret is valid only for the device it was issued to, so one compromised device cannot poll, read or forge another device's traffic. You can revoke one device's secret from the dashboard without touching the others.

Every call goes through the hub's checks

Whether a request comes from the dashboard, the MCP server or the CLI, the hub runs the same steps before it contacts the device:

1. Ownership. You can see and drive only devices you own. With identity configured, this fails closed.
2. Token scope. An MCP token is read, write or admin. A read-only token gets 403 this MCP token is read-only on any write action.
3. Policy. The deny-list (deny_actions, deny_patterns in the hub's policy.json) refuses matching actions and commands before the device is contacted. With no policy file, every command is allowed.
4. Audit. The action, the device, who asked, whether it came from the browser or MCP, and the full command text are recorded. For a command, the record is written before the command runs.

LAN-direct: the shortcut that keeps the checks

When the controller and the device share a network, screen frames, files, shell, input and exec can go straight over the LAN instead of through the hub. For this the agent listens on port 8765 on its LAN addresses and serves a hub-signed certificate for its LAN addresses, so the controller validates it against the hub's CA.

A direct call is still governed. Before each one, the controller asks the hub for a 60-second ed25519 capability, and the hub issues it only after the same ownership, deny-list and audit steps. The agent checks that the capability matches the device, the operation and a hash of the arguments, and refuses the call without one. Any failure falls back to the relay. Set HIVE_LAN=0 on the agent to turn LAN-direct off.

The AI: two ways in

• Your own AI, over MCP or the CLI. Claude Code or another MCP client calls the 32 tools of it-ai-mcp with the token you gave it. What it can do is bounded by that token's scope and your hub policy. Your MCP client may also ask you before each tool call.
• The hub's built-in assistant. It investigates with read-only tools (system reports, compliance checks, allowlisted read-only commands, CVE lookups) and explains what it found. To change anything it proposes a fix from a fixed, server-side menu. The fix runs only after a person clicks Apply. Its Anthropic API key is set on the hub and never sent to devices or browsers.

Updates

An enrolled agent keeps itself on the build its hub serves. Every two minutes it compares the hub's published SHA-256 for its platform with its own executable. Only when they differ does it download the new binary, check its ed25519 signature against a pinned key, and replace itself. A hub that lies about the checksum can delay an update but cannot install an unsigned build. Only one update runs at a time, and the agent refuses an empty or truncated binary.

What runs where

Next: security and trust, or install it.