Skip to main content

2. Register Your First Device

After signing in to the platform next step is to register a device. Registering a device install the Loc.ai:Link agent on your target machine and connects it to your Control platform account. Once registered, the device will appear in your dashboard, receive model deployments, and report telemetry and inference results.

Steps to Register Your First Device​

Step 1: From the dashboard, click Register Device button to add a new device and connect it to the Loc.ai platform.

Register Step 1

Step 2: On the Devices page, click + Register Device button to start adding a new device to the platform.

Register Step 2

Step 3: A pop up will appear requiring you to enter a device details, such as device name, set the key validity period (TTL in hours), then click Generate Registration Key button to create the connection key for your device.

Register Step 3

Step 4: Copy the generated installation command for your operating system, then click the Close button to exit the registration window.

Run this command on your remote machine

The command you copied above must be pasted into the Terminal of the target device (the remote machine you are registering), not your local machine.

Registered Devices Step 4 — copy the generated installation command

Choose one of the two installation methods below. If you are unsure, use the One-line Installer.

One-line Installer

Recommended

The fastest way to deploy — no manual setup required

Paste this command into the terminal of your remote machine. It will automatically:

  • Install uv (Python package manager) if not already present
  • Configure the Python environment and install all dependencies
  • Register the device against the Loc.ai control plane
  • Start the agent
curl -sSL https://raw.githubusercontent.com/locai-co-uk/locai-link/main/install.sh \
  | bash -s -- \
    --device-name "my-edge-device-01" \
    --email "you@example.com" \
    --registration-key "YOUR_REG_KEY"
Replace the placeholder values

The command copied from the dashboard already contains your credentials. If you are typing it manually, replace --device-name, --email, and --registration-key with the values shown in your Loc.ai dashboard under Devices → Add Device.

Install from Source

Advanced

Manual installation for development, customisation, or pinned versions

Use this method if you need to modify the agent code, contribute to development, audit the install steps, or target a specific tagged release. Run all commands on your remote machine.

1. Get the Code​

Clone the repository and switch into its directory:

git clone https://github.com/locai-co-uk/locai-link.git && cd locai-link
Prefer a stable release?

Download the ZIP from the Latest release page, extract it, and cd into the extracted folder before continuing.

2. Set Up the Environment​

Run the install script for a guided, wizard-like setup. This installs uv, creates a virtual environment, and installs all Python dependencies:

chmod +x install.sh && ./install.sh

Alternatively, invoke the setup step directly via main.py:

# Standard setup
python3 main.py setup

# Recommended: use uv for faster, reproducible installs
uv run main.py setup

3. Register the Device​

Register the remote machine using the key generated from the Loc.ai dashboard:

uv run main.py register \
  --device-name "my-edge-device-01" \
  --email "you@example.com" \
  --registration-key "YOUR_REG_KEY"

You will be prompted for your account password. To skip the prompt, supply a pre-obtained JWT:

uv run main.py register \
  --device-name "my-edge-device-01" \
  --email "you@example.com" \
  --registration-key "YOUR_REG_KEY" \
  --token "<YOUR_JWT>"
Reactivating an existing device

Replace register with activate and provide --device-id and --api-key instead of --registration-key:

uv run main.py activate \
  --device-id "EXISTING_DEVICE_ID" \
  --api-key "YOUR_API_KEY"

Add --api-url "<url>" when targeting a non-production control plane.

4. Run the Agent​

Start the agent for the current terminal session:

uv run main.py run

To install it as a persistent background service (systemd on Linux, launchd on macOS, or a Windows Service), add --prod:

uv run main.py run --prod

On subsequent runs the agent resumes the saved session automatically and applies any over-the-air (OTA) updates via execv.

CLI Reference​

CommandPurpose
main.py setup [--dev] [--tui]Install Python dependencies. --dev adds mkdocs, pytest, and other dev tools. --tui adds the terminal UI package.
main.py install [options]Full install workflow in one step: clone → setup → register → run.
main.py register [options]Register a new device using a dashboard-generated key.
main.py activate [options]Reactivate an existing device using its device ID and API key.
main.py run [--prod]Start the agent. --prod installs it as a system service. Handles OTA updates via execv.
main.py stopStop all running services, including locai-link and zenohd.
main.py reset [--hard]Clean the environment, virtual environment, and caches. --hard also removes session files.
main.py install-plugin <name>Install a plugin by name.
main.py tuiLaunch the text-based UI (requires the --tui extra).

API Reference​

API docs are generated from source docstrings via mkdocs + mkdocstrings (included in --dev extras):

uv run mkdocs serve    # Live-reload dev server at http://127.0.0.1:8000
uv run mkdocs build    # Build static site into ./site/

Narrative pages live under docs/; docs/reference/ auto-populates from src/link/ docstrings.

Directory Structure​

src/link/    Application core — app/, components/, infra/, adapters/, config/, utils/
plugins/     Extensions: language_model, audio_transcriber, image_classifier, audio_classifier
configs/     Runtime configuration and session state
tests/       Unit tests (mocked, no external dependencies)
docs/        mkdocs source (see API Reference above)

Step 5: Wait for the installation and registration process to complete. When the message Pipeline 'command_center' started appears, the device is successfully connected and running.

Register Step 5
tip

The terminal of the remote device should not be closed; it should keep running in the background.

Step 6: Open the Devices page to verify that your registered device appears in the list with an Online status, confirming it is successfully connected.

Register Step 6

Now you can deploy first model.