Hoop.dev Agent Systemd Deployment Guide

This guide walks through deploying the Hoop.dev agent as a systemd service on Linux systems, ensuring the agent runs automatically on boot and restarts on failure.

Prerequisites

• Linux system with systemd (Ubuntu 16.04+, CentOS 7+, RHEL 7+, etc.)
• Root or sudo access
• 🔑 Hoop.dev agent key: Create an agent key in the Hoop.dev web interface under Settings → Agents before starting this guide

Quick Start (One-Line Installation)

For rapid deployment, use this one-line script with your agent key from the Hoop.dev web interface:

# Run this on your SERVER with the agent key from Hoop.dev web interface
curl -sL https://gist.githubusercontent.com/andriosrobert/984ed4d76aebeb1ffcdeed3ef91824de/raw/81f26c4d275710d12699077d2a1b21485d81caca/install-agent-systemd.sh | sudo bash -s -- "YOUR_HOOP_KEY_HERE"

Get Agent Key from Web Interface

Before using the installer, create an agent key:

1. Login to your Hoop.dev web interface
2. Navigate to Settings → Agents
3. Click "Create Agent"
4. Give your agent a name (e.g., production-server-01)
5. Copy the generated key (starts with grpcs:// or https://)
6. Use this key in the installation commands below

Or create the complete installation script manually:

# Create and run the installation script
cat << 'SCRIPT_EOF' > /tmp/install-hoop-agent.sh
#!/bin/bash

set -euo pipefail

HOOP_KEY="$1"
INSTALL_USER="${2:-dedicated}"  # Options: 'dedicated', 'root', 'current'

if [[ -z "$HOOP_KEY" ]]; then
    echo "Usage: $0 <HOOP_KEY> [user_type]"
    echo "user_type options: dedicated (default), root, current"
    exit 1
fi

echo "Installing Hoop.dev Agent with systemd..."

# Install Hoop CLI
curl -s -L https://releases.hoop.dev/release/install-cli.sh | sh

# Create directories
mkdir -p /etc/hoop

# Setup user and directories based on preference
case "$INSTALL_USER" in
    "dedicated")
        useradd --system --no-create-home --shell /bin/false hoop 2>/dev/null || true
        mkdir -p /var/lib/hoop
        chown hoop:hoop /var/lib/hoop
        SERVICE_USER="hoop"
        SERVICE_GROUP="hoop"
        WORKING_DIR="/var/lib/hoop"
        ENV_PERMS="640"
        ENV_OWNER="root:hoop"
        ;;
    "root")
        SERVICE_USER="root"
        SERVICE_GROUP="root"
        WORKING_DIR="/root"
        ENV_PERMS="600"
        ENV_OWNER="root:root"
        ;;
    "current")
        SERVICE_USER="$SUDO_USER"
        SERVICE_GROUP="$SUDO_USER"
        WORKING_DIR="/home/$SUDO_USER"
        ENV_PERMS="600"
        ENV_OWNER="$SUDO_USER:$SUDO_USER"
        ;;
    *)
        echo "Invalid user type. Use: dedicated, root, or current"
        exit 1
        ;;
esac

# Create environment file
cat > /etc/hoop/agent.env << EOF
HOOP_KEY=$HOOP_KEY
LOG_LEVEL=info
LOG_ENCODING=json
LOG_GRPC=0
EOF

chown $ENV_OWNER /etc/hoop/agent.env
chmod $ENV_PERMS /etc/hoop/agent.env

# Create systemd service
cat > /etc/systemd/system/hoop-agent.service << EOF
[Unit]
Description=Hoop.dev Agent
Documentation=https://hoop.dev/docs
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0

[Service]
Type=simple
User=$SERVICE_USER
Group=$SERVICE_GROUP
WorkingDirectory=$WORKING_DIR
EnvironmentFile=/etc/hoop/agent.env
ExecStart=/usr/local/bin/hoop start agent
ExecReload=/bin/kill -HUP \$MAINPID
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=hoop-agent

# Resource limits
LimitNOFILE=65536
MemoryHigh=512M
MemoryMax=1G

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
systemctl daemon-reload
systemctl enable hoop-agent
systemctl start hoop-agent

echo "✅ Hoop.dev Agent installed and started successfully!"
echo "Check status with: sudo systemctl status hoop-agent"
echo "View logs with: sudo journalctl -u hoop-agent -f"

SCRIPT_EOF

Then run run it

chmod +x /tmp/install-hoop-agent.sh

# Run the script with your Hoop key (from web interface Settings → Agents)
sudo /tmp/install-hoop-agent.sh "YOUR_HOOP_KEY_HERE" "dedicated"

