Skip to content

IT-AI documentation

Install the IT-AI agent, enroll a device with a personal token, connect Claude Code over MCP, run background jobs and verify every download.

These docs cover the parts that run on your machines: the agent, the MCP server and the itai CLI, at agent v3.9.0. Each page of this section is also published as plain Markdown for AI assistants: add .md to the page's address, or see the list in llms.txt. The full reference is the agent README.

1. Run the hub

The hub is a single Rust binary. Point HUB_DATA at a writable directory and set RELAY_TOKEN from the start:

HUB_DATA=./hub-data RELAY_TOKEN="$(openssl rand -hex 32)" ./it-ai-hub

It prints its dashboard URL. With RELAY_TOKEN set, the hub runs in strict-ownership mode: every device is owned from enrollment, and each user sees only their own devices. Without it, the hub is an open single-operator setup for a trusted LAN.

For a hub on the internet behind a TLS proxy, set HUB_PUBLIC_URL=https://your-hub.example.com. Expose only the agent-facing paths (/relay, /bin, and /m if you use MCP) without SSO, and keep /x/*, the human control surface, behind SSO. The hub is not on the public release page; see download.

2. Enroll a device

In the dashboard, Register a device mints a personal enrollment token (htok_…) and shows the command for each OS. Its shape:

HIVE_RELAY_TOKEN=htok_… ./it-ai --relay https://your-hub.example.com --name <device> --persist

$env:HIVE_RELAY_TOKEN="htok_…"; .\it-ai.exe --relay https://your-hub.example.com --name reception-pc --persist
  • --persist adds a per-user autostart entry. --install, run as root or admin, installs a boot service instead. With neither, the agent runs until you close it.
  • The environment variable keeps the token off the command line; --relay-token htok_… also works.
  • On its first connection the agent gets its own device secret and stores it in ~/.it-ai/relay.cred (%USERPROFILE%\.it-ai\relay.cred on Windows). The enrollment token is not used again.
  • If you revoke the device's secret, the agent logs relay: device credential rejected — re-enroll this device and retries every 60 seconds. Run the enrollment command again to give it a new one.

3. Connect your AI

Mint an MCP token in the dashboard (start with a read-only one), then register the MCP server with Claude Code. The full steps, the environment variables and the list of tools are on the MCP page.

claude mcp add-json itai '{
  "command": "'"$HOME"'/.it-ai/it-ai-mcp",
  "env": { "HAIVE_HUB": "https://your-hub.example.com", "HIVE_MCP_TOKEN": "<token>", "HIVE_OWNER": "<owner>" }
}'

For the command line, install itai and run itai list to check the connection:

export HAIVE_HUB=https://your-hub.example.com
export HIVE_MCP_TOKEN=...        # from your secret manager
sh scripts/setup-itai.sh         # from a checkout of the agent repo; macOS (Apple Silicon) and Linux

4. Run long commands as jobs

A single command is capped at about 65 seconds. For a build, a dev server or a long script, start a job and read its output as it grows:

itai job start <device> --cwd /srv/app -- 'npm ci && npm run build'
itai job logs  <device> <id> --follow
itai job stop  <device> <id>

The words after -- are joined and run by the device's shell, so pass a compound command as one quoted argument. Jobs are relay-only in this version and need agent 3.6.0 or later. The MCP tools are job_start, job_logs, job_stop and job_list.

5. Move files

  • download_file / itai get copies a file from a device.
  • upload_file / itai put copies a file of up to 100 MB to a device.
  • push_file copies a larger file by stage-and-pull: the hub stages it and the device pulls it with a SHA-256 check.

6. Harden a deployment

Setting Where What it does
RELAY_TOKEN hub Strict ownership: token-gated enrollment, per-device tunnel auth, per-user isolation
policy.json hub (HUB_DATA) Deny-list: deny_actions and deny_patterns. With no file, every command is allowed
PROXY_AUTH_SECRET hub, behind an SSO proxy Trust forwarded identity headers only when they come from the proxy
HAIVE_CAFILE MCP server and CLI Verify a self-signed hub certificate instead of skipping verification
SCREEN_SHARE agent Confine file transfer to one folder
SCREEN_EXEC=0 agent Turn remote commands and jobs off: view and control only
HIVE_LAN=0 agent Turn LAN-direct off and listen on loopback only

Rotate enrollment tokens after any suspected exposure, and revoke a single device's secret when only that device is suspect. More on the security page.

7. Updates and logs

  • An enrolled agent checks your hub every two minutes and updates itself to the build the hub serves, after checking the binary's ed25519 signature. update_agent pushes an update at once.
  • Agent logs go to ~/.it-ai/agent.log (%USERPROFILE%\.it-ai\agent.log on Windows, capped at 1 MB) in most install modes; a Linux service logs to journalctl -u it-ai.

8. Remove an agent

dissolve_agent (MCP) stops the agent and removes its autostart entry. The binary itself is not deleted.

This page as Markdown: https://glick.run/it-ai/docs.md

glick.run