--- title: Device description: "A machine running the CLIKA agent: how it registers, what it reports, the states it moves through, and what blocks it from taking work." --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; A device is a machine that runs the CLIKA agent and has registered itself with the platform. A Jetson on a bench, an x86 workstation, a Windows laptop, a single-board computer, an Android phone: same agent, same fleet, same benchmark surface. ## Why it exists Numbers measured on a development machine do not tell you what a model does on the hardware you ship. The device object is how the platform reaches real hardware, so a benchmark result carries the device it was measured on and two results can be compared honestly. ## How a device joins You install the agent with one command from the **Register Device** dialog. That command carries a short activation code, so the device proves it may join without anyone typing credentials on it. The agent then dials out to the platform and holds one gRPC connection open for everything that follows: commands, file transfer, terminal, job dispatch. Nothing connects inward to the device, so no inbound port has to be opened. By default the code enrolls one device and expires 30 minutes after the dialog made it. **Reusable, many devices** switches to a batch command that any number of devices can register with for ten minutes, which is how a rack or a shelf of phones joins in one pass. The CLI and the API mint enrollment tokens as well, the other credential a device can enroll with. At registration the agent reports what the machine is: platform (`linux`, `darwin`, `windows`, `android`) and architecture (`amd64`, `arm64`, `arm`), agent version, network interfaces, and a hardware inventory (CPU cores, memory, GPU model and VRAM, disk, and detected accelerators such as `cuda`, `tensorrt`, `coreml` or `nnapi`). The platform assigns a device id on first registration and confirms the same id on every later connection. ## What it reports Every 15 seconds the agent sends a heartbeat: CPU, memory, disk, temperature, uptime, battery where there is one, network type, and the state of the processes and services the platform asked it to watch. The platform stores the heartbeat as health history, updates the live view, evaluates alert rules against it, and pushes it to anyone watching the device page. A device with no heartbeat for 60 seconds is marked offline. Services already running on it keep running: going offline is a statement about the connection, not about the machine. ## States | State | Meaning | | --- | --- | | `ONLINE` | Connected, heartbeats arriving, available for work. | | `BUSY` | Running a benchmark job. | | `SUSPENDED` | Taken out of service by an operator. | | `ERROR` | The agent reported an error state. | | `OFFLINE` | No heartbeat for 60 seconds. | ### The dirty flag Every benchmark job ends with teardown steps, and those steps always run, including after a failure. If teardown itself fails, the platform flags the device **dirty** and records which job did it and why. A dirty device takes no new benchmark jobs, because leftover state from a failed run is how one bad job turns into a series of misleading results. Dirty clears in one of two ways: the agent retries the teardown when it reconnects and reports success, or an operator who has cleaned the machine clears it from the device page. ## Resources and capabilities Two different things get reported, and jobs use them differently. - **Resources** are typed hardware facts (`cpu_cores`, `memory_bytes`, `gpu_vram_bytes`, `accelerators`). A job definition can declare `required_resources`, and the platform refuses to dispatch to a device that does not meet them, naming the requirement it failed. - **Capabilities** are platform metadata (terminal mode, SSH status, feature strings). They describe what the agent can do on this machine rather than how much hardware it has. You can also declare your own resources in the agent's configuration (a rack label, an engine name), and they merge with what auto-detection found. ## What you can do with one A registered device is not only a benchmark target. Everything below runs through the platform over the agent's own connection, so none of it needs an inbound route to the machine. - **Run benchmarks.** The device takes benchmark jobs, one at a time, and reports each state transition as it goes. Its **Jobs** tab is the history of everything the platform has run on it, with the outcome of each. - **Run managed services.** A [service](service.mdx) is a process the platform keeps running on the device and restarts when it exits. The **Services** tab lists what the device runs, with state, uptime and restart count, and a live log view per service. - **Serve a model.** A [model deployment](model-deployment.mdx) is the built-in service: one of your registered models, running on the device behind an endpoint the platform proxies for you. - **Browse and transfer files.** The **Files** tab is a file manager for the device. Navigate its filesystem, upload from your machine or from the artifact library, download a file, and save what you downloaded back into the library as a new artifact. Uploads are chunked and resumable, so a multi-gigabyte push survives a dropped connection. - **Run a command.** The **Commands** tab runs a one-off command and records it with its exit code, its output and when it ran. A recorded command stays readable afterwards, which makes it usable as evidence and not only as a convenience. - **Open a terminal.** An interactive shell in the browser over the same connection. On Linux, macOS and rooted Android it is a real PTY; on Windows and unrooted Android it is more limited. - **Open a remote desktop.** Where a provider exists for that platform, the device's screen is viewable in the browser. When no session can be served, the device reports a reason and the page names the remedy (install a VNC server, enable Screen Sharing, grant the Android consent prompt) instead of hiding the feature. - **Read its health.** CPU, memory, disk, temperature, uptime, battery and network arrive every 15 seconds, with history per metric and alert rules evaluated against them. - **Tag it.** Free-form key and value tags travel with the device and filter the fleet list, which is how a large fleet stays navigable (`rack=lab-a`, `owner=vision-team`). - **Update its agent.** The platform tracks the agent version per device and can trigger a self-update, one device or a batch at a time. - **Suspend or retire it.** A suspended device stays registered and takes no work. Deleting it removes it from the fleet. ## Where you see it
**Devices** in the sidebar lists the fleet. A device's own page carries the Overview, Jobs, Services, Files and Commands tabs, with Terminal and Remote Desktop in its header.
```bash clika-cli devices list clika-cli devices get "Linux x86 Workstation" clika-cli devices exec "Linux x86 Workstation" "nvidia-smi" clika-cli devices push "Linux x86 Workstation" ./model.gguf /tmp/model.gguf ``` Every command takes a device name or its id. See [Using the CLI](../cli/index.md).
Ask Claude: > Which of my devices are online, and how much GPU memory does each have? That reaches the `get_devices` and `get_devices_id` tools. `get_devices_id_health` returns the live health and `post_devices_id_exec` runs a command; the `device-ops` toolset exists for exactly this work.
## Related pages - [Job](job.mdx): what actually runs on a device. - [Service](service.mdx): what keeps running on it. - [Register or pick a device](../getting-started/first-benchmark/03-pick-a-device.md) in the tutorial.