Instrument Uploader Setup Guide

How it works

Most instrument software can already export results to a folder as CSV, TSV, TXT, or Excel files. The uploader watches those folders. When a new file appears and has finished writing, it uploads the file to Aliquora's instrument-ingest API using an upload-only pairing key — a credential that can send files but can never read lab data. Aliquora matches the file against your import templates:

• Files that import are moved to a sent subfolder; matched results land in Aliquora as unverified, awaiting your normal review workflow.
• Files the server can't import are moved to a failed subfolder and appear in Instrument Import → Review Queue in the app, where an admin can retry or dismiss them.
• If anything goes wrong with the connection or the key, files stay exactly where they are and the uploader retries — it never deletes or loses a file.

Every file is deduplicated by content on both ends, so restarts, retries, and re-copies never create duplicate results.

Step 1 — Create a pairing key

In Aliquora, go to Settings → Instrument Uploads and click New pairing key. Name it after the PC or instrument (e.g. "HPLC-2 bench PC") and create one key per PC — that way the status table shows each machine's health separately, and you can revoke one PC without touching the others.

Step 2 — Prepare the instrument PC

1. Install Node.js LTS (18 or newer) from nodejs.org if it isn't already installed. Accept the defaults; no extra components are needed.
2. Download aliquora-uploader.mjs from Settings → Instrument Uploads and copy it to the instrument PC — a USB stick or network share is fine. Put it somewhere stable, e.g. C:\Aliquora\aliquora-uploader.mjs.
3. Identify the folder(s) your instrument software exports results into, e.g. C:\HPLC\exports.

Step 3 — Run it

Open a terminal (Command Prompt on Windows) and run:

node C:\Aliquora\aliquora-uploader.mjs --server https://aliquora.com --key lk_YOUR_PAIRING_KEY --folder "C:\HPLC\exports"

On startup the uploader verifies the pairing key against the server and prints which folders it is watching. Drop a test export into the folder and watch it move to sent (imported) or failed (needs an import template — see troubleshooting). Repeat --folder to watch more than one folder with a single uploader.

To do a single test pass and exit instead of running continuously, add --once.

Command reference

Flag	Environment variable	Meaning
--server <url>	ALIQUORA_SERVER	Your Aliquora address, e.g. https://aliquora.com. Required.
--key <pairing key>	ALIQUORA_KEY	The upload-only pairing key created in Settings → Instrument Uploads. Required.
--folder <path>	ALIQUORA_FOLDERS	Folder to watch. Repeat --folder to watch several (env: separate paths with a semicolon). Required.
--interval <seconds>	ALIQUORA_INTERVAL	How often to scan for new files. Default 5 seconds.
--once	—	Scan each folder twice, upload what's ready, then exit. Useful for testing.

Only .csv, .tsv, .txt, and .xlsx files are uploaded (up to 5 MB each); everything else in the folder is ignored. Files still being written by the instrument are left alone until their size stops changing.

Step 4 — Make it start automatically

Windows (Task Scheduler)

1. Open Task Scheduler → Create Task…
2. General tab: name it "Aliquora Uploader" and tick Run whether user is logged on or not.
3. Triggers tab: New… → Begin the task At startup.
4. Actions tab: New… → Action Start a program:
   • Program/script: node
   • Add arguments: C:\Aliquora\aliquora-uploader.mjs --server https://aliquora.com --key lk_YOUR_PAIRING_KEY --folder "C:\HPLC\exports"
5. Settings tab: tick If the task fails, restart every 1 minute.
6. Click OK, enter the Windows account password, then right-click the task → Run to start it now. Confirm the key shows Online in Settings → Instrument Uploads after the next upload.

macOS / Linux

Any service manager works — the uploader is just a long-running node process. On Linux, a minimal systemd unit:

[Unit]
Description=Aliquora Instrument Uploader
After=network-online.target

[Service]
ExecStart=/usr/bin/node /opt/aliquora/aliquora-uploader.mjs
Environment=ALIQUORA_SERVER=https://aliquora.com
Environment=ALIQUORA_KEY=lk_YOUR_PAIRING_KEY
Environment=ALIQUORA_FOLDERS=/data/hplc/exports
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

On macOS, use a launchd LaunchDaemon with the same command, or simply add it to Login Items for a bench Mac.

What happens to each file

Outcome	Where the file goes	What it means
Imported	Moved to the sent subfolder	Results were matched to samples and saved — always as unverified, awaiting your normal review/validation workflow.
Duplicate	Moved to the sent subfolder	The identical file (by content) was already uploaded earlier. Nothing is imported twice.
Quarantined	Moved to the failed subfolder	The server received the file but couldn't import it (no matching template, unknown samples, bad rows). It appears in Instrument Import → Review Queue in the app for retry or dismissal.
Rejected	Moved to the failed subfolder	The server refused the upload — the file was empty or too large (over 5 MB). Files with unsupported extensions are never uploaded at all; they simply stay in the folder and are ignored.
Key problem (401/403)	File stays in place	The pairing key was revoked or the plan doesn't include API access. The uploader keeps the file, backs off, and retries — fix the key and it resumes.
Server/network problem	File stays in place	Timeouts, rate limits, and server errors never move files. The uploader retries with increasing delays until the upload succeeds.

Monitoring

Settings → Instrument Uploads shows each pairing key with a live status badge — Online (seen in the last 5 minutes), Seen today, or last-seen date — plus upload counts, how many files are waiting in the Review Queue, and the time of the last upload. Quarantined files are worked from Instrument Import → Review Queue inside the app.

Troubleshooting

Symptom	Fix
"Pairing key rejected (HTTP 401)" at startup	The key was mistyped or revoked. Copy the exact key from Settings → Instrument Uploads (create a new one if the original is gone — keys are only shown once).
Files sit in the watch folder and never upload	Check the file extension — only .csv, .tsv, .txt, and .xlsx are uploaded. Also confirm the instrument has finished writing: the uploader deliberately waits until a file's size stops changing between scans.
Everything lands in the failed folder	The server has no import template matching your file's columns. In the app, open Instrument Import and create a template for this instrument's export format, then retry the files from Review Queue.
The same file keeps re-uploading after you delete the state file	The uploader remembers what it sent in a hidden .aliquora-uploader-state.json file in each watch folder. Don't delete it — but even if you do, the server also dedupes by content, so nothing imports twice.
Status shows "Never connected"	The uploader hasn't reached the server with that key yet. Check the command uses the right --server address and that the PC can reach it (try opening the address in a browser on that PC).
"Online" badge doesn't turn green	The badge turns green when the key authenticated within the last 5 minutes. With the default 5-second interval and files flowing, it should be green; an idle uploader still pings on each scan cycle only when it uploads — leave a test file to confirm.

Security notes

• Upload-only keys. A pairing key can upload instrument files and identify itself — nothing else. It cannot read samples, results, or any other lab data, so a compromised instrument PC cannot exfiltrate data through it.
• Revocation is instant. Revoking a key in Settings → Instrument Uploads blocks it immediately. Files on the PC stay in place; pair again with a new key to resume.
• Results are never auto-trusted. Imported results always land unverified and pass through your normal review, validation, and QC release gates. Files the server can't confidently import are quarantined for human review — never silently imported.
• The uploader never deletes data. Files are only ever moved into sent or failed subfolders next to the originals, and only after the server has definitively responded.

Related documents

• API guide & reference — the underlying instrument-ingest endpoint, for labs that prefer to script uploads themselves.
• Regulated-lab onboarding checklist — where instrument connectivity fits in a controlled rollout.