Skip to content

Zelos Agent Installation

The Zelos Agent is a lightweight service for capturing tracing data on headless systems, edge devices, and servers.

Zelos Agent

If you're not running on a headless device, you don't need to install this. The app bundles its own flavor of the agent for you!

Overview

  • Lightweight

    Minimal resource usage with configurable data retention

  • Network Ready

    gRPC endpoint on port 2300 for SDK connections

  • Systemd Managed

    Runs as a system service with automatic startup

  • Data Buffering

    Temporary storage with configurable retention time

System Requirements

Platform Support

  • Ubuntu 22.04 LTS (Jammy) and 24.04 LTS (Noble) — tested targets
  • Architectures: amd64 and arm64 (also runs on 64-bit Debian / Raspberry Pi OS)

Check yours with dpkg --print-architecture (must be amd64 or arm64; armhf is not built). For other platforms, contact support.

Installation

# Remove an old Zelos source so apt does not list Zelos twice
sudo rm -f /etc/apt/sources.list.d/zelos.list

# Add the Zelos signing key and repository
sudo wget -qO /usr/share/keyrings/zelos-archive-keyring.gpg https://release.zeloscloud.io/app/zelos-archive-keyring.gpg
printf '%s\n' 'Types: deb' 'URIs: https://release.zeloscloud.io:443/app/ubuntu' 'Suites: jammy' 'Components: main' 'Signed-By: /usr/share/keyrings/zelos-archive-keyring.gpg' | sudo tee /etc/apt/sources.list.d/zelos.sources

# Install the agent
sudo apt update
sudo apt install zelos-agent

For early releases, use the alpha repository instead:

sudo rm -f /etc/apt/sources.list.d/zelos.list
sudo wget -qO /usr/share/keyrings/zelos-archive-keyring.gpg https://release.zeloscloud.io/app/zelos-archive-keyring.gpg
printf '%s\n' 'Types: deb' 'URIs: https://release.zeloscloud.io:443/app/alpha/ubuntu' 'Suites: jammy' 'Components: main' 'Signed-By: /usr/share/keyrings/zelos-archive-keyring.gpg' | sudo tee /etc/apt/sources.list.d/zelos.sources
sudo apt update
sudo apt install zelos-agent

Debian & Raspberry Pi

Keep Suites: jammy on every system. It is the repository's name, not your OS version, and apt pulls the matching amd64/arm64 build. Always add the repository (don't install a standalone .deb), so sudo apt update && sudo apt install --only-upgrade zelos-agent keeps the agent current.

Already installed from the Zelos repository?

You do not need to do anything. Your next agent update moves you to the signed repository and keeps your channel.

Auto-start Enabled

The agent starts automatically after installation and on system boot.

Verify Installation

sudo systemctl status zelos-agent

Expected output: 

● zelos-agent.service - Zelos Agent
     Loaded: loaded (/lib/systemd/system/zelos-agent.service; enabled)
     Active: active (running) since Mon 2024-01-15 10:30:00 UTC
     ...

Configuration

Default Settings

Setting Default Value Description
Listen Address 0.0.0.0:2300 Binds to all IPv4 interfaces
Store Type metadata Catalog only, no sample data
Data Retention 1h How long to keep data

Customize Configuration

To bind to a specific interface or change the port. The agent always also serves 127.0.0.1. The IPv6 wildcard [::] is accepted and served as 0.0.0.0 (all IPv4 interfaces); no IPv6 wildcard listener is bound.

sudo systemctl edit zelos-agent

Add:

/etc/systemd/system/zelos-agent.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/zelos-agent --listen-address 127.0.0.1:2300

For more data retention at the cost of memory:

sudo systemctl edit zelos-agent

Add:

/etc/systemd/system/zelos-agent.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/zelos-agent --store-type memory --store-retain-duration 24h

For troubleshooting:

sudo systemctl edit zelos-agent

Add:

/etc/systemd/system/zelos-agent.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/zelos-agent -vv

After making changes: 

sudo systemctl daemon-reload
sudo systemctl restart zelos-agent

Command Line Options

Option Description Example
--listen-address Set bind address --listen-address [::1]:2300
--store-type Storage backend: metadata, memory, or disk --store-type memory
--store-retain-duration Data retention --store-retain-duration 6h
-v, -vv Increase verbosity -vv for trace level
-q Quiet mode -q

Service Management

# Start the agent
sudo systemctl start zelos-agent

# Stop the agent
sudo systemctl stop zelos-agent

# Restart the agent
sudo systemctl restart zelos-agent

# Check status
sudo systemctl status zelos-agent

# Last 50 lines
sudo journalctl -u zelos-agent -n 50

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

# Logs from last hour
sudo journalctl -u zelos-agent --since "1 hour ago"

# Today's logs
sudo journalctl -u zelos-agent --since today

# Disable auto-start on boot
sudo systemctl disable zelos-agent

# Re-enable auto-start
sudo systemctl enable zelos-agent

Uninstallation

To remove the agent and keep the Zelos repository:

sudo apt remove zelos-agent

To also remove the Zelos repository and its signing key, purge the package instead:

sudo apt purge zelos-agent

Purge keeps the repository if the Zelos App is still installed, because the app updates from it too.

To remove any custom configuration:

sudo rm -rf /etc/systemd/system/zelos-agent.service.d
sudo systemctl daemon-reload

Troubleshooting

Agent won't start

Check for port conflicts: 

sudo lsof -i :2300

View detailed error messages: 

sudo journalctl -u zelos-agent -n 100 --no-pager

Try running manually to see errors: 

sudo /usr/bin/zelos-agent -vv

If the agent runs out of memory, fall back to the catalog-only store. Run sudo systemctl edit zelos-agent and add: 

[Service]
ExecStart=
ExecStart=/usr/bin/zelos-agent --store-type metadata

🚀 Next Steps