From blank PC to first sale, in one afternoon

This walkthrough follows the path of a brand-new install, in the order you'll actually do it. Each part tells you what should appear on the screen, what it means, and what to do if it doesn't. It's written for a single cashier on a single till — the setup most shops start with. Adding a second till later is covered at the end.

What you'll have when you finish

• A till that sells offline. No internet, no account to reach — the shop runs even when the network doesn't.
• Your products in stock, with prices. Add them by hand or import from a spreadsheet.
• A drawer that balances. Open a shift with the opening float, sell all day, close with the exact expected cash.
• The backup habit. Two minutes a day that make a dead PC an inconvenience instead of a disaster.

What you need

Windows

1. Step 01Open the download page on the till PC and download the Windows 64-bit installer (about 400 MB).
2. Step 02Run the installer. It copies the app, the bundled database, and the runtimes into place — a couple of minutes, no decisions needed.
3. Step 03If SmartScreen shows Windows protected your PC, click More info → Run anyway. This is expected until the installer is code-signed; the file is the one you just downloaded from the site.
4. Step 04Launch Kiosk Desktop from the Start menu or the desktop shortcut.

macOS

1. Step 01Download the macOS app from the download page.
2. Step 02Open the downloaded file and drag Kiosk into Applications.
3. Step 03First launch only: if Gatekeeper says the app is from an unidentified developer, right-click the app → Open → Open again in the confirmation dialog.
4. Step 04Launch Kiosk from Applications.

The first time you launch Kiosk Desktop you'll see a splash screen with a message like Starting your till…. Behind that message the app is doing something important: building your private database from scratch. It creates the local database engine, generates a secure password for it, and applies the full schema — 220+ steps.

1. Step 01Splash appears. “Starting your till…” — the app is initializing the database.
2. Step 02Wait about a minute. On a slow PC or with antivirus scanning the new files it can take a few. This is normal — it only happens once.
3. Step 03Don't close the window. Closing mid-setup leaves the database half-built. If it happens, just relaunch — and since you have no data yet, the worst case is a clean reinstall (Part 9).
4. Step 04The setup wizard appears. That's the signal the database is ready — Part 5.

1. Step 01Create the owner account. Your name, an email, and a password. The owner runs the whole shop — staff, settings, licenses. Don't forget the password; it's the keys to the building.
2. Step 02Set a PIN. You'll use it to unlock the till when it's locked and to identify yourself at the counter.
3. Step 03Name your business. This appears on receipts and reports — pick the name customers will recognize.
4. Step 04Done. Kiosk opens the dashboard. Your shop is alive — with zero products, zero sales, and a fresh ledger.

1. Step 01Add your products. Inventory → add items with a price. Add barcodes if you have them, or print labels; you can also import a whole list from a spreadsheet. Start with the ten things you sell most — the rest can trickle in later.
2. Step 02Set your opening float. The notes and coins you'll put in the drawer at the start of the day. This is the baseline the shift counts against.
3. Step 03Set up the receipt printer (Settings → Desktop → Receipt printer) if you have one — the three modes are below.
4. Step 04Create a cashier PIN (Settings → Staff) so sales are attributed to the person at the counter — or just sell as the owner for now. You can add staff any time.
5. Step 05Make a test sale. Cash, then a credit tab. Check the receipt prints (or the file appears) and the drawer kicks on a cash sale.

The three printer modes

Open the shift

From the cashier screen, open a new shift and enter the opening float. From this moment, every sale, drawout, and refund is recorded against this shift. If your counter has several cashiers, only one shift is open at a time — handovers happen at close.

Sell

• Scan a barcode — it lands in the cart instantly.
• Search by name if there's no barcode — the shelf updates as you type.
• Weighed items — plug in a scale and sell by weight; the price follows the weight.
• Apply a discount per line or to the whole cart where you've allowed it.

Take payment

• Cash — key the amount given; the app shows the change to return. Split payment lets you take part cash, part tab, or part wallet in one sale.
• Credit tab — attach the sale to a customer who owes you; their tab balance updates immediately.
• Customer wallet — deduct from money the customer has deposited with you in advance.
• Loyalty — let the customer redeem points toward the bill.

