Agent Deployment

The Hydranaut Agent is a lightweight monitoring agent that performs health checks and reports service status to the Hydranaut platform. Deploy it in your infrastructure to monitor your services from within your network.

Quick Start

The simplest way to run the agent is with Docker:

docker run -d \
  --name hydranaut-agent \
  -e HYDRANAUT_API_KEY=sp_abc123xyz \
  nimbitlabs/hydranaut-agent:latest

That's it! Just provide your API key and the agent will connect to Hydranaut.

Getting Your API Key

Log in to Hydranaut
Navigate to Settings → API Keys
Click Create New API Key
Give it a name (e.g., "Production Agent")
Copy the key (starts with sp_)

warning

Store your API key securely! It provides access to your Hydranaut account.

Deployment Options

Docker

Basic Deployment

docker run -d \
  --name hydranaut-agent \
  --restart unless-stopped \
  -e HYDRANAUT_API_KEY=sp_abc123xyz \
  nimbitlabs/hydranaut-agent:latest

With Persistent Logs

docker run -d \
  --name hydranaut-agent \
  --restart unless-stopped \
  -e HYDRANAUT_API_KEY=sp_abc123xyz \
  -v $(pwd)/logs:/app/logs \
  nimbitlabs/hydranaut-agent:latest

With Debug Logging

