Quick Start

This guide gets the Iotistica Agent running on your device and walks you through connecting your first industrial endpoint.

Prerequisites

• A Linux device (Raspberry Pi, industrial PC, or x86-64 server) with systemd
• The install script supports: Debian, Ubuntu, Raspberry Pi OS, RHEL, Fedora, CentOS, Alpine, and Arch Linux
• Docker Compose works on any Linux distribution

---

Install Script

The quickest path on a Debian-based device. The script sets up everything — system packages, Node.js, Docker, user accounts, and the systemd service:

TRY IT NOW

$ curl -sfL https://get.iotistica.com/agent | sudo sh

Interactive prompts

The script walks you through a short setup wizard:

Install Docker?                          (yes/no)
Install local Mosquitto MQTT broker?     (yes/no)

 Deployment Mode
 ────────────────────────────────────────
  1) Standalone  — fully offline, local admin UI only
  2) Cloud       — connect to Iotistica Cloud

Select mode [1/2]:

# If Cloud is selected:
Iotistica API URL [https://api.iotistica.com]:
Provisioning key:

Device API port [48484]:

If Mosquitto's default port 1883 is already in use (for example by a Docker container), the script detects this and asks for an alternative:

⚠️  Port 1883 is already in use by another process.
Enter an alternative port for Mosquitto [8883]:

Non-interactive / CI mode

Pass environment variables before the pipe to skip all prompts:

IOTISTICA_INSTALL_DOCKER=yes \
IOTISTICA_INSTALL_MOSQUITTO=yes \
IOTISTICA_API=https://api.iotistica.com \
PROVISIONING_KEY=your-provisioning-key \
IOTISTICA_DEVICE_PORT=48484 \
curl -sfL https://get.iotistica.com/agent | sudo sh

For standalone (offline) mode, omit IOTISTICA_API and PROVISIONING_KEY.

Variable	Default	Description
IOTISTICA_INSTALL_DOCKER	—	Set yes to allow auto-installing Docker
IOTISTICA_INSTALL_MOSQUITTO	—	Set yes to install and manage a local Mosquitto broker
MQTT_BROKER_PORT	1883	Mosquitto listener port — change if 1883 is already in use
IOTISTICA_API	—	Cloud API URL (omit for standalone mode)
PROVISIONING_KEY	—	One-time provisioning token from the Iotistica Cloud console
IOTISTICA_DEVICE_PORT	48484	Local device API and admin UI port
IOTISTICA_AGENT_VERSION	latest	Pin to a specific agent version

What the script does

Step	Action
1	Installs system packages via apt (curl, git, sqlite3, networking tools)
2	Installs Node.js 24 if missing or below v18
3	Installs Docker if missing and IOTISTICA_INSTALL_DOCKER=yes
4	Creates iotistic system user and adds it to the docker group
5	Checks if the Mosquitto port is free; prompts for an alternative if not
6	Optionally installs and configures a local Mosquitto MQTT broker
7	Downloads the pre-built agent tarball for your architecture (x86_64, arm64)
8	Writes /etc/iotistic/agent.env with configuration and secrets (mode 600)
9	Creates and starts iotistica-agent as a systemd service — enabled on boot, auto-restarts on failure
10	Installs the iotctl command-line tool

Once the script finishes, the admin UI is available at:

http://[device-ip]:48484/admin/

Check status and follow logs:

systemctl status iotistica-agent
journalctl -u iotistica-agent -f

---

Install with Docker Compose

For full control over ports, volumes, and environment variables — or if you're running a non-Debian OS — use Docker Compose directly.

Step 1 — Create a working directory

mkdir iotistica-agent && cd iotistica-agent

Step 2 — Create docker-compose.yml

services:
  agent:
    image: iotistica/agent:latest
    container_name: iotistica-agent
    restart: unless-stopped
    mem_limit: 512m
    mem_reservation: 256m
    cap_add:
      - NET_ADMIN
    ports:
      - "${AGENT_PORT:-48481}:48481"
    volumes:
      - agent-data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      # Core
      - NODE_ENV=production
      - STANDALONE=true
      - DEVICE_API_PORT=48481
      - API_SECURITY_MODE=${API_SECURITY_MODE:-LOCAL_NETWORK}

      # MQTT connectivity (optional — leave blank for fully offline/standalone)
      - MQTT_BROKER_URL=${MQTT_BROKER_URL:-}
      - MQTT_USERNAME=${MQTT_USERNAME:-}
      - MQTT_PASSWORD=${MQTT_PASSWORD:-}

      # Remote shell security (generate a random string and keep it secret)
      - AGENT_SHELL_HMAC_KEY=${AGENT_SHELL_HMAC_KEY}

volumes:
  agent-data:
    driver: local

Step 3 — Create .env

# ── Required ──────────────────────────────────────────────────────────────────

# Secret key for the remote shell — generate with: openssl rand -hex 32
AGENT_SHELL_HMAC_KEY=replace-with-a-random-secret

# ── Optional ──────────────────────────────────────────────────────────────────

# Admin UI port (default 48481)
AGENT_PORT=48481

# Security mode: LOCAL_NETWORK (default) trusts requests from the local subnet.
# Use STRICT to require authentication on all API calls.
API_SECURITY_MODE=LOCAL_NETWORK

# MQTT broker — fill in if you want the agent to forward data to a broker.
# Leave blank for fully standalone operation.
MQTT_BROKER_URL=
MQTT_USERNAME=
MQTT_PASSWORD=

:::tip Generating a secret key

openssl rand -hex 32

:::

Step 4 — Start the agent

docker compose up -d

Follow startup logs:

docker compose logs -f agent

---

Access the Admin UI

Open a browser on your local network:

Install method	Default URL
Install script (systemd)	http://[device-ip]:48484/admin/
Docker Compose	http://[device-ip]:48481/admin/

Log in with the default credentials: admin / admin. Change the password immediately from Administration → Users.

---

Add Your First Endpoint

An endpoint is a connection to one of your industrial devices:

1. Go to Endpoints in the sidebar.
2. Click Add Endpoint.
3. Fill in the connection details (host, port, protocol).
4. Set a poll interval — 5000 ms is a good start.
5. Click Save.

The endpoint appears in the list. If the device is reachable it connects within a few seconds.

Not sure of the connection details? Click Discover — the agent scans your network and finds compatible devices automatically.

---

Send Data Somewhere

Data is collected locally by default. To forward it to an MQTT broker or cloud destination:

1. Go to Destinations → New Destination.
2. Choose the type (MQTT, InfluxDB, Azure IoT Hub, etc.) and fill in the connection settings.
3. Go to Subscriptions → New Subscription.
4. Select your destination and configure the payload format.
5. Save — data starts flowing immediately.

---

Updating the Agent

Install script (systemd): re-run the installer. It replaces the agent binary and restarts the service, preserving /etc/iotistic/agent.env and the database.

UPDATE

$ curl -sfL https://get.iotistica.com/agent | sudo sh

Docker Compose: pull the latest image and restart:

docker compose pull && docker compose up -d

Your data volume (agent-data) is preserved across updates.

---

Next Steps

• Endpoints — supported protocols and connection settings
• Integrations — MQTT and cloud destinations
• Discovery — auto-detect devices on your network
• Alerts — anomaly detection and alerting