Print the receipt

On Desktop, receipts go through the built-in device bridge to your ESC/POS printer — no browser print dialog. The same bridge fires the cash-drawer kick when a cash sale completes.

Close the shift

At the end of the day (or when the cashier hands over), close the shift and count the drawer. Kiosk totals the expected cash from the ledger; the difference between expected and counted is your variance — zero is a perfect day. Drawouts (cash removed mid-shift) are tracked separately so they never look like shortages.

1. Step 01Settings → Desktop → Backups → Backup now. The file lands in the backups/ folder of your data directory.
2. Step 02Back up at least daily — the evening habit: close the shift, run the backup. Two minutes.
3. Step 03Copy the backup off the PC — a flash drive, another machine, anywhere. A backup on the same disk as the shop is not a backup.
4. Step 04To restore: Settings → Desktop → Backups → Restore next to the file. It overwrites the database and asks you to restart Kiosk.

The “Kiosk couldn't start” dialog

On Windows, if the app doesn't come up, the launcher can show a dialog that looks like this:

Here's what it means. The launcher starts the app's backend, then waits for a health check on port 5050 before opening the window. “Actively refused it (os error 10061)” is Windows' way of saying nothing is listening on 5050 yet — either the backend is still booting, or it stopped while booting.

1. Step 01Reinstall with the latest installer. Downloads published after this message was written wait up to five minutes instead of ninety seconds — a slow first launch on a modest PC is no longer a false alarm. If the backend really does crash, the newer dialog names the exact log file instead of waiting silently.
2. Step 02Read kiosk.log. Its path is printed in the dialog. Open it and look at the last lines — they say exactly what happened. On Windows it lives at C:\Users\<you>\AppData\Roaming\Palmart\kiosk.log.
3. Step 03If the dialog names backend.out.log or backend.err.log, open those too — they hold the backend's own story, including any crash.
4. Step 04Make sure nothing else holds the ports. Another program on port 5050 or 33306 will stop Kiosk from starting. Close the other program (or uninstall it) and launch Kiosk again.
5. Step 05Antivirus again? If your scanner quarantined part of the app on install, allow the Kiosk folder and reinstall.
6. Step 06Still stuck? Send the kiosk.log file to support. That one file is the whole story.

Ports & log files

Kiosk Desktop uses three local ports. They belong to this PC — you shouldn't need to touch them, but they explain almost every startup error:

• kiosk.log — the launcher's diary; start here.
• backend.out.log / backend.err.log — the backend itself.
• mariadb.log — the database.
• backups/ — backups you create.

Common symptoms, quick fixes

Full reset

To start completely fresh: uninstall Kiosk Desktop, then delete the data folder for your OS (above). This removes the database, media, and logs — keep a backup file somewhere safe first, because nothing survives a reset. Reinstall and the first launch builds a brand-new database (Part 4, again).

Frequently asked questions

Does the shop need internet to sell?

No. Selling, stock, tabs, shifts, and reports run entirely on the PC. Only M-Pesa STK and outbound SMS (cloud features) need the internet, and Desktop doesn't use those.

The first launch is slow — is that normal?

Yes. The first launch builds the entire database from scratch (220+ schema steps) and can take a minute or two on a modest PC. It happens exactly once; every later launch is seconds.

I closed the window during first launch. Now what?

Just launch Kiosk again. Because you have no data yet, the worst case is a clean start: uninstall, delete the data folder, reinstall. Nothing is lost before your first sale.

Can I add a second till later?

Yes — enable Share on LAN (Settings → Desktop) and any device on the same Wi-Fi opens the till in its browser, writing to the same database. The complete guide walks through it.

What happens to my data if the PC dies?

That's what backups are for. Run one daily and copy it off the PC; restore it onto the replacement machine and the shop comes back. Without a backup, the data is on that disk only.

Is there a monthly fee?

Desktop starts with a 30-day trial, then runs on a license key from your vendor — one license per machine. There's no usage metering; it's a flat offline subscription.

Can I take M-Pesa on Desktop?

Not STK push — that's a cloud feature. On Desktop you take cash, credit tabs, wallet, and loyalty offline. When the shop outgrows one PC, the guide explains the move to the cloud.