Documentation

Everything you need to install, use, secure, and manage LockMargin. This page is the authoritative source of truth: everything described below without a "Planned" tag works in the current build.

Install LockMargin

LockMargin is a portable desktop application. No installer, no cloud account, no subscription.

1. Download the latest release from the download page.
2. Extract the .zip archive to any folder on your machine.
3. Run LockMargin.exe. The app launches immediately — no setup wizard, no registration.

System requirements: Windows 10 or Windows 11, 64-bit. No internet connection required.

First launch

On first launch LockMargin creates a local encrypted SQLite database on your machine. Press Ctrl+K to open the Command Palette — it is the primary way to navigate and act. (Cmd+K on macOS — coming soon.)

Optionally enable encryption via Settings > Security > Initialize Encryption. See How encryption works.

Create your first client

1. Press Ctrl+K and type create_client.
2. Fill in name, currency, tax rate, and bank details.
3. Save. Sensitive fields (bank account, tax ID, contact info) are encrypted at the field level when encryption is enabled.

Create your first invoice

1. Open Invoices and choose create_invoice — or create_invoice_from_time to build it from tracked hours.
2. Add line items, tax, and discounts. The status starts as draft.
3. When ready, set the status to sent. Sent invoices are sealed: they can be viewed, not silently edited.

Invoice statuses: draft, sent, paid, overdue, cancelled, refunded.

Export your first PDF

1. Select the invoice and choose generate_invoice_pdf.
2. Pick a folder with save_pdf_file. The PDF is generated locally — no internet required.
3. Optionally send it via SMTP with send_invoice_email (requires internet).

Clients

Full client management with per-client currency, tax rate, and bank details. Encrypted fields when encryption is on: bank_account_encrypted, tax_id_encrypted, contact_info_encrypted. Bulk import via import_clients_csv — processed locally, nothing is sent to a server.

Projects

Organize work into projects with stages (Fixed, Retainer, Hourly), budgets, and a Health Score computed from budget vs. actual spend, timeline, and stage completion. Attach local asset folders to any project.

Time tracking

Active session timer with start/stop; the session persists even if the app closes. Entries support categories and billable/non-billable flags, and feed directly into invoices and the RHR metric.

Expenses

Track expenses by category with receipt attachments, suppliers, and billable flags. Recurring expenses are handled by the same reactive engine as recurring invoices.

Invoices

Partial payments via create_invoice_payment (Stripe, credit, manual) with automatic status recalculation. Reusable templates, discounts, and a full payment history per invoice. Every line item traces back to its source time entry or expense.

Quotes & proposals

Quotes support tax and discount and convert to invoices on acceptance (convert_quote_to_invoice). Proposals are scope documents for larger engagements with their own status workflow.

Recurring engine

LockMargin uses a reactive recurring engine — no cron jobs. Recurring invoices and expenses are generated on demand when they become due, triggered by app launch or a manual check. It works on a plane, in a cafe without Wi-Fi, or on a client site.

Dashboard & metrics

Dashboard v8 computes all metrics locally: Revenue, Expenses, Profit, Margin %, RHR (revenue per hour worked), and Runway (months of operation based on balance vs. monthly burn, including personal expenses). Attention Items flag overdue invoices, low runway, and unhealthy projects.

Where your data lives

All business data is stored locally in a single encrypted SQLite database under your Windows app-data directory. There is no cloud database and no cloud sync — by design.

Open format: SQLite, JSON, CSV. Any tool can read your data — today, tomorrow, in ten years.

How encryption works

• Key derivation: a master key is derived from your passphrase with Argon2id and a random salt.
• Key storage: the master key lives in your system keychain (Windows Credential Manager) — never in the database or in files.
• Field encryption: each encrypted field uses a unique nonce (AES-256-GCM).

Initialize via Settings > Security > Initialize Encryption; verify with check_encryption_status.

Back up your data

1. Open Settings > Backup & Restore, or run create_backup.
2. LockMargin writes a full snapshot of the database to backups\.
3. Review old copies with list_backups; prune with delete_backup.

For a proper setup, follow 3-2-1: local primary, external drive copy, encrypted export offsite. The full argument is in the backup problem article.

Restore from a backup

1. Open Settings > Backup & Restore and choose Restore.
2. Select the backup file and confirm.
3. The app restarts on the restored database.

Export your data

CSV and PDF export are available now for clients, projects, and invoices (export_clients_csv, export_projects_csv, export_invoices_csv, and the PDF equivalents). CSV exports include all fields except encrypted data, which exports as ciphertext. JSON/YAML portability is Planned (Sprint 9).

Open data layer

The data layer is a separate, public project: github.com/vladsh444/lockmargin-data-layer. It includes:

• Schema — documented and public.
• Export / import — CSV, JSON.
• Standalone decryption utility — AES-256-GCM + Argon2id; password = key.

Samples include an encrypted sample.lockmargin file you can open with the password lockmargin-sample.

With your password and any tool, your records are readable without LockMargin. If I disappear, your history survives me.

Soft delete & audit log

Deleting a client, project, time entry, or expense marks it with a deleted_at timestamp instead of removing it. Restore anytime; permanent deletion is a separate explicit action. Every action (CREATE, UPDATE, DELETE, EXPORT) is recorded in an immutable audit_log with a diff snapshot and idempotency key.

Working without internet

LockMargin does not require an internet connection to create, edit, store, or export your work.

What requires internet

Only two things: sending invoice emails via your own SMTP server, and downloading updates. Stripe Payment Links are generated offline; your client completes payment online on Stripe's side. There is no telemetry and no third-party server involved in running the app.

Command Palette

Press Ctrl+K. 21 actions in 4 categories: Create, Navigation, Settings, Help. Built for keyboard-first use; every action also has a direct shortcut. Advanced mode adjusts UI density and visible complexity.

Database overview

One local SQLite database, 33 tables, 47 migrations. Groups: Core (clients, projects, time_entries, expenses, invoices…), Financial (quotes, tax_rates, recurring_items, client_credits), Security (encryption_metadata, audit_log), Auxiliary (backups, email_log, assets, templates). Read why we chose SQLite over PostgreSQL.

Tech stack

Development status

Current release: Early Access. Latest merged work: Sprint 8 — Stealth/Privacy Mode.

Available now: core CRUD, time tracking, expenses, invoicing + recurring + quotes, dashboard + export + search, credit-based payments, AES-256-GCM encryption, stealth mode, multi-currency invoicing & VAT calc Live.

Planned: data portability — JSON/YAML export/import (Sprint 9) Planned; extended multi-currency conversions & reporting (Sprint 10) Planned; reporting engine — P&L, tax reports (Sprint 11) Planned.

Troubleshooting

"database disk image is malformed"

The database file was copied mid-write or synced by a cloud client. Do not keep using the corrupted copy. Restore from the latest backup (restore_backup). Never sync a live database — sync exports and closed copies only.

PDF export fails

Check write permission on the target folder and use save_pdf_file to pick a new location. Generation is local; antivirus software occasionally locks the output file.

Encryption status unknown

Run check_encryption_status. If initialization was interrupted, re-run Initialize Encryption from Settings > Security.

Migration Guides

Step-by-step guides to migrate from popular tools to LockMargin. Export your data, import in ~15 minutes, own your data forever. No subscription.

Was this page helpful? Found an error? Contact support → · Related: Glossary · Security overview · Blog