Cambrionix connect
Developers
Cambrionix CLI

Enroll a computer

Add a computer to your organisation from its terminal, with or without a browser on it.

Enrolling a computer adds it to your Connect organisation, so its hubs and devices appear in Connect. The computer needs the Cambrionix Connect Suite installed and running.

Headless: one command with a code

Use this for servers, CI runners and anything else without a browser. Nobody signs in on the computer itself.

  1. In Connect, open Computers → Add a computer and choose Headless enrollment.
  2. Optionally give the computer a name. Without one, the CLI uses its host name.
  3. Choose Create enrollment command, pick the computer's operating system and copy the command.
  4. Run it on the computer. The page shows when the computer has joined.

The command installs the CLI from a signed link and enrolls the computer. It looks like this:

curl -LsSf '<signed install link>' | sh -s -- --enroll <code>
$env:CAMBRIONIX_ENROLL_CODE='<code>'; irm '<signed install link>' | iex

If the CLI is already installed, run cambrionix-cli enroll --code <code> --yes instead.

The code starts with cbxc_ and includes the address of the Connect that created it, so a code from staging enrolls into staging whichever Connect the CLI is configured for. --yes (or -y) answers the one question enroll can ask: whether to leave an organization the computer already belongs to. The install command passes it for you.

Enroll many computers

To enroll a fleet from provisioning scripts, cloud-init or Ansible, use an enrollment token instead of a code. One token works on any number of computers until it expires or you revoke it.

  1. In Connect, open Computers → Add a computer → Headless enrollment and choose Many computers.
  2. Choose how long the token lasts (7, 14 or 30 days) and choose Create enrollment token.
  3. Copy the token, and the install link for each operating system you use. Connect shows the token once. The install links work for as long as the token does.

Each computer needs the Cambrionix Connect Suite installed and running before it enrolls.

From a shell

Pass the token in the CAMBRIONIX_ENROLL_TOKEN environment variable. The installer hands it to the CLI through the environment, so it never appears in the process list.

export CAMBRIONIX_ENROLL_TOKEN='<token>'
curl -LsSf '<install link>' | sh -s -- --name build-07
$env:CAMBRIONIX_ENROLL_TOKEN='<token>'; irm '<install link>' | iex

On a computer that already has the CLI:

CAMBRIONIX_ENROLL_TOKEN='<token>' cambrionix-cli enroll --name build-07

With Ansible

Encrypt the token with Ansible Vault and keep it with the install link in your group variables:

ansible-vault encrypt_string '<token>' --name cambrionix_enroll_token >> group_vars/cambrionix_hosts.yml
echo "cambrionix_install_url: '<install link>'" >> group_vars/cambrionix_hosts.yml

This play installs the CLI where it's missing, then enrolls each host under its inventory name. Running it again changes nothing on hosts that have already joined.

- name: Enroll hosts into Cambrionix Connect
  hosts: cambrionix_hosts
  become: true
  vars:
    cambrionix_cli: /usr/local/bin/cambrionix-cli
  tasks:
    - name: Install the Cambrionix CLI
      ansible.builtin.shell: curl -LsSf '{{ cambrionix_install_url }}' | sh
      environment:
        CAMBRIONIX_CLI_UNMANAGED_INSTALL: /usr/local/bin
      args:
        creates: "{{ cambrionix_cli }}"


    - name: Enroll into Connect
      ansible.builtin.command:
        argv: ["{{ cambrionix_cli }}", "enroll", "--name", "{{ inventory_hostname }}", "--json"]
      environment:
        CAMBRIONIX_ENROLL_TOKEN: "{{ cambrionix_enroll_token }}"
      register: cambrionix_enroll
      changed_when: (cambrionix_enroll.stdout | from_json).changed

For Windows hosts, use ansible.windows.win_shell with irm '<install link>' | iex to install the CLI. Then run cambrionix-cli enroll --json with the same environment.

With cloud-init

#cloud-config
runcmd:
  # Install the Cambrionix Connect Suite first, then:
  - curl -LsSf '<install link>' | CAMBRIONIX_ENROLL_TOKEN='<token>' sh

Re-running, moving and revoking

  • Already joined: a computer already in the token's organisation is left as it is. enroll --json prints "changed": false.
  • In another organisation: enrolling fails, so a play never moves a computer by accident. Add --replace --yes to move it.
  • Revoking: revoke a token under Active enrollment tokens on the same page. Computers that already joined stay enrolled. To remove one, run cambrionix-cli unenroll on it or delete it in Connect.

With a browser

Run cambrionix-cli enroll (or cambrionix-cli tui for the interactive screen). The CLI prints a link and a QR code and opens your browser. Approve the computer there, or scan the QR code and approve it on your phone. Add --no-browser on a computer without a desktop.

Moving a computer to another organisation

A computer belongs to one organisation at a time. If it's already enrolled, enroll asks before leaving the current organisation; pass --replace to leave without asking. The CLI only leaves the old organisation once it has the new invite, so a mistyped or expired code never leaves the computer without an organisation.

cambrionix-cli enroll --code <code> --replace --yes
cambrionix-cli unenroll                  # leave without joining another organisation

Scripting

enroll --json prints the result for provisioning tools:

{
  "changed": true,
  "organizationId": "7c9e6679-7425-40de-944b-e07fc1f99a3d",
  "computerId": "35aea4bc-44d3-4e9e-9b3c-c33b965c5639",
  "serviceId": "36d5a398-e3ef-55f9-8b09-ba6351511464",
  "name": "build-07"
}

changed is false when a token's computer had already joined. The code can also come from the CAMBRIONIX_ENROLL_CODE environment variable, and a token from CAMBRIONIX_ENROLL_TOKEN. Both keep the secret out of shell history and process lists.

Troubleshooting

MessageWhat to do
Relay API is not reachableInstall or start the Connect Suite, then run cambrionix-cli services list.
No invite for this codeThe code was used, expired or came from another Connect. Create a new command in Connect.
this computer is already enrolledAdd --replace to move it to the new organisation.
that isn't an enrollment tokenCopy the whole token, starting cbxe_, from Many computers.
joining the organization failed with a tokenThe token expired or was revoked. Create a new one.
install.sh: error: unknown optionThe install script predates CLI 0.2.1. Copy a new command or token from Connect.
Anything elseRun cambrionix-cli doctor, then cambrionix-cli support bundle --preset enrollment for support.