Skip to content

Zelos Agent Installation

The Zelos agent runs as a service on Linux machines without a screen: bench computers, test rigs, edge devices and servers. It runs extensions, receives data from SDK code, runs notebooks, and serves everything to any Zelos app that connects to it.

Using the app?

On a machine with the Zelos app, you do not need this. The app includes its own agent.

Overview

  • Extensions

    Runs the same extensions as the app's agent

  • Network Ready

    Serves apps, SDK code and the CLI on port 2300

  • Notebooks

    Runs notebooks headless with zelos notebook run

  • Systemd Managed

    Runs as a system service with automatic startup

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 in a memory or disk store

The default store keeps no samples

With the metadata store, the agent lists the signals that exist and streams them live to a connected app. It keeps no history, so queries, notebooks that read past data, and trace exports fail. To keep data, use a memory or disk store (see Enable Memory Store below).

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

To keep data for queries, notebooks and trace exports, 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
--memory-limit Memory cap for the memory store --memory-limit 2GB
--store-path Parent folder for the disk store --store-path /data/zelos
--disk-limit Size cap for the disk store --disk-limit 50GB
--dev-mode Enable development mode features --dev-mode true
-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