# 02 — LabBridge Agent Installation

The LabBridge Agent is the clinic-side service that talks to your analyzers
locally and relays everything to the cloud. It is a **single static binary**
— no XAMPP, no PHP, no other runtime required on the clinic PC.

Source lives at [labbridge-agent/](../../labbridge-agent/).

## When you need it

You need exactly **one agent per clinic site**. One agent handles every
analyzer at that site (multiple TCP devices + multiple COM ports).

If the clinic only does cloud-to-cloud integration (e.g. IDEXX VetConnect
PLUS via API), you don't need the agent for those — only for analyzers that
expose a local TCP or serial interface.

## Build

Requires **Go 1.22 or newer**. Install Go from
[go.dev/dl](https://go.dev/dl/) on the build machine — you don't need Go on
the clinic PC, only the resulting binary.

```bash
cd labbridge-agent
go mod tidy
go build -ldflags "-s -w" -o labbridge.exe ./cmd/labbridge      # Windows
go build -ldflags "-s -w" -o labbridge     ./cmd/labbridge      # Linux/macOS
```

The binary is fully static — `modernc.org/sqlite` is pure Go, no cgo. You
can build for any target with standard Go cross-compilation:

```bash
GOOS=windows GOARCH=amd64 go build -ldflags "-s -w" -o labbridge.exe ./cmd/labbridge
GOOS=linux   GOARCH=amd64 go build -ldflags "-s -w" -o labbridge     ./cmd/labbridge
GOOS=linux   GOARCH=arm64 go build -ldflags "-s -w" -o labbridge     ./cmd/labbridge   # Raspberry Pi etc.
```

Final binary size: ~15–20 MB.

## Configure

1. **Create a Bridge Agent in the cloud UI** (Lab → Agents → "Add Bridge
   Agent"). The flash message shows the API token — copy it now, it isn't
   displayed again. (You can re-issue with the key icon.)

2. **Copy the config template:**

   ```bash
   cp config.example.yaml config.yaml
   ```

3. **Edit `config.yaml`:**

   ```yaml
   cloud_url: "https://erp.example.com"            # your cloud ERP base URL
   agent_code: "main-clinic"                       # matches the agent's "code" in the UI
   api_token: "<paste-the-token-from-the-cloud>"
   data_dir:  "./data"                             # writable folder for SQLite + logs
   heartbeat_interval: 60                          # seconds
   retry_interval:     30                          # sync sweep cadence (seconds)
   ```

That's all the local config the agent needs. **Device-specific settings
(TCP ports, COM ports, baud rates, vendor) are pulled from the cloud** at
startup — the agent calls `/api/lab/agent/register` and gets the device
list that's configured in the **Lab → Devices** screen.

To reconfigure devices: edit them in the cloud UI, then restart the agent
to pick up the new list.

## Deploy the binary

Drop `labbridge.exe` + `config.yaml` together on the clinic PC. Recommended
location:

| OS | Path |
|---|---|
| Windows | `C:\Program Files\LabBridge\labbridge.exe` |
| Linux | `/opt/labbridge/labbridge` |

The agent will create `data/queue.sqlite` next to itself unless `data_dir`
points elsewhere. Make sure the service account can write to `data_dir`.

## Install as a Windows Service

From an **elevated** command prompt:

```bat
cd C:\Program Files\LabBridge
labbridge.exe install
labbridge.exe start
labbridge.exe status
```

Other actions:

```bat
labbridge.exe stop
labbridge.exe restart
labbridge.exe uninstall
```

By default the service runs under `LocalSystem`. If your `data_dir` is in a
user folder, switch the service account in **Services.msc** → LabBridge
Agent → Properties → Log On.

### Verifying it started cleanly

```bat
sc query LabBridgeAgent
```

Look at the Windows Event Viewer → Application log. Look for entries from
source `LabBridgeAgent`. A clean startup logs:

```
LabBridge Agent 1.0.0 starting — cloud=... data=...
registered as agent #4 "Main Clinic" — 2 device(s)
listener: device 5 "VetScan VS2 - Bench 1" TCP on :9600 (abaxis)
listener: device 6 "VetScan HM5 - Bench 2" serial COM3 @ 9600 (abaxis)
```

## Install on Linux / systemd

```bash
cd /opt/labbridge
sudo ./labbridge install      # writes /etc/systemd/system/labbridgeagent.service
sudo ./labbridge start
sudo journalctl -u labbridgeagent -f
```

The `install` subcommand uses `kardianos/service` and works the same on
Linux (systemd), macOS (launchd) and Windows.

## Run interactively (for debugging)

`labbridge run` runs in the foreground, logging to stdout — useful when
diagnosing a setup before turning it into a service:

```bash
./labbridge run -config /opt/labbridge/config.yaml
```

Ctrl-C to stop.

## File layout once running

```
C:\Program Files\LabBridge\
  labbridge.exe
  config.yaml
  data\
    queue.sqlite            ← outbound queue + event log + worklist cache
    queue.sqlite-wal        ← SQLite write-ahead log
    queue.sqlite-shm
```

Backup `queue.sqlite` if you want to preserve unsent messages across a
machine move — but a healthy agent on a healthy network typically holds
nothing in the queue.

## Verify it's actually reaching the cloud

1. Go to **Lab → Agents** in the cloud UI.
2. Your agent's **Connectivity** column should show **Online** within
   `heartbeat_interval` seconds (default 60).
3. The **Last Heartbeat** column should update.

If it stays Offline, see [07 Troubleshooting § Agent isn't reaching the
cloud](07-troubleshooting.md#agent-isnt-reaching-the-cloud).

## Updating

To deploy a new agent build:

```bat
labbridge.exe stop
:: copy the new labbridge.exe over the old one
labbridge.exe start
```

The SQLite queue is forward-compatible across patch versions; major-version
upgrades will be documented in the release notes.

## Uninstall

```bat
labbridge.exe stop
labbridge.exe uninstall
:: optionally:
rmdir /S /Q "C:\Program Files\LabBridge"
```

On Linux:

```bash
sudo systemctl stop labbridgeagent
sudo ./labbridge uninstall
sudo rm -rf /opt/labbridge
```

The cloud `lab_agents` row is **not** removed — delete it from the UI
(Lab → Agents → trash icon) if you don't plan to re-install.

## Next

Once the agent is running and shows Online, [register a device and run a
real analyzer through it](03-device-integration.md).
