Skip to Content
Edge AgentInstallation & Upgrade

Edge Agent Installation

The one-line installer detects your OS and architecture, downloads the appropriate binary, and configures the agent as a system service.

curl -fsSL https://install.atlastechlab.com/agent \
  | bash -s -- \
    --tenant-url <TENANT_PLANE_URL> \
    --api-key <AGENT_API_KEY>

Find your Tenant URL and API Key in the AtlasAI UI under Settings → Edge Agents → Installation.

The installer performs the following steps:

  1. Detects OS and architecture
  2. Downloads the atlas-agent binary to /usr/local/bin/
  3. Creates the configuration directory at /etc/atlasai/
  4. Generates a default configuration file at /etc/atlasai/agent.yaml
  5. Installs and enables a systemd service (atlasai-agent.service)
  6. Starts the agent and verifies connectivity to the Tenant Plane

Package Manager Install

Debian / Ubuntu (DEB)

curl -fsSL https://packages.atlastechlab.com/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/atlasai-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/atlasai-archive-keyring.gpg] https://packages.atlastechlab.com/deb stable main" | sudo tee /etc/apt/sources.list.d/atlasai.list
sudo apt update
sudo apt install atlasai-agent

RHEL / CentOS / Amazon Linux (RPM)

sudo rpm --import https://packages.atlastechlab.com/gpg.key
sudo tee /etc/yum.repos.d/atlasai.repo <<EOF
[atlasai]
name=AtlasAI Repository
baseurl=https://packages.atlastechlab.com/rpm
enabled=1
gpgcheck=1
gpgkey=https://packages.atlastechlab.com/gpg.key
EOF
sudo yum install atlasai-agent

Kubernetes DaemonSet

Deploy the agent as a DaemonSet to run on every node in your cluster:

kubectl create namespace atlasai
kubectl apply -f https://install.atlastechlab.com/agent/k8s-daemonset.yaml

Configure the agent using a ConfigMap:

kubectl create configmap atlasai-agent-config -n atlasai \
  --from-literal=TENANT_URL=<TENANT_PLANE_URL> \
  --from-literal=API_KEY=<AGENT_API_KEY>

Alternatively, use the Helm chart:

helm repo add atlasai https://charts.atlastechlab.com
helm install atlasai-agent atlasai/edge-agent \
  --namespace atlasai --create-namespace \
  --set tenantUrl=<TENANT_PLANE_URL> \
  --set apiKey=<AGENT_API_KEY>

Docker

Run the agent as a Docker container (useful for testing):

docker run -d \
  --name atlasai-agent \
  --pid=host \
  --network=host \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /var/log:/host/var/log:ro \
  -e TENANT_URL=<TENANT_PLANE_URL> \
  -e API_KEY=<AGENT_API_KEY> \
  atlasai/edge-agent:latest

Verifying Installation

After installation, verify the agent is running and connected:

sudo systemctl status atlasai-agent

Check the agent logs:

sudo journalctl -u atlasai-agent -f

Verify the agent appears in the AtlasAI UI under Settings → Edge Agents. It should show as Connected within 30 seconds of starting.

Uninstalling

Script-installed agent

sudo systemctl stop atlasai-agent
sudo systemctl disable atlasai-agent
sudo rm /usr/local/bin/atlas-agent
sudo rm -rf /etc/atlasai
sudo rm /etc/systemd/system/atlasai-agent.service
sudo systemctl daemon-reload

DEB package

sudo apt remove atlasai-agent

RPM package

sudo yum remove atlasai-agent

Kubernetes

helm uninstall atlasai-agent -n atlasai
kubectl delete namespace atlasai

Air-Gapped Installation

Use this when the agent host has no internet access.

Step 1: Download the binary on a connected machine

# Download the binary for your target platform
# Linux x64
curl -LO https://dl.atlastechlab.com/agent/latest/linux-amd64/atlas-edge-agent
 
