Skip to main content

​
Device Provisioning

This guide walks through the complete process of onboarding edge devices to Acusight using provisioning tokens.

​
Overview

Acusight uses a token-based provisioning flow to securely onboard edge devices: 
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Admin creates  │────▶│  Token used on  │────▶│ Device appears  │
│    token in UI  │     │  edge device    │     │  in dashboard   │
└─────────────────┘     └─────────────────┘     └─────────────────┘
  1. Admin creates a provisioning token in the Acusight dashboard
  2. Token is used on the edge device via a setup script
  3. Device exchanges token for an API key and begins reporting to the platform
  4. Device appears in the dashboard with live status

​
Prerequisites

  • Edge device running Linux (aarch64/arm64) with Docker installed
  • SSH access to the edge device
  • Acusight platform running with SERVER_EXTERNAL_IP configured

​
Step 1: Create a Provisioning Token

  1. Log in to the Acusight dashboard
  2. Navigate to Settings → Provisioning
  3. Click Create Token
  4. Configure the token:
    • Name: A descriptive name (e.g., “Production Line 1”)
    • Expiration: When the token should expire (default: 30 days)
    • Single Use: Whether the token should auto-revoke after first use
  5. Click Create
  6. Copy the token immediately - it’s only shown once!
The UI will display a setup command you can paste directly on the device.

​
Via API

curl -X POST https://<SERVER>/api/provisioning-tokens \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Line 1",
    "expires_in_days": 30,
    "single_use": true
  }'
Response: 
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Line 1",
    "token": "apt_abc123...",
    "single_use": true,
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2024-02-14T10:30:00Z",
    "setup_command": "curl -sSL https://acusight.io/setup | sh -s -- apt_abc123..."
  }
}
The token field is only returned once at creation time. Store it securely or use the setup_command immediately.

​
Step 2: Run the Setup Script

SSH into your edge device and run the setup command: 
# Cloud (recommended) - run as root or with sudo
curl -sSL https://acusight.io/setup | sh -s -- apt_<TOKEN>

# LAN/local
curl -sSL http://<SERVER_IP>:8080/setup | sh -s -- apt_<TOKEN>
The script will:
  1. Validate the provisioning token
  2. Register the device with Acusight
  3. Receive an API key and (optionally) a Portainer Edge key
  4. Write configuration to /etc/acusight/agent.conf
  5. Pull and start the Acusight agent container

​
What the Setup Script Does

# 1. Get device identity from Docker
DEVICE_ID=$(docker system info --format "{{.ID}}")

# 2. Exchange token for API key
curl -X POST http://<SERVER>:8080/api/devices/provision \
  -d '{"token":"apt_...", "device_info":{"device_id":"..."}}'

# 3. Write agent config
cat > /etc/acusight/agent.conf <<EOF
ACUSIGHT_DEVICE_ID=<device_id>
ACUSIGHT_API_KEY=adk_<key>
ACUSIGHT_API_ENDPOINT=http://<SERVER>:8080
EOF

# 4. Start the agent
docker run -d --name acusight-agent \
  -v /etc/acusight:/etc/acusight:ro \
  arcturusnetworks/acusight-agent:latest

​
Step 3: Verify the Device

​
Check Agent Logs

docker logs acusight-agent 2>&1 | head -30
Look for:
  • Cloud mode - Confirms the agent is connecting via HTTP
  • Heartbeat worker started - Agent is sending health checks

​
Check Device Status via API

curl http://<SERVER>:8080/api/device/self \
  -H "X-Device-Key: adk_<KEY>"

​
View in Dashboard

The device should appear on the Devices page with status “Online” (green dot).

​
Token Management

​
List Tokens

curl https://<SERVER>/api/provisioning-tokens \
  -H "Authorization: Bearer <YOUR_TOKEN>"

​
Revoke a Token

curl -X DELETE https://<SERVER>/api/provisioning-tokens/<TOKEN_ID> \
  -H "Authorization: Bearer <YOUR_TOKEN>"
Revoking a token prevents it from being used to provision new devices. Already-provisioned devices are not affected.

​
Advanced: Manual Provisioning

If you need more control over the provisioning process: 
# 1. Get device identity
DEVICE_ID=$(docker system info --format "{{.ID}}")
DEVICE_NAME=$(hostname)

# 2. Provision the device
curl -X POST http://<SERVER>:8080/api/devices/provision \
  -H "Content-Type: application/json" \
  -d "{
    \"token\": \"apt_<TOKEN>\",
    \"device_info\": {
      \"device_id\": \"${DEVICE_ID}\",
      \"name\": \"${DEVICE_NAME}\",
      \"ip_address\": \"$(hostname -I | awk '{print $1}')\"
    }
  }"

# 3. Save the response
# {
#   "device_id": "...",
#   "api_key": "adk_...",
#   "api_endpoint": "http://...:8080",
#   "edge_key": "..." (optional)
# }

# 4. Write config manually
mkdir -p /etc/acusight
cat > /etc/acusight/agent.conf <<EOF
ACUSIGHT_DEVICE_ID=<device_id>
ACUSIGHT_API_KEY=<api_key>
ACUSIGHT_API_ENDPOINT=<api_endpoint>
EOF
chmod 600 /etc/acusight/agent.conf

# 5. Start agent
docker run -d --name acusight-agent \
  --restart unless-stopped \
  --network host \
  -v /etc/acusight:/etc/acusight:ro \
  -v acusight-agent-data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  arcturusnetworks/acusight-agent:latest

​
Troubleshooting

ProblemCauseSolution
409 DEVICE_EXISTSDevice already registeredDelete via API and re-provision
401 INVALID_TOKENToken expired or revokedCreate a new token
401 TOKEN_EXPIREDToken past expiration dateCreate a new token
Agent shows “connection refused”SERVER_EXTERNAL_IP wrongCheck .env and rebuild

​
Re-provisioning a Device

If you need to re-provision a device (e.g., after a factory reset):
  1. Delete the device from the dashboard or API: 
    curl -X DELETE http://<SERVER>/api/core/devices/<DEVICE_ID> \
  -H "Authorization: Bearer <TOKEN>"
  2. On the device, remove the old config: 
    docker rm -f acusight-agent
rm -rf /etc/acusight
  3. Create a new provisioning token and run the setup script again.

​
Next Steps

Data Collection

Learn how devices send data to Acusight

API Reference

Explore the full provisioning API