> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acusight.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Device Provisioning

> How to onboard edge devices to Acusight

# 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 (hostname and IP are auto-detected at startup)

## Step 1: Create a Provisioning Token

### Via the Dashboard (Recommended)

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

```bash theme={null}
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:

```json theme={null}
{
  "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..."
  }
}
```

<Warning>
  The `token` field is only returned once at creation time. Store it securely or use the `setup_command` immediately.
</Warning>

## Step 2: Run the Setup Script

SSH into your edge device and run the setup command:

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
curl https://<SERVER>/api/provisioning-tokens \
  -H "Authorization: Bearer <YOUR_TOKEN>"
```

### Revoke a Token

```bash theme={null}
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:

```bash theme={null}
# 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

| Problem                          | Cause                                       | Solution                                                               |
| -------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------- |
| `409 DEVICE_EXISTS`              | Device already registered                   | Delete via API and re-provision                                        |
| `401 INVALID_TOKEN`              | Token expired or revoked                    | Create a new token                                                     |
| `401 TOKEN_EXPIRED`              | Token past expiration date                  | Create a new token                                                     |
| Agent shows "connection refused" | `LAN_IP` wrong or incorrectly auto-detected | Check `.env`; on LAN re-run `scripts/install-acusight.sh` to re-detect |

### 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:
   ```bash theme={null}
   curl -X DELETE http://<SERVER>/api/core/devices/<DEVICE_ID> \
     -H "Authorization: Bearer <TOKEN>"
   ```

2. On the device, remove the old config:
   ```bash theme={null}
   docker rm -f acusight-agent
   rm -rf /etc/acusight
   ```

3. Create a new provisioning token and run the setup script again.

## Next Steps

<CardGroup cols={2}>
  <Card title="Data Collection" icon="database" href="/tutorials/data-collection">
    Learn how devices send data to Acusight
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore the full provisioning API
  </Card>
</CardGroup>