Complete Workflow Summary

🌐 In Hoop.dev Web Interface:

1. Login to Hoop.dev web interface
2. Go to Settings → Agents
3. Click "Create Agent" and name it (e.g., my-server)
4. Copy the generated agent key

🖥️ On Server:

1. Use one-line installer with the key from step 4
2. Verify installation: sudo systemctl status hoop-agent

🌐 Back in Web Interface:

1. Verify agent appears online in Settings → Agents

Manual Installation Options

Choose your preferred installation method:

Option A: Dedicated User (Recommended for Production)

Option B: Root User (Simple Setup)

Option C: Current User (Development/Testing)

Prerequisites

• Linux system with systemd (Ubuntu 16.04+, CentOS 7+, RHEL 7+, etc.)
• Root or sudo access
• Existing Hoop.dev account and agent key

Step 1: Install Hoop.dev CLI (On Server)

📍 Run this section on your SERVER

Download and Install Binary

# Download the latest Hoop.dev CLI on your server
curl -s -L https://releases.hoop.dev/release/install-cli.sh | sh

# Verify installation
hoop version

Note: The server installation only needs the hoop binary to run the agent. Authentication and key management is done from your local computer.

Alternative: Manual Installation

# Create directory for Hoop binary
sudo mkdir -p /usr/local/bin

