Install the local agent

This guide installs the agent from the GitHub repository. It uses the current booter.py workflow. No installer or automatic Store-to-device installation is available yet.

1. Check your prerequisites

Install Git, Python 3.10 or newer for the host boot script, Docker with Compose, and FFmpeg on your PATH. Start Docker before booting the agent. A working webcam is required for the recording test.

The camera service can use a bundled FFmpeg binary for recording, but camera discovery on Windows and macOS currently invokes the system ffmpeg command. Install FFmpeg explicitly for this workflow.

Check the tools in a terminal. On Windows, use python if python3 is not available.

git --version
python3 --version
docker info
docker compose version
ffmpeg -version

For BPM, also verify that nvidia-smi works and Docker can access your GPU. A working desktop GPU alone is not enough; the analyzer's Compose file requests the NVIDIA runtime. The BPM container has its own legacy Python/CUDA dependencies, separate from the host environment.

2. Clone the repository

The repository is currently private. You need a GitHub account with access before cloning it. If GitHub shows 404 or Git reports Repository not found, verify that you are signed in with an authorized account or request access from Diego.

git clone https://github.com/diegoturri/healthcam.git
cd healthcam/healthcam-agent

Run the following agent commands from healthcam-agent, not the repository root. The boot system uses the current directory to locate configuration and services.

If you downloaded a ZIP from GitHub instead, extract it and open a terminal in its healthcam-agent directory.

3. Create a Python environment

On macOS or Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install python-dotenv

On Windows PowerShell, use the environment's executable directly; activation is optional:

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install python-dotenv

The booter creates separate environments for native services and builds images for container services when they are missing. The root-level install.py and legacy tray launchers are not required by this guide.

4. Connect a personal workspace

Open HealthCam Login, sign in with Google, and generate an API key in Settings. The shared demo cannot generate a personal key or receive your test data.

Create a file named .env directly inside healthcam-agent:

CLOUD_API_KEY="paste-your-personal-key-here"
NEXTJS_API_URL="https://healthcam.diegoturri.com/api/recordings/payloads"

Keep the key private and leave .env out of Git. Do not copy it into issues or screenshots.

If you are developing the web app locally, complete the cloud setup first and set the endpoint to:

NEXTJS_API_URL="http://host.docker.internal:3000/api/recordings/payloads"

The orchestrator runs in Docker. localhost inside that container is not your host web server. The orchestrator's Compose file supplies a host-gateway mapping.

The existing cloud.enabled field in config.json is not used by the current dispatcher. Setting it to false does not disable uploads. Set the intended endpoint and key before you start recording.

5. Choose which services to run

Edit config.services.json. For a first blink test, this is a minimal configuration:

{
  "base": {
    "orchestrator": true,
    "camera-capture": true
  },
  "analyzers": {
    "app-tracker": true,
    "diego-turri-bpm-estimator-pyvhr-v-0-0-1": false,
    "blink-counter": false,
    "blink-dt-0-0-1": true
  },
  "utility": {
    "notification-service": false
  }
}

blink-counter is a legacy entry without a service directory; leave it disabled. Notifications are not needed to verify capture, inference, and cloud upload.

For a BPM test on a compatible NVIDIA machine, set diego-turri-bpm-estimator-pyvhr-v-0-0-1 to true. You can disable the blink analyzer for the first BPM run to isolate failures. A blink-only run will not populate the BPM dashboard.

Restart the booter after changing service selection. Changing ownership in the web Store does not update this local file.

6. Review the capture settings

In config.json, the current capture settings are:

{
  "camera_capture": {
    "segment_time": 20,
    "res": "1920x1080",
    "fps": 30
  }
}

These are the fields to review, not a replacement for the whole file. Use a resolution and frame rate your camera supports. Close other applications using the webcam. On Linux, the picker currently defaults to /dev/video0; a different device requires adjusting the picker in services/camera-capture/utils/camera_picker.py.

7. Boot the services

On macOS/Linux, with the environment activated:

python booter.py

On Windows PowerShell:

.\.venv\Scripts\python.exe booter.py

Keep this terminal open. The first boot installs native dependencies and builds enabled containers, so it may take several minutes. The boot system creates the healthcam Docker network, writes runtime/service-registry.json, starts services, and monitors whether their processes remain running.

Booting does not start recording. It also does not execute the full HTTP healthcheck sequence declared in each manifest. Once startup completes, continue to Run your first test to verify readiness and explicitly start capture.