Everything you need to get Kira running.
From your first monitored device to a full understanding of events and alerts.
Getting started
Getting Kira to monitor your first device takes a few minutes and doesn't require installing any server.
- 1 Create your account — a default group ("Default") is created for you automatically.
- 2 On the dashboard's Add device page, generate an enrollment token for the group.
- 3 Install the agent on the machine you want to monitor (see Install the agent below).
- 4 Within a few minutes, the device shows up on the dashboard with hardware, software, and status.
Install the agent
Native installers (.deb/
.rpm for Linux,
.msi for Windows,
.pkg for macOS) register the
agent as a background service automatically. Not code-signed yet — Windows will show a
SmartScreen warning ("More info → Run anyway") and macOS Gatekeeper blocks the .pkg by
default (right-click → Open works around it).
1. Generate an enrollment token
On the dashboard's Add device page, pick a group and click "Generate token". Tokens expire after 24 hours and are single-use.
2. Install the agent
Download the latest installer from the releases page for the target machine's OS and run it:
kira-agent-X.Y.Z-amd64.msi— Windowskira-agent_X.Y.Z_amd64.deb/kira-agent-X.Y.Z.x86_64.rpm— Linuxkira-agent-X.Y.Z-amd64.pkg/kira-agent-X.Y.Z-arm64.pkg— macOS (Intel / Apple Silicon)
The service gets registered but isn't started yet — there are no credentials until the next step.
3. Enroll the device
On the target machine (as Administrator on Windows, with sudo on Linux/macOS), run the command below with the token from step 1:
sudo kira-agent enroll --token=YOUR_TOKEN --api=https://api.staging.kiraware.comThis exchanges the token for a permanent credential, writes the config, and restarts the service automatically — no separate manual step needed. The agent reports immediately, then every 5 minutes.
Device status
Every device has a status that affects the severity of the events it generates. A newly enrolled device starts as Not allocated.
| Status | Meaning | Event severity |
|---|---|---|
| Active | In normal use by someone at the company | Full (critical/warning) |
| Not allocated | In storage, no assigned user (default on enrollment) | Downgraded to info |
| Maintenance | Being repaired or reconfigured | Downgraded to info |
| Decommissioned | Permanently out of use | Excluded from the offline check |
Events & alerts
Every agent report is compared against the last one. Every real change becomes a specific event — never a generic summary.
- Hardware change — CPU, memory, disk, or network changed since the last report.
- Software change — a package was installed, removed, or had its version changed.
- USB storage — a flash drive, external HDD, or other removable storage was connected or disconnected.
- Agent offline — the device hasn't reported in over 15 minutes.
- New device — generated once, when the device is enrolled.
Every event has a severity — critical, warning, or info — computed from the change type and the device's status (see the table above). Critical events on active devices trigger an immediate email to every user in the organization, batching every critical change from the same report into a single message. Connecting a USB storage device is treated as critical (it's a classic data-exfiltration vector); disconnecting one is just a warning.
Remote access
Open a full remote desktop or an SSH terminal right in the browser — no VPN, no firewall ports to open, no separate client to install. The session runs entirely inside the Kira dashboard.
Starting a session
On an online (and not decommissioned) device's detail page, use the buttons at the top:
- Remote Desktop — full remote desktop (mouse and keyboard). Available on Windows, Linux, and macOS.
- SSH Terminal — a command-line terminal. Linux and macOS only (Windows has no equivalent on-demand-enableable native SSH).
Each button opens a new browser tab with the session already connected.
How it works
The agent installed on the machine generates a one-time credential just for that session — it's never stored or logged anywhere. Ending the session (closing the tab, or clicking "Disconnect") makes the credential stop existing. Every session is capped at 4 hours.
Worth knowing before you use it
In this version, starting a session doesn't require any confirmation from whoever is currently at the machine — any user with permission to view the device can open a session directly. Every session start and end is recorded in the device's audit log (who, when, and for how long), which today is the only accountability mechanism — there's no on-screen prompt on the remote machine.
Agent environment variables
| Variable | Required | Description |
|---|---|---|
| KIRA_AGENT_ID | Yes | Returned by the enrollment endpoint |
| KIRA_AGENT_KEY | Yes | The agent's secret key — treat it like a password |
| KIRA_API_BASE_URL | Yes | Base URL of the Kira API |
The report interval (5 minutes by default) isn't configurable via environment variable yet — it's a fixed value in the agent.
Frequently asked questions
My device isn't showing up on the dashboard. What do I check?
Make sure the agent process is still running and that
KIRA_API_BASE_URL points at the
correct API. The agent logs connection errors to stdout.
My enrollment token expired. Now what?
Generate a new one from the "Add device" page — tokens expire after 24 hours and are single-use.
How do I stop monitoring a device?
Stop the agent process on the machine, and mark the device "Decommissioned" on the dashboard to exclude it from the offline check.
Do I need to ask whoever's at the machine before opening a remote session?
Not in this version — the session starts with no on-screen confirmation on the remote machine. Any user with permission to view the device can open one. The only trail is the device's audit log.
Is there an API I can call directly?
Yes — it's REST/JSON, and the same endpoints the agent and dashboard use are callable directly. Dedicated public API reference docs don't exist yet; for now, the commands on this page are the best guide.