ekwo-os

# Ekwo OS

**Ekwo** is open source accounting, ready to use on **[Ekwo Cloud](https://cloud.ekwo.ai)**: the web application for your invoices, your bank statements, your VAT returns and the electronic invoices your country uses, in your own instance, with an account opened in a minute. **Ekwo OS** is the free and open source core it runs on, under AGPL-3.0: install it on your own Supabase project and own your accounting data, forever.

Built and maintained by **Ekwo**. Ekwo OS is a schema, the rules of each country as data, and the tools — a command line and an MCP server — with which you, your accountant and the AI agent you choose work in the same books, each with their own access. Ekwo reads any supplier invoice, in any language, with the AI model you choose, and every entry is posted on your confirmation. What Ekwo is, and its limits: [DISCLAIMER.md](DISCLAIMER.md).

![An empty Supabase project, npx ekwo-os init, ekwo status, a company, a sale invoice posted and its VAT return prepared, for two countries side by side](docs/demo/install.gif)

*From an empty Supabase project to a prepared VAT return, for two countries
side by side. How it was recorded: [`docs/demo/`](docs/demo/).*

**Try it on your own books.** Already using Claude? [Start with
Claude](docs/start-with-claude.md) goes from a free Supabase project to your
own books taken over, questioned and your next VAT return prepared, in about
twenty minutes. Or open the same books in the web application,
[Ekwo Cloud](https://cloud.ekwo.ai).

---

## Why Ekwo

> The long version — financial autonomy for every business, accounting as a
> commons, a network rather than a vendor — is in [MANIFESTO.md](MANIFESTO.md).

**The data belongs to the business, and the work of keeping the books can be
done by software the business also owns.** So the whole accounting core is
open, the data sits in a Postgres database you control, and the interface is
designed for machines as much as for people. Supabase gives the schema a REST
API for free, and an MCP server sits on top of it, so an AI agent can book a
purchase, match a payment or prepare a VAT return on your own data — as you,
under your own row level security, without the data leaving your account.

What ships today:

- **The core** — schema, posting rules, taxes, reports, financial statements,
  as migrations you apply to a database you control.
- **A country pack for every country listed below**, each a versioned set of
  data with a year of books that proves it.
- **`ekwo`, the command line** — one command installs everything on your own
  Supabase project; the same tool then keeps books from a terminal.
- **The MCP server**, hosted at `https://mcp.ekwo.ai/mcp` or run locally with
  `npx @ekwo-ai/mcp`, so any AI agent can operate the books.
- **Modules** for fixed assets, budgets, corporate income tax and electronic
  invoicing.
- **Format libraries** under MIT — the files administrations, banks and
  e-invoicing networks exchange, written and read.

Who it is for: a company that wants to keep its own books with an AI at the
keyboard; an accounting firm that runs several companies inside one
installation; a developer who needs a real double-entry core with tax rules as
data rather than as code; and anyone who wants to leave a proprietary system
with the books intact.

## What is in this repository

A double-entry accounting core for Postgres. There is no server to run:
Supabase turns the schema into a REST API with an OpenAPI description, and row
level security decides who sees what.

- **Double entry, enforced by the database.** An entry cannot be posted unless
  it balances, and a locked period refuses writes at the trigger — not in a
  form validator.
- **Documents and entries are two layers.** An invoice answers to EN 16931 and
  Peppol; an entry answers to the chart of accounts. Keeping them apart keeps
  both honest.
- **Country rules are data.** A tax points at the ledger accounts it posts to
  and at the boxes of the declaration it feeds. Adding a régime is a row, not a
  release.
- **Every label is data, in every language a country pack publishes.**
  Identifiers stay English; what a person reads comes from the pack, in the
  language of the company or of the reader. See
  [`docs/languages.md`](docs/languages.md).
- **Every country a pack, out of the box.** <!-- generated:countries -->United Arab Emirates (`ae`), Albania (`al`), Հայաստան (`am`), Angola (`ao`), Argentina (`ar`), Austria (`at`), Australia (`au`), Azərbaycan (`az`), Bosna i Hercegovina (`ba`), Bangladesh (`bd`), Belgium (`be`), Burkina Faso (`bf`), България (`bg`), البحرين (`bh`), Bénin (`bj`), Bermuda (`bm`), Brunei Darussalam (`bn`), Bolivia (`bo`), Canada (`ca`), République démocratique du Congo (`cd`), Centrafrique (`cf`), Congo (`cg`), Schweiz (`ch`), Côte d’Ivoire (`ci`), Chile (`cl`), Cameroun (`cm`), 中国 (`cn`), Colombia (`co`), Costa Rica (`cr`), Cyprus (`cy`), Czechia (`cz`), Germany (`de`), Danmark (`dk`), Dominican Republic (`do`), Algérie (`dz`), Ecuador (`ec`), Estonia (`ee`), مصر (`eg`), España (`es`), Ethiopia (`et`), Finland (`fi`), France (`fr`), Gabon (`ga`), United Kingdom (`gb`), საქართველო (`ge`), Guernsey (`gg`), Ghana (`gh`), Guinée (`gn`), Guinée équatoriale (`gq`), Ελλάδα (`gr`), Guatemala (`gt`), Guinée-Bissau (`gw`), Hong Kong (`hk`), Honduras (`hn`), Croatia (`hr`), Magyarország (`hu`), Indonesia (`id`), Ireland (`ie`), Israel (`il`), India (`in`), Ísland (`is`), Italia (`it`), Jersey (`je`), 日本 (`jp`), Kenya (`ke`), Comores (`km`), 대한민국 (`kr`), Kuwait (`kw`), Cayman Islands (`ky`), Қазақстан (`kz`), Sri Lanka (`lk`), Lietuva (`lt`), Luxembourg (`lu`), Latvija (`lv`), Maroc (`ma`), Moldova (`md`), Crna Gora (`me`), Северна Македонија (`mk`), Mali (`ml`), 澳門 (`mo`), Malta (`mt`), Mauritius (`mu`), México (`mx`), Malaysia (`my`), Moçambique (`mz`), Niger (`ne`), Nigeria (`ng`), Nicaragua (`ni`), Nederland (`nl`), Norge (`no`), New Zealand (`nz`), Oman (`om`), Panamá (`pa`), Perú (`pe`), Philippines (`ph`), Pakistan (`pk`), Polska (`pl`), Portugal (`pt`), Paraguay (`py`), Qatar (`qa`), Romania (`ro`), Srbija (`rs`), Rwanda (`rw`), Saudi Arabia (`sa`), Sverige (`se`), Singapore (`sg`), Slovenia (`si`), Slovensko (`sk`), Sénégal (`sn`), El Salvador (`sv`), Tchad (`td`), Togo (`tg`), ประเทศไทย (`th`), Tunisie (`tn`), Türkiye (`tr`), 臺灣 (`tw`), Tanzania (`tz`), Україна (`ua`), Uganda (`ug`), United States (`us`), Uruguay (`uy`), British Virgin Islands (`vg`), Việt Nam (`vn`), Kosova (`xk`), South Africa (`za`), Zambia (`zm`) and Zimbabwe (`zw`)<!-- /generated --> — each with its chart of accounts, its tax codes, its
  declaration boxes and its financial statements, and all of them installed by
  `ekwo init`, so one installation keeps companies in any of these countries.
  The version and review status of each are in
  [`docs/packs.md`](docs/packs.md#the-packs-of-this-checkout).
- **Statutory files.** The French FEC, XBRL annual accounts, Peppol UBL and
  Factur-X invoices, recapitulative statements — written from the ledger by the
  format libraries.
- **Tested on real Postgres.** The test suite runs the migrations, the seeds,
  the accounting scenarios, the installer and the MCP server against Postgres
  compiled to WebAssembly.

## Modules

The core lives in the `public` schema. Beside it, a module is a schema of its
own, with its own migrations, row level security and tests, enabled per
company.

| Module code | Schema | What it does |
|---|---|---|
| [`assets`](modules/fixed-assets/) | `fixed_assets` | Fixed assets, their depreciation schedule and their disposal. Durations and methods are country pack data. |
| [`budgets`](modules/budgets/) | `budgets` | A budget per financial year and the variance against the ledger. |
| [`tax`](modules/corporate-tax/) | `tax` | Corporate income tax estimated from the books: adjustments, losses and rates are country pack data. An estimate until an owner calls it final. |
| [`einvoicing`](modules/einvoicing/) | `einvoicing` | The electronic invoice of a posted sale, in the format the company's country pack declares, checked against the rules of that format, and every sending with its state. |

```sh
npx -y ekwo-os@latest module list                          # what is here, and what the database holds
npx -y ekwo-os@latest module enable assets --company "…"   # turn one on for a company
```

Then add the module's schema to the project's exposed schemas (Supabase
dashboard → Project Settings → API); `ekwo module enable` prints the line.

A module never writes the ledger directly: it hands its lines to the core,
which applies the same balancing, numbering and lock rules as everywhere else.
[`docs/modules.md`](docs/modules.md) is how to write one.

## Install on your own Supabase project

Create a project at [supabase.com](https://supabase.com) — the free plan is
enough to start — and point the installer at it. Node 20 or later is the only
thing you need locally: no Supabase CLI, no Docker, no clone.

```sh
npx -y ekwo-os@latest init
```

It asks for the connection string, the country, the chart of accounts and the
language where the pack offers a choice, your organisation, the first company
and the address of the first administrator. Then it applies the migrations,
loads every country pack, creates that administrator in *your* Supabase Auth
and opens the first financial year. Running it twice creates nothing twice.

Ekwo does not create the project and does not pay for it: your books are on
your account from the first row. The installation guide, with every flag and
the four settings to change on your project before going live, is
[`packages/cli`](packages/cli/README.md).

Asking an AI agent to do it with you? Point it at [`AGENTS.md`](AGENTS.md).
Each country also has its own step-by-step page on
[ekwo.ai/countries](https://ekwo.ai/countries/), and the whole documentation is
served to a model as `https://ekwo.ai/llms.txt`.

### Keeping it running

```sh
npx -y ekwo-os@latest status