Skip to main content
If you already manage hosts with Ansible, use the official mirurobotics.agent collection instead of minting provisioning tokens yourself. One play installs the agent and registers each host.

​
What it does

The collection installs the Miru Agent debian package and provisions the target host in Miru. It is the provisioning-token flow packaged as a role: the API key stays on the Ansible controller, and only a short-lived token reaches each device. Provision role control flow: install or upgrade, skip if already provisioned, create a token, create the device in Miru if needed, then activate Provision role control flow: install or upgrade, skip if already provisioned, create a token, create the device in Miru if needed, then activate The miru_device_name is used to match the device in Miru. If a device with that name doesn’t exist, it is created and activated in Miru. If that device has been created in Miru but not yet activated (has state inactive), then the device is activated.

​
Requirements

  • ansible-core 2.15 or later on the controller
  • A target host on a supported platform
  • Miru Agent v0.10.2 or later
  • An API key with the devices:provision and provisioning_tokens:write scopes

​
Install the collection

Install the collection from Ansible Galaxy on the Ansible controller:
Or pin a version in requirements.yml:
requirements.yml
You can also install from git or a GitHub Release tarball.

​
Use the role

​
Write the playbook

Write the playbook to apply the provision role to the hosts in your inventory.
Be sure to set the hosts variable to your inventory group. We recommend passing miru_api_key at run time, which is why it isn’t included in the snippet above.
miru_agent_version is required and must be 0.10.2 or later.

​
Role variables

​
string
required
Platform API key used to mint provisioning tokens. This secret remains on the Ansible controller; it is never transferred to the target host.
​
string
required
Miru Agent version to install. The version must be 0.10.2 or later.Use latest to install the newest available package on every run.Example: 0.10.2
​
string
Device name shown in the dashboard. Defaults to the hostname of the target host.Default: inventory_hostname
​
string
Debian package architecture. The role automatically detects amd64 or arm64.Default: auto-detected

​
Run the playbook

Run the playbook and pass the API key in at runtime:
Ansible Vault or a CI secret store also work for storing the API key. Never commit a plaintext key.

​
Verify

To verify the Miru Agent was successfully installed and provisioned in Miru, navigate to the Devices page. You should see the device listed with the status Activating before transitioning to Online.
The transition from Activating to Online may take up to 10 seconds, depending on your network connection.
Last modified on September 23, 2026