Eight.ly Agent — Multi-Host Docker Management¶

Eight.ly Agent is a lightweight, cross-platform Docker management daemon. Install it on any Docker host — Linux, macOS, or Windows — register it with your Eight.ly OS instance, and manage all your containers from one dashboard.

Included at no charge with every Eight.ly licence. Nothing else in Eight.ly is free, but the Agent and Eight.ly Backup Server are.

Apache 2.0 licensed.

Where to find it: The Remote Environments page registers a host; once registered, the environment switcher in the Docker page header lets you switch between your local Docker and any registered remote hosts.

How It Works¶

Eight.ly OS Dashboard
        │
        │ HTTPS + Bearer Token (HMAC-SHA256)
        ▼
Eight.ly Agent (:9001)
        │
        │ Unix Socket (Linux/macOS) or Named Pipe (Windows)
        ▼
Docker Engine

The agent proxies authenticated API requests to the local Docker socket, providing container management, WebSocket console, file browsing, and host info — all over TLS.

Installing the Agent¶

Docker (recommended, works today)¶

docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 9001:9001 \
  -e EIGHTLY_AGENT_SECRET="your-shared-secret" \
  -e EIGHTLY_SERVER_URL="https://your-eos-server:8080" \
  smashingtags/eightly-agent:latest

The GHCR mirror (ghcr.io/imogenlabs/eightly-agent:latest) lands when the repo goes public at launch — use the Docker Hub image above until then.

Docker Compose¶

# docker-compose.yml
services:
  eightly-agent:
    image: smashingtags/eightly-agent:latest
    restart: unless-stopped
    ports:
      - "9001:9001"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      EIGHTLY_AGENT_SECRET: "your-shared-secret"
      EIGHTLY_SERVER_URL: "https://your-eos-server:8080"

docker compose up -d

Homebrew (macOS / Linux) — at launch¶

brew install imogenlabs/tap/eightly-agent

Scoop (Windows) — at launch¶

scoop bucket add eightly https://github.com/imogenlabs/scoop-eightly
scoop install eightly-agent

Debian / Ubuntu (.deb) — at launch¶

Downloads from GitHub Releases once the repo is public:

sudo dpkg -i eightly-agent_*.deb
sudo systemctl enable --now eightly-agent

RHEL / Fedora (.rpm) — at launch¶

sudo rpm -i eightly-agent-*.rpm
sudo systemctl enable --now eightly-agent

Binary Download — at launch¶

Binaries for all platforms will be available at GitHub Releases once the repo is public:

• Linux (amd64 / arm64)
• macOS (Intel / Apple Silicon)
• Windows (amd64)

Platform-Specific Setup¶

Linux (systemd)¶

The .deb and .rpm packages install a systemd service automatically. For manual installs:

sudo cp deploy/eightly-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now eightly-agent

Configure via a drop-in override:

sudo systemctl edit eightly-agent

[Service]
Environment=EIGHTLY_AGENT_SECRET=your-shared-secret
Environment=EIGHTLY_SERVER_URL=https://your-eos-server:8080

macOS (launchd)¶

brew services start eightly-agent

Or run interactively:

eightly-agent --secret "your-shared-secret" --server-url "https://your-eos-server:8080"

Windows (Windows Service)¶

The Windows binary supports native service management — no terminal window, starts on boot:

# Install and start (run as Administrator)
eightly-agent.exe install
eightly-agent.exe start

# Manage
eightly-agent.exe status
eightly-agent.exe stop
eightly-agent.exe uninstall

Configure via system environment variables. Default data path: C:\ProgramData\eightly-agent.

Registering a Remote Host¶

1. Navigate to Remote Environments in Eight.ly OS
2. Click Add Agent
3. Enter the remote host's IP/hostname and the agent port (default: 9001)
4. The agent authenticates using a one-time enrollment token
5. Once registered, the host appears in the environment selector on the Docker page

Managing Remote Containers¶

Once registered, switch to a remote environment using the dropdown in the Docker page header. All container operations work identically to local:

• Container lifecycle (start, stop, restart, kill, pause, remove, recreate)
• Logs (SSE streaming)
• Stats (live charts)
• Inspect (JSON tree)
• Console (xterm.js terminal into the container)
• Stack deploy
• Image management
• Volume file browser (list, upload, download, delete, rename)

Heartbeat Monitoring¶

Each agent sends heartbeats to Eight.ly OS every 30 seconds. If heartbeats are missed, the environment shows a warning indicator. The agent dashboard displays:

• Connection status (online/offline)
• Last heartbeat timestamp
• Agent version
• Host info (PCI devices, physical disks)

Prometheus Metrics¶

Enable the /metrics endpoint with the --metrics flag (or EIGHTLY_METRICS=true). The endpoint requires the same HMAC Bearer token as all other endpoints.

# Enable metrics
eightly-agent --metrics --secret "your-shared-secret" --server-url "https://your-eos-server:8080"

Scrape config for Prometheus:

scrape_configs:
  - job_name: eightly-agent
    scheme: https
    tls_config:
      insecure_skip_verify: true  # if using self-signed certs
    authorization:
      type: Bearer
      credentials: "<your-hmac-token>"
    static_configs:
      - targets: ["agent-host:9001"]

Configuration¶

Security¶

• Fail-closed TLS — uses the system trust store by default; --insecure-server-tls required to explicitly opt in to skipping verification
• HMAC-SHA256 authentication — every request (except /ping) requires a valid Bearer token
• No exposed Docker socket — the agent mediates all access
• Single-use enrollment tokens — consumed on first registration
• Automatic re-registration — recovers from connection loss
• Signed releases — binaries are built to be signed with provenance and SBOM attestations once releases are public

Use Cases¶

• Multi-server homelab — manage a media server, a backup server, and a dev box from one UI
• Remote sites — manage Docker hosts at a remote location via Tailscale/VPN
• Mixed OS fleet — Linux NAS, macOS dev machine, Windows GPU server — all managed centrally
• Separation of concerns — run AI workloads on a GPU server, media on a NAS, both managed from Eight.ly OS

Resources¶

• Docker Hub — works today
• GitHub Repository (Apache 2.0) — public at launch
• Full Wiki — API reference, authentication, troubleshooting — public at launch
• Homebrew Tap — formula points at release binaries that ship at launch
• Scoop Bucket — same, ships at launch