Local development quickstart

Prerequisites

Node.js 20+ (node -v to check)
Odoo 12 running locally at http://localhost:8069 with a POS session open
A terminal with 3 tabs

Step 1: Build the protocol package

The protocol package must be built first since the hub depends on it.

cd nu_pos_sync_protocol
npm install
npm run build

Step 2: Start the hub in dev mode

Open a new terminal tab:

cd nu_pos_hub
npm install

Create a .env file for local development:

.env

ODOO_URL=http://localhost:8069
ODOO_DB=pos
ODOO_USER=admin
ODOO_PASSWORD=admin
HUB_HTTP_PORT=8766
HUB_DB_PATH=./dev.sqlite
HUB_LOG_LEVEL=debug
HUB_MDNS_ENABLED=false
HUB_DEV_AUTH=true

HUB_DEV_AUTH=true enables dev-mode auth bypass. When the frontend sends an empty token, the hub authenticates using its own Odoo credentials instead of rejecting the connection.

Start with tsx (auto-reloads on changes):

npm run dev

Verify it works:

curl http://localhost:8766/health | python3 -m json.tool

Expected output:

{
    "status": "ok",
    "uptime": 5,
    "connectedTerminals": 0,
    "activeLeases": 0,
    "orders": 0,
    "pendingForward": 0,
    "totalForwarded": 0,
    "lastOdooSync": null
}

Open http://localhost:8766/ in a browser to see the live dashboard.

Step 3: Enable hub mode in Odoo

Odoo UI
Python shell
Environment variable

Go to Point of Sale > Configuration
Set nu_hub_enabled = checked
Set nu_hub_url = ws://localhost:8766
Save

config = env['nu.pos.config'].search([], limit=1)
config.write({
    'nu_hub_enabled': True,
    'nu_hub_url': 'ws://localhost:8766',
})

In dev mode with mock bootstrap data:

NEXT_PUBLIC_HUB_URL=ws://localhost:8766 npm run dev

This adds nu_hub_enabled: true and nu_hub_url to the mock bootstrap config automatically.

Step 4: Start the frontend

Open a third terminal tab:

cd nu_pos_react
NEXT_PUBLIC_HUB_URL=ws://localhost:8766 npm run dev

Open two browser tabs:

Tab 1: http://localhost:3000/pos-react/order/?table=1
Tab 2: http://localhost:3000/pos-react/order/?table=1

Both tabs should connect to the hub. The dashboard at http://localhost:8766/ should show 2 connected terminals.

Step 5: Test real-time sync

In Tab 1: Add an item to the order
Watch Tab 2: The item should appear within milliseconds
Check the dashboard: 2 terminals, 1 active lease, events flowing

Test leasing

In Tab 1, open an order (acquires a lease)
In Tab 2, try to open the same order
Tab 2 should see a “LEASE_DENIED”
Navigate away in Tab 1 (releases the lease)
Tab 2 can now acquire the lease

Test offline recovery

Stop the hub (Ctrl+C in the hub terminal)
Add items in Tab 1 — they queue in the localStorage outbox
Restart the hub (npm run dev)
The frontend reconnects automatically and flushes the outbox

Development workflow

Terminal 1 (hub):      npm run dev          # auto-reloads on src/ changes
Terminal 2 (frontend): npm run dev          # Next.js hot reload
Terminal 3 (tests):    npm run test         # vitest watch mode
Browser:               http://localhost:8766  # hub dashboard

Inspecting the hub database

The dev SQLite file is at nu_pos_hub/dev.sqlite:

sqlite3 nu_pos_hub/dev.sqlite

# See all orders
SELECT pos_reference, version, terminal_id, updated_at FROM orders;

# See active leases
SELECT pos_reference, terminal_id, role, expires_at FROM leases;

# See pending events
SELECT id, type, pos_reference, forwarded, created_at FROM events ORDER BY id DESC LIMIT 20;

Testing with wscat

Connect to the hub directly to test the protocol:

npx wscat -c ws://localhost:8766

Then send messages manually:

{"type":"AUTH","token":"your-odoo-session-id","deviceId":"test-001"}

Troubleshooting

Hub won't start: Cannot find module '@nu/sync-protocol'

Build the protocol package first:

cd nu_pos_sync_protocol && npm run build

Auth fails for all terminals

Make sure Odoo is running and credentials in .env are correct. In dev mode, ensure HUB_DEV_AUTH=true is set.

Frontend stays in 'Connecting' state

Is the hub running? curl http://localhost:8766/health
Is nu_hub_enabled set to true?
Check browser DevTools Network tab for WS connections
Look for connection errors in the browser console

Orders not forwarding to Odoo

Is Odoo reachable? curl http://localhost:8069/web/login
Check hub logs for forwarding errors
Ensure ODOO_USER/ODOO_PASSWORD has POS access

'Lease request timed out'

The hub didn’t respond to LEASE_ACQUIRE within 10 seconds. Usually means the hub is overloaded or the message was lost. Check hub logs.

Stale dev.sqlite causing SQLite errors

rm nu_pos_hub/dev.sqlite
# Restart the hub — it recreates the database

Environment variable reference

Variable	Default	Description
`ODOO_URL`	`http://localhost:8069`	Odoo instance URL
`ODOO_DB`	`pos`	Odoo database name
`ODOO_USER`	`admin`	Odoo user for hub session
`ODOO_PASSWORD`	`admin`	Odoo password
`HUB_HTTP_PORT`	`8766`	HTTP + WebSocket port
`HUB_DB_PATH`	`./hub.sqlite`	SQLite database file
`HUB_LOG_LEVEL`	`info`	Log level
`HUB_MDNS_ENABLED`	`true`	mDNS discovery
`HUB_LEASE_TTL_MS`	`60000`	Lease duration (ms)
`HUB_HEARTBEAT_MS`	`20000`	Heartbeat interval (ms)
`HUB_GRACE_MS`	`10000`	Disconnect grace period (ms)
`HUB_FORWARD_INTERVAL_MS`	`5000`	Odoo drain interval (ms)
`HUB_FORWARD_BATCH_SIZE`	`20`	Events per drain batch
`HUB_DEV_AUTH`	`false`	Dev-mode auth bypass

Overview

Core concepts

Implementation

Operations

Local development quickstart

Prerequisites

Step 1: Build the protocol package

Step 2: Start the hub in dev mode

Step 3: Enable hub mode in Odoo

Step 4: Start the frontend

Step 5: Test real-time sync

Test leasing

Test offline recovery

Development workflow

Inspecting the hub database

Testing with wscat

Troubleshooting

Environment variable reference

​Prerequisites

​Step 1: Build the protocol package

​Step 2: Start the hub in dev mode

​Step 3: Enable hub mode in Odoo

​Step 4: Start the frontend

​Step 5: Test real-time sync

​Test leasing

​Test offline recovery

​Development workflow

​Inspecting the hub database

​Testing with wscat

​Troubleshooting

​Environment variable reference

Prerequisites

Step 1: Build the protocol package

Step 2: Start the hub in dev mode

Step 3: Enable hub mode in Odoo

Step 4: Start the frontend

Step 5: Test real-time sync

Test leasing

Test offline recovery

Development workflow

Inspecting the hub database

Testing with wscat

Troubleshooting

Environment variable reference