Skip to main content

Edge Agent Installation

System requirements​

RequirementMinimum
OSLinux (x86_64, ARM64), Windows Server 2016+
RAM128 MB
Disk50 MB + buffer space
NetworkOutbound HTTPS (port 443) to api.haltless.io
RuntimePython 3.10+ or Docker

Installation methods​

docker pull ghcr.io/haltless/edge-agent:latest

docker run -d \
  --name haltless-agent \
  --restart unless-stopped \
  -e HALTLESS_API_KEY="your_api_key_here" \
  -e HALTLESS_API_URL="https://api.haltless.io" \
  -v /opt/haltless/config:/etc/haltless \
  ghcr.io/haltless/edge-agent:latest

Docker Compose​

Create a docker-compose.yml:

services:
  haltless-agent:
    image: ghcr.io/haltless/edge-agent:latest
    restart: unless-stopped
    environment:
      HALTLESS_API_KEY: "${HALTLESS_API_KEY}"
      HALTLESS_API_URL: "https://api.haltless.io"
      HALTLESS_POLL_INTERVAL: "30"
      HALTLESS_BATCH_SIZE: "100"
    volumes:
      - ./config:/etc/haltless
      - ./data:/var/lib/haltless
HALTLESS_API_KEY=your_key docker compose up -d

Linux (systemd)​

# Download the agent
curl -fsSL https://get.haltless.io/agent | bash

# Configure
sudo nano /etc/haltless/agent.toml

# Enable and start the service
sudo systemctl enable haltless-agent
sudo systemctl start haltless-agent

Windows​

Download the MSI installer from the Haltless dashboard (Settings > Edge Agent > Download) and follow the setup wizard. The agent installs as a Windows service.

Verifying the installation​

Check that the agent can reach the Haltless cloud:

# Docker
docker logs haltless-agent

# Linux
sudo journalctl -u haltless-agent -f

# Manual test
curl -s https://api.haltless.io/api/v1/agent/heartbeat \
  -H "X-API-Key: YOUR_API_KEY"

Expected output:

{
  "status": "active",
  "next_check_seconds": 300
}

Firewall requirements​

The agent only needs outbound connectivity:

DestinationPortProtocolPurpose
api.haltless.io443HTTPSAPI calls and data push

No inbound ports need to be opened. If you use a proxy, set the HTTPS_PROXY environment variable:

export HTTPS_PROXY=http://proxy.internal:8080

Updating​

Docker​

docker pull ghcr.io/haltless/edge-agent:latest
docker compose up -d

Linux​

sudo haltless-agent update
sudo systemctl restart haltless-agent

Next steps​