Rangka OS

What is Rangka OS?

Rangka OS is a source-available, declarative operating system for business apps (CRM, sales, invoicing, payments, stock, POS), built first for Indonesian small and medium businesses.

Every module, model, rule, flow, dashboard, print format, theme and backend capability is a .rk file: strict YAML, checked by JSON Schema. The kernel turns those files into Postgres tables, a REST + MCP API, realtime events and the screens of the web app. A running installation changes only through change sets: proposed (by a person, the Console or the Raka AI agent), validated on a copy, previewed with their SQL, approved by a person, applied live and revertible. Money and stock never depend on an LLM.

Status: alpha (v0.5.0-alpha). Rangka runs end to end, backs up and restores, enforces permissions and row scope per organisation and outlet, and is being readied for its first pilot businesses. It is not yet a stable release. See Status.

Features

• Apps as files. Modules hold models, flows, roles, imports and print formats; apps compose modules into what a business uses, with dashboards and processes (contract 0001). An organisation's own fields and rules are overlays in custom/<model>.rk, never edits to the app.
• Documents that behave. Draft → submitted → cancelled, with amend; numbering at submit with per-organisation series; approvals; rupiah as integers (no floats), PPN 12% on DPP 11/12; declared stock moves with recipes and returns; recurring documents.
• Work screens for staff. Screens declared in .rk for the people at the counter or in the field, starting with the POS counter: cart, hold, split tender, sessions with a blind close, receipts, stock per outlet; an offline outbox with idempotency keys (contract 0030).
• Generated everything. Tables and safe migrations (--dry-run, --rollback, destructive steps refused unless allowed), REST (/api/v1), SSE events, MCP tools, list aggregates, dashboards, PDF print formats, spreadsheet imports, CSV export, attachments, plan limits. Every screen works from phone to desktop.
• Change sets. Propose → validate → preview → approve → apply → revert. High-risk changes need the owner; an AI token can never approve or apply.
• Raka in the app. The Rangka AI agent answers in the web app and Console through a sidecar (contract 0020) and changes things only by proposing change sets. skills/ gives Raka and any other agent harness the same Rangka skills (contract 0035).
• Rangka ID built in. Password sign-in (bcrypt), sessions, API tokens, an OpenID Connect provider, roles with outlet scope and Postgres row-level security per organisation.
• One binary. Queue, scheduler, realtime, cache and files run on Postgres and the local disk by default; system.rk decides the drivers. rangka backup / rangka restore archive the database, metadata and uploads.
• A strict validator, twice. The Go kernel and the Python reference (tools/rangka_validate.py) print byte-identical reports: 107 codes, each with file:line:col.

Quick start

Start a project with npm

Needs Node.js 18+ and Docker (for Postgres), or a Postgres 16 of your own. Releases are pre-releases on the next tag for now.

npm create @rangka-os@next my-shop     # asks for the business name, template demo or blank
cd my-shop
npm install                            # installs the rangka binary for your platform
npm run db                             # Postgres 16 in Docker on port 54329
npm run setup                          # validate, migrate, seed
npm run dev                            # http://localhost:8080/app/

The CLI on its own: npx @rangka-os/cli@next validate --apps apps --site site.

Run the container

docker run --rm -p 8080:8080 -v "$PWD:/srv" -e DATABASE_URL=postgres://… ghcr.io/rangka-os/rangka:0.5.0-alpha.5 serve

Pre-releases are tagged by version only; :latest follows the first stable release.

/srv is a project folder as written by npm create @rangka-os. A production compose file (Postgres, Caddy, backups, systemd) with a runbook lives in deploy/juragan/.

Build from source

Needs Go 1.24+ and PostgreSQL 16 server binaries (scripts/pgtemp.sh finds Homebrew, DBngin, Postgres.app and Debian installs, or set PGBIN).

mkdir rangka && cd rangka
git clone [email protected]:rangka-os/rangka-os.git
git clone [email protected]:rangka-os/rangka-connectors.git
git clone [email protected]:rangka-os/rangka-ai.git          # optional: Raka answers in the demo when built

cd rangka-os/kernel
make run-demo                  # throwaway Postgres → migrate → seed → serve on :8080; Ctrl-C cleans up
make run-demo ADDR=:8090       # when 8080 is taken

URL	What
http://localhost:8080/app/	The web app: dashboards, lists, forms, approvals, imports, print
http://localhost:8080/console/	Rangka Console for operators (demo sign-in [email protected] / rangka-demo)
http://localhost:8080/api/v1/meta	Metadata API
POST http://localhost:8080/mcp	MCP endpoint for AI clients

make run-demo serves with --dev-open (API without sign-in, as the owner). Never use that flag on a real server.

Other commands, from kernel/:

make test-unit        # go test without a database
make test             # every package against a throwaway Postgres
make validate         # validate the catalogue, sites and connectors
make compare-python   # Go and Python validators must print identical reports

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