Skip to main content

Set up your own HAL

You can run HAL on hardware you already own. The agent is a single binary that runs on most Linux machines — a Raspberry Pi, a mini PC, an old laptop, or a spare single-board computer.

Once it's running, your HAL shows up in EmbedHub like any other device: you can own it, give it access to specific projects, and assign it todos.

What you need​

  • A 64-bit Linux device with a spare USB port (x86_64 or aarch64)
  • Network access from that device
  • An EmbedHub account

Nothing else to install — the installer takes care of everything.

1. Request a provisioning bundle​

Every HAL has its own serial number and its own credentials, so we generate a bundle for each device.

Email anuj@embedhub.com to request one. You'll receive a zip file named after your device's serial number, for example HAL-541932-US3G50.zip.

Keep the bundle private

The bundle contains your device's private credentials. Anyone who has it can act as your HAL. Don't commit it to a repository or share it.

2. Install the agent​

Copy the zip to your device, then:

unzip HAL-541932-US3G50.zip
cd HAL-541932-US3G50
sudo ./install.sh

The installer downloads the agent for your architecture, installs your device's configuration, and starts HAL as a service so it comes back after a reboot.

Check that it's running:

systemctl status embedhub-hal

HAL runs in the background with no interface of its own. Everything it does — the work it picks up, the hardware it sees — goes to the system log:

journalctl -u embedhub-hal -f

Keep that open in a terminal while you finish the setup.

3. Claim the device​

Your HAL isn't linked to anyone until you claim it.

  1. Go to embedhub.com/tools/HAL.
  2. Click Add Device.
  3. Enter the serial number from your bundle (e.g. HAL-541932-US3G50) and give the device a friendly name.

The device is now yours. A serial number can only be claimed once — if someone else has already claimed it, you'll be told so.

4. Give it access to a project​

A HAL is a member of projects, in the same way a person is. Owning a device gives it nothing on its own — you have to invite it in.

  1. Open the project you want the device to work with.
  2. Go to the Members tab.
  3. Switch the member type to HAL and pick your device.
  4. Choose a role.

The role controls what the device may read and write, the same way roles work for people. Give it only what the job needs — for example, read access to releases/ so it can flash firmware, and write access to runs/ so it can report results.

note

You can only add a HAL to a project if you own that HAL and you're an admin or developer on the project.

5. Give the device its own key​

HAL reads your project files and reports progress through the EmbedHub CLI, so it needs a key. Give it a device key: a key that acts as the device itself rather than as you.

  1. Log in to embedhub.com and click your name in the top right → Settings.
  2. Open the API Keys tab.
  3. Click Create API Key, name it after the device (e.g. "hal-bench"), choose A HAL device, and pick your HAL.
  4. Copy the key — it's shown only once. Device keys start with ehd_.

Then, on the device:

sudo nano /etc/embedhub-hal/config.env

Fill in the line that's waiting for it:

EMBEDHUB_API_KEY=ehd_1234567890123456_abcdef1234567890abcdef1234567890abcdef12

Restart the agent so it picks up the key:

sudo systemctl restart embedhub-hal
Do this after step 4, not before

A device key can only reach the projects the device is a member of, and only the files its role allows. If you create the key before giving the device project access, it will reach nothing at all.

Why a device key

A device key is confined to that one HAL's projects — it does not inherit your access. If the device is lost or tampered with, whoever holds the key still cannot touch anything the device wasn't explicitly given. Unlinking the device revokes its keys immediately, and you can also revoke a key by hand from the API Keys tab.

6. Give it something to do​

You hand work to a HAL the same way you hand work to a person: with a todo.

Write the task itself as a markdown file in your project — say documents/flash-badge.md. Then create a todo that links to that file and assign it to the device. The todo's title and notes are just the summary; the linked document is the task.

embedhub push flash-badge.md acme/badge --path documents

embedhub todos add acme/badge \
  --title "Flash the badge" \
  --file documents/flash-badge.md \
  --hal HAL-541932-US3G50

You can do the same from the project's Todos tab. To hand an existing todo to a device, name the device where you would name a person:

embedhub todos assign acme/badge a1b2c3d4 HAL-541932-US3G50

Within a few seconds, the device picks it up. In journalctl you'll see it announce the assignment, print the task it pulled, and mark it in progress:

📋 Assigned: Flash the badge
   project: acme/badge
   todo:    a1b2c3d4   status: pending
   file:    documents/flash-badge.md
   ── task ──
   │ # Flash the badge
   │ 1. Attach the board to the top USB port
   │ 2. Run make flash
   ──────────
   ✔ acknowledged, marked in_progress

The todo now shows as in progress in the web UI — that's the device telling you it has the work.

Keeping the task in a file rather than in the todo means it can be as long as you need, it lives alongside the rest of the project, and the device can update the document as it works.

A device keeps its assignments even when it's offline, and picks up anything it missed the next time it reconnects.

Updating​

Re-run the installer to pull the latest agent. Your configuration and API key are left untouched:

sudo ./install.sh

Moving a HAL to another account​

Unlink the device from embedhub.com/tools/HAL.

You'll need to remove it from every project it's a member of first — this is deliberate, so a device never quietly keeps access to a project after changing hands. Once unlinked, the serial number is free to be claimed again, and the same bundle keeps working.