# 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.

Canonical page: https://glick.run/it-ai/docs.html

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](https://glick.run/llms.txt). The full reference is the [agent README](https://github.com/gitayg/haive-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:

```sh
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](https://glick.run/it-ai/download.html).

## 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:

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

```powershell
$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](https://glick.run/it-ai/mcp.html).

```sh
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:

```sh
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:

```sh
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](https://glick.run/it-ai/security.html).

## 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.