Your First Hive AI Investigation

Install the Hive agent on a server, connect it to ops0, and run your first AI-powered investigation.

Scenario

You have a Linux server — a VM, a bare-metal machine, or a cloud instance. Something is behaving unexpectedly: high CPU, slow response, a crashing service. You want to:

• Install the Hive agent in under 5 minutes
• Use natural language to ask what's wrong
• Watch Hive investigate and show you exactly what it finds

Prerequisites

Step 1: Generate an Install Command

Step 2: Install the Agent on Your Server

SSH into your server and run the copied command as root (or with sudo):

curl -sSL https://brew.ops0.ai/hive/install | \
  HIVE_API_KEY=hive_xxxxxxxxxxxx \
  HIVE_URL=https://brew.ops0.ai \
  bash

The script:

1. Detects your platform (Linux x86_64, ARM, etc.)
2. Downloads the correct agent binary
3. Creates a systemd service (hive-agent)
4. Starts the agent and registers it with ops0

The whole process takes about 30 seconds on a typical server.

Step 3: Confirm the Agent is Online

Back in ops0:

The agent sends a heartbeat every 30 seconds. If it doesn't appear within 1–2 minutes, see Troubleshooting below.

Step 4: Start a Chat Session

Good first questions to try:

• "Is this server healthy?"
• "What's using the most CPU right now?"
• "Show me recent errors in the system logs"
• "What services are running and which ones are failing?"

Step 5: Watch Hive Investigate

When you send a message, Hive:

1. Plans — determines which commands will answer your question
2. Executes — runs commands through the secure tunnel to your server
3. Analyzes — reviews the output and continues investigating if needed
4. Responds — explains what it found in plain English

Example — asking about high CPU:

You: "Why is CPU usage high?"

Hive: I'll investigate the CPU usage.

  ✓ top -bn1 | head -20          → Load: 3.4, 3.1, 2.8
  ✓ ps aux --sort=-%cpu | head   → java process at 87% CPU
  ✓ ps -p 12847 -o cmd           → /usr/bin/java -jar /opt/app/service.jar
  ✓ journalctl -u myapp -n 50    → OutOfMemoryError at 14:23:11

Root cause: The Java application (myapp service) is running out of heap
memory, causing the JVM to spend most of its time in garbage collection
rather than doing useful work. This is a classic GC thrash pattern.

Recommended actions:
1. Increase JVM heap: add -Xmx2g to the service start command
2. Check for memory leaks in the application
3. Restart the service now to get immediate relief: sudo systemctl restart myapp

Step 6: Command Safety

Hive distinguishes between safe (read-only) and dangerous (write/destructive) commands.

Safe commands run automatically:

• ps, top, df, free, netstat, journalctl, ls, cat (on log files)

Dangerous commands require your approval:

When Hive suggests restarting a service or making a change, you'll see a confirmation prompt:

Hive wants to run:
  sudo systemctl restart myapp

This will restart the myapp service (brief downtime).
[Approve] [Reject]

Click Approve to let it run, or Reject to skip that action and ask Hive to suggest an alternative.

Blocked commands (never executed regardless of approval):

• rm -rf, shutdown, dd, package installs, shell metacharacters

Step 7: Open a Terminal (Optional)

For direct shell access without AI chat:

No SSH client needed. No inbound ports required. The session goes through the same outbound tunnel the agent established on install.

Verification

You have successfully completed this tutorial when:

1. Agent shows online status in Hive → Agents
2. You sent a chat message and received a response with command output
3. Hive identified at least one finding about the server's state

Next Steps

Troubleshooting