# Download specific version (replace with latest version)
VERSION=$(curl -s https://releases.hoop.dev/release/latest.txt)
wget https://releases.hoop.dev/release/$VERSION/hoop-linux-amd64.tar.gz

# Extract and install
tar -xzf hoop-linux-amd64.tar.gz
sudo mv hoop /usr/local/bin/
sudo chmod +x /usr/local/bin/hoop

# Verify installation
/usr/local/bin/hoop version

Step 2: Choose User Configuration (On Server)

📍 Run this section on your SERVER

Option A: Dedicated User (Recommended for Production)

Create a dedicated user for running the Hoop agent:

# Create system user with no login shell
sudo useradd --system --no-create-home --shell /bin/false hoop

# Create working directory
sudo mkdir -p /var/lib/hoop
sudo chown hoop:hoop /var/lib/hoop
sudo chmod 755 /var/lib/hoop

Option B: Root User (Simple Setup)

Run as root user (no additional user creation needed):

# Create working directory (optional, will use /root)
sudo mkdir -p /var/lib/hoop

Option C: Current User (Development/Testing)

Run as your current user:

# No additional setup needed
# Service will run as your current user

Step 3: Configure Agent Authentication

📍 Use the agent key from the Hoop.dev web interface (Settings → Agents)

You should have already created an agent key in the Hoop.dev web interface. The key will look like:

grpcs://my-agent:xagt-ABC123...@use.hoop.dev:8443?mode=standard

or

https://my-agent:xagt-ABC123...@use.hoop.dev/agent?mode=standard

Transfer Key to Server

Copy this key to your server using one of these methods:

Option 1: Direct SSH session

# SSH to your server and set the key directly
ssh your-server
export HOOP_KEY="grpcs://my-agent:xagt-ABC123...@use.hoop.dev:8443?mode=standard"

Option 2: Secure file transfer

# On local computer: save key to file
echo "grpcs://my-agent:xagt-ABC123...@use.hoop.dev:8443?mode=standard" > hoop-key.txt

# Transfer to server
scp hoop-key.txt your-server:/tmp/

# On server: read the key
ssh your-server
export HOOP_KEY=$(cat /tmp/hoop-key.txt)
rm /tmp/hoop-key.txt  # Clean up

Option 3: Include in deployment scripts

# Include in your automation scripts
HOOP_KEY="grpcs://my-agent:xagt-ABC123...@use.hoop.dev:8443?mode=standard"

Step 4: Create Environment File (On Server)

📍 Run this section on your SERVER using the key from Step 3

Create a secure environment file for the agent configuration:

For Dedicated User Setup

# Create environment file
sudo tee /etc/hoop/agent.env << EOF
# Hoop.dev Agent Configuration
HOOP_KEY=YOUR_AGENT_KEY_HERE
LOG_LEVEL=info
LOG_ENCODING=json
LOG_GRPC=0
EOF

# Secure the environment file
sudo chown root:hoop /etc/hoop/agent.env
sudo chmod 640 /etc/hoop/agent.env

For Root User Setup

# Create environment file
sudo tee /etc/hoop/agent.env << EOF
# Hoop.dev Agent Configuration
HOOP_KEY=YOUR_AGENT_KEY_HERE
LOG_LEVEL=info
LOG_ENCODING=json
LOG_GRPC=0
EOF

# Secure the environment file
sudo chown root:root /etc/hoop/agent.env
sudo chmod 600 /etc/hoop/agent.env

For Current User Setup

# Create environment file
sudo tee /etc/hoop/agent.env << EOF
# Hoop.dev Agent Configuration
HOOP_KEY=YOUR_AGENT_KEY_HERE
LOG_LEVEL=info
LOG_ENCODING=json
LOG_GRPC=0
EOF

# Secure the environment file (replace 'username' with your actual username)
sudo chown username:username /etc/hoop/agent.env
sudo chmod 600 /etc/hoop/agent.env

Important: Replace YOUR_AGENT_KEY_HERE with your actual agent key from the Hoop.dev web interface (Settings → Agents).

Step 5: Create Systemd Service Unit (On Server)

📍 Run this section on your SERVER

Choose the service configuration based on your user preference:

For Dedicated User (hoop user)

sudo tee /etc/systemd/system/hoop-agent.service << 'EOF'
[Unit]
Description=Hoop.dev Agent
Documentation=https://hoop.dev/docs
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0

[Service]
Type=simple
User=hoop
Group=hoop
WorkingDirectory=/var/lib/hoop
EnvironmentFile=/etc/hoop/agent.env
ExecStart=/usr/local/bin/hoop start agent
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=hoop-agent

# Security settings
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/lib/hoop
CapabilityBoundingSet=
AmbientCapabilities=
DevicePolicy=closed

# Resource limits
LimitNOFILE=65536
MemoryHigh=512M
MemoryMax=1G

[Install]
WantedBy=multi-user.target
EOF

For Root User

sudo tee /etc/systemd/system/hoop-agent.service << 'EOF'
[Unit]
Description=Hoop.dev Agent
Documentation=https://hoop.dev/docs
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0

[Service]
Type=simple
User=root
Group=root
WorkingDirectory=/root
EnvironmentFile=/etc/hoop/agent.env
ExecStart=/usr/local/bin/hoop start agent
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=hoop-agent

# Resource limits
LimitNOFILE=65536
MemoryHigh=512M
MemoryMax=1G

[Install]
WantedBy=multi-user.target
EOF

For Current User (replace 'username' with your actual username)

# Get current username
CURRENT_USER=${SUDO_USER:-$(whoami)}

sudo tee /etc/systemd/system/hoop-agent.service << EOF
[Unit]
Description=Hoop.dev Agent
Documentation=https://hoop.dev/docs
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0

[Service]
Type=simple
User=$CURRENT_USER
Group=$CURRENT_USER
WorkingDirectory=/home/$CURRENT_USER
EnvironmentFile=/etc/hoop/agent.env
ExecStart=/usr/local/bin/hoop start agent
ExecReload=/bin/kill -HUP \$MAINPID
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=hoop-agent

# Resource limits
LimitNOFILE=65536
MemoryHigh=512M
MemoryMax=1G

[Install]
WantedBy=multi-user.target
EOF

Step 6: Enable and Start Service (On Server)

📍 Run this section on your SERVER

# Reload systemd to recognize new service
sudo systemctl daemon-reload

# Enable service to start on boot
sudo systemctl enable hoop-agent

# Start the service
sudo systemctl start hoop-agent

# Check service status
sudo systemctl status hoop-agent

Step 7: Verify Deployment

Check Service Status (On Server)

📍 Run this section on your SERVER

# Check if service is running
sudo systemctl is-active hoop-agent

# View detailed status
sudo systemctl status hoop-agent

# Check if enabled for boot
sudo systemctl is-enabled hoop-agent

View Logs (On Server)

📍 Run this section on your SERVER

# View recent logs
sudo journalctl -u hoop-agent -n 50

# Follow logs in real-time
sudo journalctl -u hoop-agent -f

# View logs since boot
sudo journalctl -u hoop-agent --since boot

Verify Agent Connection (In Web Interface)

🌐 Check in Hoop.dev Web Interface

1. Login to your Hoop.dev web interface
2. Navigate to Settings → Agents
3. Verify your agent appears as "Online"
4. Check the agent name matches what you created

Service Management Commands

Basic Operations

# Start the service
sudo systemctl start hoop-agent

# Stop the service
sudo systemctl stop hoop-agent

# Restart the service
sudo systemctl restart hoop-agent

# Reload configuration
sudo systemctl reload hoop-agent

# Check status
sudo systemctl status hoop-agent

Configuration Changes

When updating agent configuration:

# Edit environment file
sudo nano /etc/hoop/agent.env

# Restart service to apply changes
sudo systemctl restart hoop-agent

Troubleshooting

Common Issues

Service fails to start

# Check detailed logs
sudo journalctl -u hoop-agent --no-pager

# Verify binary exists and is executable
ls -la /usr/local/bin/hoop

# Test manual start
sudo -u hoop /usr/local/bin/hoop start agent

Permission denied errors

# Check file permissions
ls -la /etc/hoop/agent.env
ls -la /var/lib/hoop

# Fix permissions if needed
sudo chown hoop:hoop /var/lib/hoop
sudo chmod 640 /etc/hoop/agent.env

Network connectivity issues

# Test connectivity to Hoop.dev (run on SERVER)
curl -v https://use.hoop.dev

# Check if agent key is valid (check in web interface Settings → Agents)

High memory usage

# Check memory usage
sudo systemctl show hoop-agent -p MemoryCurrent

# Adjust memory limits in service file if needed
sudo systemctl edit hoop-agent

Log Analysis

# Check for errors in the last hour
sudo journalctl -u hoop-agent --since="1 hour ago" | grep -i error

# Monitor resource usage
sudo journalctl -u hoop-agent | grep -E "(memory|cpu|resource)"

# Check service restarts
sudo journalctl -u hoop-agent | grep -i restart

Security Considerations

File Permissions

Ensure proper file permissions are set based on your setup:

For Dedicated User Setup

# Agent binary
sudo chmod 755 /usr/local/bin/hoop

# Environment file (contains sensitive keys)
sudo chmod 640 /etc/hoop/agent.env
sudo chown root:hoop /etc/hoop/agent.env

# Working directory
sudo chmod 755 /var/lib/hoop
sudo chown hoop:hoop /var/lib/hoop

For Root User Setup

# Agent binary
sudo chmod 755 /usr/local/bin/hoop

# Environment file (contains sensitive keys)
sudo chmod 600 /etc/hoop/agent.env
sudo chown root:root /etc/hoop/agent.env

For Current User Setup

# Agent binary
sudo chmod 755 /usr/local/bin/hoop

# Environment file (contains sensitive keys)
sudo chmod 600 /etc/hoop/agent.env
sudo chown $USER:$USER /etc/hoop/agent.env

Firewall Configuration

If using a firewall, ensure outbound HTTPS (443) and gRPC (8443) connections are allowed:

# UFW example
sudo ufw allow out 443
sudo ufw allow out 8443

# iptables example
sudo iptables -A OUTPUT -p tcp --dport 443 -j ACCEPT
sudo iptables -A OUTPUT -p tcp --dport 8443 -j ACCEPT

SELinux (RHEL/CentOS)

If SELinux is enabled, you may need to create a custom policy:

# Check SELinux status
sestatus

# If SELinux is enforcing, check for denials
sudo ausearch -m avc -ts recent | grep hoop

Backup and Recovery

Backup Agent Configuration

# Create backup directory
sudo mkdir -p /backup/hoop

# Backup configuration
sudo cp /etc/hoop/agent.env /backup/hoop/
sudo cp /etc/systemd/system/hoop-agent.service /backup/hoop/

# Backup working directory (if contains important data)
sudo tar -czf /backup/hoop/hoop-data-$(date +%Y%m%d).tar.gz /var/lib/hoop

Disaster Recovery

To restore agent on a new system:

# Install Hoop CLI (Step 1)
# Create system user (Step 2)
# Restore configuration files
sudo cp /backup/hoop/agent.env /etc/hoop/
sudo cp /backup/hoop/hoop-agent.service /etc/systemd/system/

# Set permissions and start service
sudo chown root:hoop /etc/hoop/agent.env
sudo chmod 640 /etc/hoop/agent.env
sudo systemctl daemon-reload
sudo systemctl enable --now hoop-agent

Production Recommendations

1. Resource Monitoring: Set up monitoring for the agent service
2. Log Rotation: Configure log rotation to prevent disk space issues
3. Automated Updates: Implement a strategy for updating the Hoop binary
4. Health Checks: Monitor agent connectivity through Hoop.dev dashboard
5. Backup Strategy: Regular backup of configuration and any local data

Agent Modes and Use Cases

Standard Mode (Default)

Best for:

• Multiple database connections
• Port-forwarding internal services
• Container platform access (kubectl, AWS ECS)
• Acting as a jump host

Embedded Mode

Best for:

• Single application/database access
• Ad-hoc task execution
• Interactive console access
• REPL environments

To use embedded mode, modify the service file:

ExecStart=/usr/local/bin/hoop run --name myapp --postgres 'postgres://user:pwd@localhost/db'

This systemd deployment provides a robust, production-ready setup for the Hoop.dev agent with proper security, logging, and management capabilities.