Domotz Devices · diff
git:20260804.055e86e to git:20260806.ad583a2
85 added, 49 removed. Audit A to A.
---
name: "Domotz Devices"
description: >
Domotz device inventory: how agents discover and classify devices, the
identification attributes (IP, MAC, hostname, display name, vendor), the
- ONLINE/OFFLINE/UNKNOWN status model, and the list/get/search tools plus
- inventory and topology workflows built on them.
+ ONLINE/OFFLINE/UNKNOWN status model, the five device tools — list, get,
+ uptime, history, inventory metadata — and why device lookup is a
+ client-side match rather than a server-side search.
when_to_use: >-
When looking up, listing, or auditing devices discovered by a Domotz agent.
Use when: domotz device, device inventory, device discovery,
- device status, device search, device lookup, network device, device list, find device, or device
- details.
+ device status, device search, device lookup, network device, device list, find device, device
+ uptime, device history, or device details.
---
# Domotz Devices
## Overview
Domotz automatically discovers and monitors devices on networks where agents are deployed. Devices include servers, workstations, network equipment, IoT devices, printers, and any IP-connected hardware. Each device is associated with a specific agent (site).
## Anti-triggers
- **A managed endpoint with software installed on it** — a Domotz
device is anything that answered a LAN scan, including unmanaged
phones, printers, and IoT gear. Managed-endpoint inventory is
`atera` or `ncentral`.
- **Infrastructure across every client at once** — Domotz queries are
scoped to a single agent, so fleet-wide network inventory means
fanning out site by site; `auvik-devices` answers it directly.
- **Meraki hardware you intend to act on** — reading it here is fine,
but reboot, removal, and config key off the Dashboard serial; use
`meraki-devices`.
- **Attack-surface or rogue-asset discovery** — use `runzero`.
## Key Concepts
### Device Discovery
Domotz agents continuously scan local networks and automatically discover new devices. Discovered devices are classified by type and can be:
- **Monitored** - Actively tracked with status checks
- **Unmonitored** - Discovered but not actively tracked
### Device Identification
Devices are identified by multiple attributes:
- **IP Address** - Current network address
- **MAC Address** - Hardware identifier (persistent)
- **Hostname** - DNS or NetBIOS name
- **Display Name** - User-assigned friendly name
- **Vendor** - Manufacturer identified from MAC OUI
### Device Status
| Status | Meaning |
|--------|---------|
| `ONLINE` | Device is reachable on the network |
| `OFFLINE` | Device is not responding |
| `UNKNOWN` | Status cannot be determined |
- ## API Patterns
+ ## Tools
+ | Tool | Description | Arguments |
+ |------|-------------|-----------|
+ | `domotz_devices_list` | Every device on the agent's network, with status, IPs, MAC, and type | `agent_id` |
+ | `domotz_devices_get` | Full detail for one device — vendor, model, OS, services | `agent_id`, `device_id` |
+ | `domotz_devices_uptime` | Uptime history and current uptime | `agent_id`, `device_id` |
+ | `domotz_devices_history` | Online/offline event history | `agent_id`, `device_id` |
+ | `domotz_devices_inventory` | Inventory metadata — owner, location, notes, custom fields | `agent_id`, `device_id` |
+
+ All IDs are numbers. **There is no device search tool and no pagination
+ arguments** — `domotz_devices_list` returns the full census for the agent
+ in one response, and matching by name, IP, or MAC is done client-side over
+ that array.
+
+ `domotz_devices_inventory` is the operator-maintained metadata layer
+ (owner, location, notes), not the discovery data. It is where the human
+ context lives, and it is empty unless somebody filled it in.
+
### List Devices
```
- domotz_list_devices
+ domotz_devices_list
```
Parameters:
- `agent_id` -- The agent monitoring this network (required)
- - `page` -- Page number for pagination
- - `page_size` -- Results per page
**Example response:**
```json
[
{
"id": 789,
"display_name": "Core Switch",
"ip_addresses": ["192.168.1.1"],
"hw_address": "AA:BB:CC:DD:EE:FF",
"vendor": "Cisco Systems",
"type": {
"detected_id": 3,
"label": "Network Device"
},
"status": "ONLINE",
"last_status_change": "2026-03-27T10:00:00Z",
"first_seen": "2025-06-15T08:30:00Z"
}
]
```
### Get Device Details
```
- domotz_get_device
- ```
-
- Parameters:
- - `agent_id` -- The agent ID
- - `device_id` -- The specific device ID
-
- ### Search Devices
-
- ```
- domotz_search_devices
+ domotz_devices_get
```
Parameters:
- - `agent_id` -- The agent ID
- - `query` -- Search term (name, IP, or MAC)
+ - `agent_id` -- The agent ID (required)
+ - `device_id` -- The specific device ID (required)
## Common Workflows
- ### Device Lookup by IP
+ ### Device Lookup by IP or MAC
- 1. Call `domotz_search_devices` with the IP address as `query`
- 2. Review matching devices for the correct match
- 3. Call `domotz_get_device` for full details if needed
+ There is no server-side search, so a lookup is a list-and-filter:
- ### Device Lookup by MAC
+ 1. Determine scope. One site means one `agent_id`; "anywhere in the
+ estate" means `domotz_agents_list` then a call per agent.
+ 2. Call `domotz_devices_list` for each agent in scope.
+ 3. Match client-side on `ip_addresses`, `hw_address`, `display_name`, or
+ hostname. Prefer MAC when devices move on DHCP.
+ 4. Call `domotz_devices_get` on the match for full detail.
- 1. Call `domotz_search_devices` with the MAC address as `query`
- 2. MAC lookups are useful when devices change IPs (DHCP)
+ Say that the match was done locally when you report it — a device absent
+ from the list is absent from the agent's last scan, which is not the same
+ as "not on the network".
### Full Site Inventory
- 1. Call `domotz_list_devices` with the `agent_id` for the site
- 2. Paginate through all results
- 3. Group devices by type (servers, workstations, network devices, etc.)
- 4. Note online vs offline status for each
+ 1. Call `domotz_devices_list` with the `agent_id` for the site
+ 2. Group devices by type (servers, workstations, network devices, etc.)
+ 3. Note online vs offline status for each
+ 4. Pull `domotz_devices_inventory` for the devices that matter to pick up
+ owner, location, and notes
### Device Change Detection
1. List all devices for an agent
- 2. Compare against a previous inventory snapshot
+ 2. Compare against a previous inventory snapshot, or sort by `first_seen`
3. Identify new devices (potential rogue devices)
4. Identify missing devices (potentially decommissioned)
+ New devices appear only as the agent's own scan cycle finds them. There is
+ no tool to force a rescan, so a device connected moments ago may not be
+ listed yet.
+
+ ### Outage Investigation for One Device
+
+ 1. Call `domotz_devices_get` for current status
+ 2. Call `domotz_devices_history` for the online/offline event sequence —
+ this is what distinguishes a flapping device from a clean outage
+ 3. Call `domotz_devices_uptime` for how long it has been up since the
+ last transition
+ 4. Check `domotz_agents_get` before trusting any of it; a dead collector
+ reports last-known state as if it were current
+
### Network Topology Mapping
- 1. List all devices for an agent
- 2. Group by subnet based on IP addresses
- 3. Identify network devices (switches, routers, APs)
- 4. Map device-to-switch port relationships where available
+ For the actual connectivity graph, use `domotz_network_topology` — see the
+ `network` skill. `domotz_devices_list` grouped by subnet is a weaker
+ substitute and should not be presented as topology.
## Error Handling
### Device Not Found
- **Cause:** Invalid device ID, device has been removed, or wrong agent
- **Solution:** Verify the device ID and agent ID; search by IP or MAC instead
+ **Cause:** Invalid device ID, device has been removed, or the ID belongs
+ to a different agent
+ **Solution:** Verify the `agent_id`/`device_id` pair against
+ `domotz_devices_list`. Device IDs are not globally unique across agents.
### Empty Device List
- **Cause:** Agent has not completed initial scan, or no devices on network
- **Solution:** Verify agent is online; trigger a network scan; wait for discovery
+ **Cause:** Agent has not completed its initial scan, agent is offline, or
+ no devices on the network
+ **Solution:** Check `domotz_agents_get` status. There is no scan trigger —
+ if discovery has not run yet, the only option is to wait for the agent's
+ own cycle.
### Stale Device Data
- **Cause:** Agent is offline or device status hasn't been refreshed
- **Solution:** Check agent status; trigger a fresh scan if possible
+ **Cause:** Agent is offline, so records persist and read as last-known
+ rather than current
+ **Solution:** Check the agent's status and `last_seen` first. A report of
+ "all devices online" from a site whose collector died is worse than no
+ report.
## Best Practices
- Use MAC address for persistent device identification (IPs change with DHCP)
- - Paginate through all results for accurate device counts
+ - Expect one large response per site rather than paged results; scope by
+ `agent_id` and filter locally
- Monitor `last_status_change` to detect recent outages
+ - Use `domotz_devices_history` rather than a single status read when the
+ question is "has this been stable"
- Use `vendor` field to categorize devices by manufacturer
- Cross-reference device inventory with IT documentation (IT Glue configurations)
- Track `first_seen` dates to detect new/rogue devices on the network
- - Use display names consistently with your documentation platform
+ - Treat the full list as premises data about people — at a small business
+ it includes staff phones and personal laptops, not just managed assets
## Related Skills
- - [api-patterns](../api-patterns/SKILL.md) - Pagination and rate limiting
+ - [api-patterns](../api-patterns/SKILL.md) - Authentication, tool catalog, error codes
- [agents](../agents/SKILL.md) - Agents that monitor devices
- - [alerts](../alerts/SKILL.md) - Alerts triggered by device events
- - [network](../network/SKILL.md) - Network scanning and port monitoring
- - [eyes](../eyes/SKILL.md) - Sensors monitoring specific devices
+ - [alerts](../alerts/SKILL.md) - Alert profile coverage for devices
+ - [network](../network/SKILL.md) - Topology, IP conflicts, and SNMP metrics
+ - [power](../power/SKILL.md) - PDU outlet control