docker run -d \
  --name hydranaut-agent \
  --restart unless-stopped \
  -e HYDRANAUT_API_KEY=sp_abc123xyz \
  -e Serilog__MinimumLevel__Default=Debug \
  nimbitlabs/hydranaut-agent:latest

Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  hydranaut-agent:
    image: nimbitlabs/hydranaut-agent:latest
    container_name: hydranaut-agent
    restart: unless-stopped
    environment:
      - HYDRANAUT_API_KEY=sp_abc123xyz
    volumes:
      - ./logs:/app/logs
    healthcheck:
      test: ["CMD", "ps", "aux", "|", "grep", "-v", "grep", "|", "grep", "-q", "Hydranaut.Agent"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 5s

Then run:

docker-compose up -d

Kubernetes

Create a deployment manifest:

apiVersion: v1
kind: Secret
metadata:
  name: hydranaut-secrets
  namespace: monitoring
type: Opaque
stringData:
  api-key: "sp_abc123xyz"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hydranaut-agent
  namespace: monitoring
  labels:
    app: hydranaut-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hydranaut-agent
  template:
    metadata:
      labels:
        app: hydranaut-agent
    spec:
      containers:
      - name: agent
        image: nimbitlabs/hydranaut-agent:latest
        env:
        - name: HYDRANAUT_API_KEY
          valueFrom:
            secretKeyRef:
              name: hydranaut-secrets
              key: api-key
        resources:
          requests:
            memory: "64Mi"
            cpu: "100m"
          limits:
            memory: "128Mi"
            cpu: "200m"
        livenessProbe:
          exec:
            command:
            - /bin/sh
            - -c
            - ps aux | grep -v grep | grep -q Hydranaut.Agent
          initialDelaySeconds: 5
          periodSeconds: 30

Apply the manifest:

kubectl apply -f hydranaut-agent.yaml

Systemd Service (Linux)

For running the agent directly on a Linux server:

Download the agent binary (contact support for direct binary downloads)
Create a systemd service file at /etc/systemd/system/hydranaut-agent.service:

[Unit]
Description=Hydranaut Monitoring Agent
After=network.target

[Service]
Type=simple
User=hydranaut
Group=hydranaut
WorkingDirectory=/opt/hydranaut-agent
Environment="HYDRANAUT_API_KEY=sp_abc123xyz"
ExecStart=/opt/hydranaut-agent/Hydranaut.Agent
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable hydranaut-agent
sudo systemctl start hydranaut-agent

Configuration

Environment Variables

Variable	Required	Description	Default
`HYDRANAUT_API_KEY`	Yes	Your Hydranaut API key	-
`Agent__ApiBaseUrl`	No	Hydranaut API endpoint (for self-hosted)	`https://hydranaut-api.nimbitlabs.com`
`Agent__ConfigurationRefreshIntervalSeconds`	No	How often to fetch new configuration	`300` (5 minutes)
`Agent__HealthCheckWorkerCount`	No	Number of concurrent health check workers	`5`
`Serilog__MinimumLevel__Default`	No	Logging level (Debug, Information, Warning, Error)	`Information`

Advanced Configuration

For self-hosted Hydranaut instances:

docker run -d \
  --name hydranaut-agent \
  -e HYDRANAUT_API_KEY=sp_abc123xyz \
  -e Agent__ApiBaseUrl=https://your-hydranaut-instance.com \
  nimbitlabs/hydranaut-agent:latest

Monitoring the Agent

View Logs

# Docker
docker logs -f hydranaut-agent

# Docker Compose
docker-compose logs -f hydranaut-agent

# Kubernetes
kubectl logs -f deployment/hydranaut-agent -n monitoring

# Systemd
sudo journalctl -u hydranaut-agent -f

Check Health Status

# Docker
docker inspect --format='{{.State.Health.Status}}' hydranaut-agent

# Kubernetes
kubectl get pods -n monitoring -l app=hydranaut-agent

Verify Agent is Working

Check the agent logs to confirm it's successfully connecting and performing health checks:

# Look for successful connection messages
docker logs hydranaut-agent | grep -i "connected\|health check"

You should see log entries indicating the agent is fetching configuration and performing health checks.

Troubleshooting

Agent Not Connecting

Symptoms: Agent starts but doesn't appear in Hydranaut dashboard

Solutions:

Verify your API key is correct
Check network connectivity to hydranaut-api.nimbitlabs.com
Review agent logs for error messages
Ensure no firewall is blocking outbound HTTPS traffic

# Test connectivity
curl -I https://hydranaut-api.nimbitlabs.com/health

# Check agent logs
docker logs hydranaut-agent

Invalid API Key Error

Symptoms: Agent logs show "Unauthorized" or "Invalid API key"

Solutions:

Verify the API key in Hydranaut dashboard
Ensure the key hasn't been revoked
Check for extra spaces or quotes in the environment variable
Regenerate the API key if necessary

High Resource Usage

Symptoms: Agent consuming excessive CPU or memory

Solutions:

Increase the configuration refresh interval:

-e Agent__ConfigurationRefreshIntervalSeconds=600

Reduce concurrent workers:
```
-e Agent__HealthCheckWorkerCount=3
```
Review the number of services being monitored

Container Keeps Restarting

Symptoms: Agent container restarts repeatedly

Solutions:

Check logs for crash reasons:
```
docker logs hydranaut-agent
```
Verify all required environment variables are set
Ensure sufficient resources are allocated
Check for network connectivity issues

Security Best Practices

API Key Management

✅ Use secrets management: Store API keys in Docker secrets, Kubernetes secrets, or a vault
✅ Rotate keys regularly: Create new API keys periodically
✅ Use least privilege: Create separate API keys for different environments
❌ Never commit keys: Don't store API keys in version control

Network Security

✅ Use HTTPS: All communication with Hydranaut is encrypted
✅ Firewall rules: Only allow outbound HTTPS (443) to hydranaut-api.nimbitlabs.com
✅ Private networks: Deploy agents in private networks when possible

Container Security

✅ Non-root user: The agent runs as a non-root user by default
✅ Read-only filesystem: Consider mounting the root filesystem as read-only
✅ Resource limits: Set CPU and memory limits to prevent resource exhaustion

Example with enhanced security:

docker run -d \
  --name hydranaut-agent \
  --restart unless-stopped \
  --read-only \
  --tmpfs /tmp \
  --memory="128m" \
  --cpus="0.5" \
  --security-opt=no-new-privileges:true \
  -e HYDRANAUT_API_KEY=sp_abc123xyz \
  nimbitlabs/hydranaut-agent:latest

Updating the Agent

Docker

# Pull the latest image
docker pull nimbitlabs/hydranaut-agent:latest

# Stop and remove the old container
docker stop hydranaut-agent
docker rm hydranaut-agent

# Start with the new image
docker run -d \
  --name hydranaut-agent \
  --restart unless-stopped \
  -e HYDRANAUT_API_KEY=sp_abc123xyz \
  nimbitlabs/hydranaut-agent:latest

Docker Compose

docker-compose pull
docker-compose up -d

Kubernetes

kubectl rollout restart deployment/hydranaut-agent -n monitoring

Multi-Region Deployment

For monitoring services across multiple regions or data centers:

Deploy an agent in each region
Each agent will automatically report its location
Configure services to be monitored by specific agents
View regional health status in the Hydranaut dashboard

# US East Agent
docker run -d \
  --name hydranaut-agent-us-east \
  -e HYDRANAUT_API_KEY=sp_abc123xyz \
  -e Agent__Location=us-east-1 \
  nimbitlabs/hydranaut-agent:latest

# EU West Agent
docker run -d \
  --name hydranaut-agent-eu-west \
  -e HYDRANAUT_API_KEY=sp_abc123xyz \
  -e Agent__Location=eu-west-1 \
  nimbitlabs/hydranaut-agent:latest

Support

Need help with agent deployment?

📧 Email: support@nimbitlabs.com
📚 Documentation: docs.nimbitlabs.com
🐛 Report issues: GitHub Issues

Quick Start​

Getting Your API Key​

Deployment Options​

Docker​

Basic Deployment​

With Persistent Logs​

With Debug Logging​

Docker Compose​

Kubernetes​

Systemd Service (Linux)​

Configuration​

Environment Variables​

Advanced Configuration​

Monitoring the Agent​

View Logs​

Check Health Status​

Verify Agent is Working​

Troubleshooting​

Agent Not Connecting​

Invalid API Key Error​

High Resource Usage​

Container Keeps Restarting​

Security Best Practices​

API Key Management​

Network Security​

Container Security​

Updating the Agent​

Docker​

Docker Compose​

Kubernetes​

Multi-Region Deployment​

Support​

Quick Start

Getting Your API Key

Deployment Options

Docker

Basic Deployment

With Persistent Logs

With Debug Logging

Docker Compose

Kubernetes

Systemd Service (Linux)

Configuration

Environment Variables

Advanced Configuration

Monitoring the Agent

View Logs

Check Health Status

Verify Agent is Working

Troubleshooting

Agent Not Connecting

Invalid API Key Error

High Resource Usage

Container Keeps Restarting

Security Best Practices

API Key Management

Network Security

Container Security

Updating the Agent

Docker

Docker Compose

Kubernetes

Multi-Region Deployment

Support