ShellHub Ansible Collection (shellhub.core)

Manage your ShellHub-connected machines with Ansible.

ShellHub gives every device standard SSH access through a central gateway, so machines behind NAT are reachable with no public IP and no inbound ports. This collection provides a dynamic inventory plugin that lists the devices in a ShellHub namespace and connects to each one through the gateway — Ansible treats them like any other SSH host.

Install

ansible-galaxy collection install shellhub.core

Inventory plugin: shellhub.core.devices

Create an inventory source file whose name ends in shellhub.yml:

# inventory.shellhub.yml
plugin: shellhub.core.devices
api_url: https://cloud.shellhub.io   # your server, for self-hosted
ssh_user: root
ssh_key: ~/.ssh/id_ed25519           # private key registered in ShellHub
keyed_groups:
  - key: shellhub_tags               # each ShellHub tag becomes a group: tag_<name>
    prefix: tag

Provide a namespace API key (created in the ShellHub dashboard) and run:

export SHELLHUB_API_KEY=...
ansible-inventory -i inventory.shellhub.yml --graph
ansible -i inventory.shellhub.yml tag_production -m ping
ansible-playbook -i inventory.shellhub.yml site.yml

What it does

• Pages through the namespace's accepted devices via the ShellHub API.
• Connects through the gateway: ansible_host is the gateway, ansible_user is the device SSHID (<user>@<namespace>.<device>).
• Authenticates with an API key (X-API-Key); the namespace is resolved from the key, server-side.
• Exposes shellhub_tags, shellhub_online and shellhub_namespace as host facts, and supports keyed_groups, groups, compose and inventory caching.

Configuration

Every option can come from the source file or the environment:

Option	Env	Default
api_url	SHELLHUB_API_URL	https://cloud.shellhub.io
api_key	SHELLHUB_API_KEY	(required)
ssh_host	SHELLHUB_SSH_HOST	host of api_url
ssh_port	SHELLHUB_SSH_PORT	22
ssh_user	SHELLHUB_SSH_USER	root
ssh_key	SHELLHUB_SSH_KEY	(none)

Authenticate with SSH keys: upload your public key in the ShellHub dashboard under Public Keys, then point ssh_key at the matching private key.

License

Apache-2.0