Agents

A Hive agent is a lightweight process installed on your server. It establishes a secure outbound tunnel to ops0, enabling AI chat, terminal access, command execution, and metric collection — without opening any inbound ports.

How Agents Work

Your Server                  ops0
    │                          │
    │  Hive Agent              │
    │  ┌─────────────────┐     │
    │  │ Outbound tunnel ├────►│  WebSocket / HTTPS
    │  │ (port 443 out)  │     │
    │  └─────────────────┘     │
    │                          │

The agent dials out on port 443. Your firewall needs no inbound rules. The tunnel carries AI commands, terminal sessions, telemetry, and heartbeats.

Installing an Agent

Option 1: One-Click Deploy Script

Go to Hive → Agents → Add Agent
Click Deploy
Copy the generated install command
Run it on your target server as root

The script detects your platform (Linux x86_64, ARM, macOS) and installs the appropriate binary.

Linux / macOS:

curl -sSL https://brew.ops0.ai/hive/install | \
  HIVE_API_KEY=<your-key> \
  HIVE_URL=https://brew.ops0.ai \
  bash

The agent starts automatically as a system service and registers itself with ops0.

Option 2: Kubernetes DaemonSet

Deploy Hive to every node in a Kubernetes cluster using a DaemonSet. ops0 generates the full YAML manifest.

Go to Hive → Agents → Add Agent
Select Kubernetes
Copy the generated YAML
Apply it to your cluster: kubectl apply -f hive-daemonset.yaml

The manifest includes:

ServiceAccount and ClusterRole with full cluster read permissions
DaemonSet with resource limits, liveness/readiness probes, and tolerations
ConfigMap with your API key and endpoint

Option 3: Docker

docker run -d \
  --name hive-agent \
  --restart unless-stopped \
  -e HIVE_API_KEY=<your-key> \
  -e HIVE_URL=https://brew.ops0.ai \
  ops0/hive-agent:latest

Option 4: Manual Registration

Go to Hive → Agents → Add Agent → Manual
Name the agent
Click Create — the plaintext API key is shown once only
Copy the key and configure your agent manually

API Key shown once

ops0 stores a hashed version of the API key. The plaintext key is shown immediately after creation and never again. Store it securely before closing the dialog.

Agent Status

Status	Meaning
online	Agent is connected and sending heartbeats
offline	No heartbeat received recently
pending_deletion	Delete requested; agent will uninstall and deregister

Agents send a heartbeat every 30 seconds. An agent is marked offline if no heartbeat is received within the expected window.

Agent Fields

Field	Description
Name	Display name for the agent
Hostname	Server hostname reported by the agent
IP Address	IP address of the agent machine
Version	Hive agent binary version
Last Heartbeat	Time of the most recent heartbeat
Group	Agent group assignment (optional)
Tags	Labels for filtering and organization

Deleting an Agent

Open the agent detail
Click Delete
An uninstall command is optionally sent to the agent before removal

Options:

--keep-logs — preserve agent logs on the server
--keep-config — preserve agent config files
--force — delete without sending an uninstall command (for unreachable agents)

Troubleshooting

Agent stuck at "offline" after install

Check that outbound HTTPS (port 443) to brew.ops0.ai is not blocked by a firewall or proxy. Run curl -I https://brew.ops0.ai from the server to verify connectivity.

Agent shows online but AI chat fails

Verify the agent has sufficient permissions to run system commands (usually requires running as root or a privileged user). Check the agent service logs: journalctl -u hive-agent -f.

Lost the API key

API keys cannot be recovered. Delete the agent and create a new one to get a new key. The old agent installation will stop heartbeating and can be uninstalled from the server.