Install the connector

The connector is a small Docker service that listens for terminal connections on your network and forwards their messages to OnTime over HTTPS.

Prerequisites

A host on the same network as your terminals

Anything that runs Docker: a small server, a NUC, a VM. It does not need to be powerful — the connector holds no state and does almost no work.

Outbound HTTPS to OnTime

The host must reach https://app.ontime.hosai.app. Nothing needs to reach in from the internet.

An inbound TCP port reachable by the terminals

Default 7005. The terminals connect to the connector, so this port must be open on the host’s local network.

A connector secret

A shared secret that authenticates the connector to OnTime. Ask your OnTime contact to provision one.

The connector cannot run on Render, where the rest of OnTime is deployed. Render web services accept only public HTTP(S), and the connector needs a raw TCP listener. Run it on your own network — which is where it belongs anyway, next to the hardware.

Configuration

Four environment variables:

Variable	Default	Meaning
`LOGSERVER_PORT`	`7005`	The TCP port terminals connect to.
`BACKEND_URL`	`http://localhost:3000`	Your OnTime backend’s base URL. Set this — the default is for local development.
`CONNECTOR_SECRET`	`dev-insecure-connector-secret`	The bearer secret. Set this.
`DEVICE_TZ_OFFSET`	`+05:30`	The timezone the terminals report wall-clock time in.

Never deploy with the default CONNECTOR_SECRET. It is a development placeholder, its value is published, and it authenticates a service that can write attendance for every organization. Generate a strong random value and set it on both the connector and the OnTime backend — they must match exactly.

Running it

docker run -d \
  --name ontime-connector \
  --restart unless-stopped \
  -p 7005:7005 \
  -e BACKEND_URL="https://app.ontime.hosai.app" \
  -e CONNECTOR_SECRET="<your secret>" \
  -e DEVICE_TZ_OFFSET="+05:30" \
  ontime-connector

The image is built from connector/Dockerfile in the OnTime repository as a bundled single-file build.

--restart unless-stopped matters more than it usually does. The connector is stateless, so restarting it is free — and any punch in flight when it dies is simply re-sent by the device.

Pointing terminals at it

On each terminal, set its LogServer configuration:

Setting	Value
Server IP	The connector host’s address on your local network.
Server port	`7005`, or whatever you set `LOGSERVER_PORT` to.

The exact menu path varies by model — look for “LogServer”, “Server settings” or “Communication” in the device’s admin menu. Once set, the device opens a persistent connection and starts streaming. It should appear in OnTime’s unclaimed-devices list within a minute.

The timezone assumption

F500 terminals report wall-clock time with no timezone. The connector stamps every message with DEVICE_TZ_OFFSET, which defaults to +05:30 (India).If your terminals are set to a different zone, set this to match — otherwise every punch lands at the wrong time, shifting late arrivals, overtime bands and day boundaries.A deployment spanning multiple timezones needs one connector per zone, each with its own offset. There is no per-device offset.

Verifying

Check the connector logs

You should see connections from your terminals and acknowledgement lines as messages are forwarded.

Check the Devices page

Terminals should appear as unclaimed serials, then flip Online once registered.

Run the fake device

To validate the whole path without waiting for a real punch. See Test with a fake device.

Common problems

Terminals connect but nothing reaches OnTime

Check BACKEND_URL and CONNECTOR_SECRET. A wrong secret means OnTime returns 401, so the connector never acknowledges — and the device correctly keeps retrying. Nothing is lost, but nothing arrives either, and the device’s queue backs up.

Terminals cannot connect at all

Firewall on the connector host, or the wrong IP on the device. Confirm the port is reachable from a terminal’s subnet.

Punches arrive at the wrong time

DEVICE_TZ_OFFSET does not match the terminals’ configured timezone.

​Prerequisites

​Configuration

​Running it

​Pointing terminals at it

​The timezone assumption

​Verifying

​Common problems

Prerequisites

Configuration

Running it

Pointing terminals at it

The timezone assumption

Verifying

Common problems