# Linux ARM64
curl -LO https://dl.atlastechlab.com/agent/latest/linux-arm64/atlas-edge-agent
 
# Or download the npm tarball for local install
npm pack @atlasai/edge-agent@1.3.0
# Creates: atlasai-edge-agent-1.3.0.tgz

Step 2: Transfer to the air-gapped host

# Via SCP
scp atlas-edge-agent admin@air-gapped-host:/tmp/
 
# Via removable media
cp atlas-edge-agent /media/usb/
# ... physically transfer USB drive ...

Step 3: Install on the air-gapped host

# Copy binary to path
sudo install -m 755 /tmp/atlas-edge-agent /usr/local/bin/atlas-edge-agent
 
# Create config directory
sudo mkdir -p /etc/atlasai
 
# Create configuration file
sudo tee /etc/atlasai/agent.yaml <<EOF
tenantUrl: http://your-tenant-plane:3000
tenantId: acme-corp
apiKey: your-agent-api-key
hostname: $(hostname)
mode: host
EOF
 
# Create systemd service
sudo tee /etc/systemd/system/atlas-edge-agent.service <<EOF
[Unit]
Description=AtlasAI Edge Agent
After=network.target
 
[Service]
Type=simple
ExecStart=/usr/local/bin/atlas-edge-agent run
Restart=always
RestartSec=10
 
[Install]
WantedBy=multi-user.target
EOF
 
sudo systemctl daemon-reload
sudo systemctl enable atlas-edge-agent
sudo systemctl start atlas-edge-agent

Upgrading the Edge Agent

Online upgrade (internet access)

# Linux service upgrade
npm install -g @atlasai/edge-agent@1.3.0
sudo systemctl restart atlas-edge-agent

Or use the included upgrade script:

# Upgrade to latest
bash packages/edge-agent/scripts/upgrade-linux-service.sh
 
# Upgrade to a specific version
EDGE_AGENT_VERSION=1.3.0 bash packages/edge-agent/scripts/upgrade-linux-service.sh

Air-gapped upgrade (no internet — pull from Tenant Plane)

For fully air-gapped environments, the Tenant Plane serves upgrade bundles directly to agents. When a new version is available:

Admin step (once per version):

  1. Download the new bundle on a connected machine:

    # Download the npm tarball
npm pack @atlasai/edge-agent@1.3.0
# File: atlasai-edge-agent-1.3.0.tgz

  2. Transfer the bundle to the Tenant Plane server:

    scp atlasai-edge-agent-1.3.0.tgz admin@tenant-plane-server:/app/edge-bundles/

  3. Set the desired version in the Tenant Plane admin UI or via API:

    # Via API
curl -X POST https://your-tenant-plane/api/admin/edge-upgrade \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"desired_version": "1.3.0"}'

Agent step (automatic):

On the next heartbeat (within 30 seconds), each agent automatically:

  1. Receives the desired version and download URL from the Tenant Plane
  2. Downloads the bundle from the Tenant Plane (no external network needed)
  3. Verifies the SHA256 checksum
  4. Installs the new version
  5. Restarts itself via systemd

The agent logs show progress:

[atlas-edge] Self-update: 1.2.2 → 1.3.0
[atlas-edge] Downloading bundle from: http://your-tenant-plane/api/collectors/upgrade-bundle?version=1.3.0
[atlas-edge] SHA256 verified: abc123...
[atlas-edge] Restarting via systemd...

To disable automatic self-update (update manually instead):

# Set this on the agent host
ATLAS_EDGE_AUTO_UPDATE=0
# Then restart: sudo systemctl restart atlas-edge-agent

Rolling back the Edge Agent

# Roll back to version 1.2.2
bash packages/edge-agent/scripts/rollback-linux-service.sh 1.2.2

Or manually:

npm install -g @atlasai/edge-agent@1.2.2
sudo systemctl restart atlas-edge-agent
OverviewConfiguration