Skip to content
Back to search

backenly

Autonomous backend platform. Your coding agent builds it over MCP, Backenly keeps it running: Postgres, REST APIs, auth, storage, realtime, and functions, with every change governed, verified, and reversible.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/backenly/backenly with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/backenly/backenly'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/backenly--backenly/badge.svg)](/listings/backenly--backenly)

HTML

<a href="/listings/backenly--backenly"><img src="/api/listings/backenly--backenly/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Cloud

Create a project at **[backenly.com](https://backenly.com)**, then point your agent at it. Nothing to install or operate.

Self-hosted

One deployment is one project.

git clone https://github.com/backenly/backenly.git
cd backenly
npm install
npm run selfhost

That is the whole install. It generates the secrets, starts the Compose stack, creates the tables, runs the superuser steps, issues the PostgREST credential and reconciles until the deployment reports ready. Then:

npm run dev                   # dashboard :3000 · runtime :3001

Then **claim the deployment**. The installer prints a claim link carrying a setup token. Open it and create your account: the first account to present the token becomes the administrator and takes ownership of this deployment's single project in the same step. There is no second command to run. The signup page also has a **Setup token** field while the deployment is unclaimed, if you would rather paste the token than follow the link.

The token is in `.env` as `BACKENLY_SETUP_TOKEN`. It gates the claim because a deployment is often reachable before its operator gets to it — an open port on a VPS, a preview environment, a colleague pointed at the wrong host — and without it the single administrator slot would go to whoever loaded the page first. Once the deployment is claimed the token stops working, whatever it is set to.

Email

Claiming the deployment needs no email. Two things do: **password-reset codes**, and the code a new account must enter before it exists if you open registration with `BACKENLY_ALLOW_PUBLIC_SIGNUP=true`. Set any SMTP provider in `.env`:

SMTP_HOST=smtp.resend.com     # or SES, Mailgun, SendGrid, Gmail
SMTP_PORT=587                 # STARTTLS; 465 is rewritten to 587
SMTP_USER=resend
SMTP_PASS=...
SMTP_FROM=Backenly <noreply@yourdomain.com>   # a domain your provider has verified

Without it, the reset page says email is unavailable rather than pretending a code was sent, and later signups are refused rather than created unverified. To reset a password without email, run this on the server:

npm run auth:reset-password -- --email you@example.com              # prompts
npm run auth:reset-password -- --email you@example.com --generate   # prints one

It ends every session for that account. Access to the machine is the authority, as it is for the setup token.

The four credentials

The install creates a separate PostgreSQL role for each job, rather than one that does everything:

| Role | Used by | Properties | | --- | --- | --- | | `backenly_user` | the install scripts only | `SUPERUSER`. Creates roles, installs event triggers. Never in `DATABASE_URL`. | | `backenly_app` | web and runtime | **`NOSUPERUSER NOBYPASSRLS`**. Owns the platform tables and workspace schemas, so governed typed actions keep their DDL rights. | | `backenly_authenticator` | PostgREST | `NOINHERIT`; can only switch into `anon` / `authenticated` / `service_role`. | | `backenly_backup` | `pg_dump` only | `NOSUPERUSER BYPASSRLS`, with `CONNECT`, `USAGE`, `SELECT` and nothing else. |

`backenly_app` not being a superuser is the one that matters most. A superuser bypasses row-level security — including `FORCE ROW LEVEL SECURITY` — so an application running as one has its own policies applied only by convention. Ownership plus `FORCE` is what keeps DDL working while leaving RLS in force.

Restore runs over the application connection, not the backup one, so the application keeps ownership of the schema it restored.

`npm run selfhost` is **safe to rerun**. It fills in what is missing and never rotates a secret that already exists, so a rerun cannot sign out your sessions or break a running PostgREST.

It does not hide the steps or replace them: it runs the same sequence [documented below](#doing-it-by-hand), driven by the same module that `npm run bootstrap` prints its guidance from. Read that section if you are

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 659 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="public/backenly-icon-hd.svg" alt="Backenly" width="112" height="112" />
  3. # Backenly
  4. ### Your coding agent builds it. Backenly keeps it running.
  5. The autonomous backend platform for agentic coding. PostgreSQL, REST APIs, auth,
  6. storage, realtime, and functions, driven by your coding agent over MCP, with every
  7. change planned, verified, and reversible.
  8. <br/>
  9. [![License](https://img.shields.io/badge/platform-Apache--2.0-3b82f6?style=flat-square)](LICENSE)
  10. [![Clients](https://img.shields.io/badge/SDK%20%C2%B7%20CLI%20%C2%B7%20MCP-MIT-22c55e?style=flat-square)](packages/)
  11. [![npm downloads](https://img.shields.io/npm/dm/@backenly/mcp-server?style=flat-square&label=mcp%20server&color=f59e0b)](https://www.npmjs.com/package/@backenly/mcp-server)
  12. [![Contributors](https://img.shields.io/github/contributors/backenly/backenly?style=flat-square&color=64748b)](https://github.com/backenly/backenly/graphs/contributors)
  13. [![GitHub stars](https://img.shields.io/github/stars/backenly/backenly?style=flat-square&label=stars&color=8b5cf6)](https://github.com/backenly/backenly/stargazers)
  14. [![Follow on X](https://img.shields.io/badge/Follow-%40Backenly-0f0f0f?style=for-the-badge&logo=x&logoColor=white)](https://x.com/Backenly)
  15. [![LinkedIn](https://img.shields.io/badge/LinkedIn-Backenly-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/company/117034579)
  16. [![Star on GitHub](https://img.shields.io/badge/Star-on%20GitHub-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/backenly/backenly)
  17. <a href="https://www.producthunt.com/products/backenly-2?embed=true&amp;utm_source=badge-top-post-badge&amp;utm_medium=badge&amp;utm_campaign=badge-backenly-2" target="_blank" rel="noopener noreferrer"><img alt="#4 Product of the Day on Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=1297694&amp;theme=neutral&amp;period=daily&amp;t=1793532522574"></a>
  18. **[backenly.com](https://backenly.com)** &nbsp;·&nbsp; [Docs](https://backenly.com/docs) &nbsp;·&nbsp; [Pricing](https://backenly.com/pricing) &nbsp;·&nbsp; [Client libraries](https://github.com/backenly/backenly-js)
  19. https://github.com/user-attachments/assets/2b215d72-4b1b-4a4c-8290-a94553be192d
  20. </div>
  21. > ⭐ **Star the repo** to follow releases and help other builders find Backenly.
  22. ---
  23. ## What this is
  24. Most backend platforms hand you primitives and leave you owning schema design,
  25. API wiring, RLS policies, monitoring, and recovery. Newer agent-native backends
  26. hand an agent raw SQL and no safety net.
  27. Backenly does neither. You describe the product you're building through the
  28. coding agent you already use (Claude Code, Cursor, Codex) over an MCP server.
  29. Backenly derives the data model, generates the endpoints, writes the policies,
  30. applies the change, and then **verifies it against the live runtime**. A
  31. continuous autonomy loop keeps watching after that, repairing drift, missing
  32. indexes, broken triggers, and RLS gaps on its own. When a table starts doing
  33. two jobs, Backenly moves the second into a table of its own once you approve,
  34. while your apps keep working, and every change can be undone from one History
  35. without rewinding your data.
  36. The distinction that matters: Backenly does not just *generate* backend
  37. resources, it *manages backend change safely*. Every mutation, whether it comes
  38. from an agent, from the dashboard, or from an automated repair, goes through one
  39. typed action kernel with dry-run, audit, and rollback. There is deliberately no
  40. raw-SQL path for mutating structure. Reads are standard SQL, and your data is
  41. never locked in: direct Postgres connection strings and full `pg_dump` exports
  42. are one command away.
  43. ## How it works
  44. <div align="center">
  45. <img src=".github/assets/architecture.svg" width="100%" alt="Your coding agent drives Backenly over MCP. The Brain plans the change, executeAction governs and verifies it, and it lands in PostgreSQL. A closed MAPE-K autonomy loop watches the running backend and repairs it back through the Brain." />
  46. </div>
  47. - **Intent-first.** An LLM planner derives entities, relations, and actions from
  48. natural language. No table designer, no hand-written migrations.
  49. - **One governed kernel.** Every mutation flows through `executeAction`, so the
  50. agent's model of the database and the database itself cannot silently diverge.
  51. - **Closed-loop autonomy.** The loop heals the reversible safe band by itself.
  52. Anything risky, such as auth, external credentials, or destructive and
  53. irreversible changes, always waits for a human.
  54. - **Multi-tenant by construction.** Each project gets its own PostgreSQL schema
  55. (`workspace_{projectId}`). Isolation is enforced by Postgres grants and RLS,
  56. never by application-level string filtering.
  57. - **PostgREST data plane.** Tables are served through PostgREST, so the query
  58. grammar you already know works unchanged.
  59. ## Core capabilities
  60. | Capability | What you get |
  61. |---|---|
  62. | **Database** | PostgreSQL with a schema per project, served through PostgREST |
  63. | **Auth & Users** | Email/password and social sign-in, JWT sessions, RLS-forced user tables |
  64. | **Storage** | Public and private buckets with per-file access control |
  65. | **Realtime** | Shared `LISTEN`/`NOTIFY` hub for table change subscriptions |
  66. | **Functions** | Serverless route modules, validated before they ship and self-healed if they break |
  67. | **Integrations** | One `ctx.integrations.<id>.request()` surface for third-party APIs |
  68. | **Autonomy** | MAPE-K loop that observes, detects, proposes, applies, and verifies repairs |
  69. | **Restructuring** | A table doing two jobs is split in two after you approve: rehearsed on a copy, kept in step while apps keep working, undoable |
  70. | **History** | One entry per change to schema, auth, storage, functions, webhooks, env, keys, and integrations; undo one or roll back to a point, app data never rewound |
  71. | **Monitoring** | Request logs with stability and reliability scoring |
  72. | **Branches** | Preview branches with their own sequences, plus diff and merge |
  73. | **Deploy** | Governed rollout with restore points and an audit ledger |
  74. ## What your agent can actually do
  75. The MCP server advertises **20 tools**. The catalog is capped deliberately, because
  76. tool-selection accuracy degrades as it grows, while the dispatcher stays wider so an
  77. agent pinned to an older manifest never gets a 404.
  78. | Group | Tools |
  79. |---|---|
  80. | **Understand** | `read_backend_state` · `get_table_schema` · `run_query` · `fetch_docs` |
  81. | **Build** | `apply_migration` · `enable_auth` · `set_rls` · `create_bucket` · `generate_function` · `enable_realtime` |
  82. | **Data** | `db_insert` · `db_update` · `db_delete` |
  83. | **Operate** | `branch` · `create_api_key` · `set_env_var` · `get_database_credentials` · `check_approval` · `generate_types` |
  84. | **Natural language** | `backend_chat`, the fall-through for anything not named above |
  85. Agents can also browse live project state as MCP **resources** (`backenly://state`,
  86. `tables`, `apis`, `buckets`, `triggers`) instead of spending a tool call to ask.
  87. ## Quick start
  88. ### Cloud
  89. Create a project at **[backenly.com](https://backenly.com)**, then point your agent
  90. at it. Nothing to install or operate.
  91. ### Self-hosted
  92. One deployment is one project.
  93. ```bash
  94. git clone https://github.com/backenly/backenly.git
  95. cd backenly
  96. npm install
  97. npm run selfhost
  98. ```
  99. That is the whole install. It generates the secrets, starts the Compose stack,
  100. creates the tables, runs the superuser steps, issues the PostgREST credential
  101. and reconciles until the deployment reports ready. Then:
  102. ```bash
  103. npm run dev # dashboard :3000 · runtime :3001
  104. ```
  105. Then **claim the deployment**. The installer prints a claim link carrying a
  106. setup token. Open it and create your account: the first account to present the
  107. token becomes the administrator and takes ownership of this deployment's single
  108. project in the same step. There is no second command to run. The signup page
  109. also has a **Setup token** field while the deployment is unclaimed, if you
  110. would rather paste the token than follow the link.
  111. The token is in `.env` as `BACKENLY_SETUP_TOKEN`. It gates the claim because a
  112. deployment is often reachable before its operator gets to it — an open port on
  113. a VPS, a preview environment, a colleague pointed at the wrong host — and
  114. without it the single administrator slot would go to whoever loaded the page
  115. first. Once the deployment is claimed the token stops working, whatever it is
  116. set to.
  117. #### Email
  118. Claiming the deployment needs no email. Two things do: **password-reset
  119. codes**, and the code a new account must enter before it exists if you open
  120. registration with `BACKENLY_ALLOW_PUBLIC_SIGNUP=true`. Set any SMTP provider in
  121. `.env`:
  122. ```bash
  123. SMTP_HOST=smtp.resend.com # or SES, Mailgun, SendGrid, Gmail
  124. SMTP_PORT=587 # STARTTLS; 465 is rewritten to 587
  125. SMTP_USER=resend
  126. SMTP_PASS=...
  127. SMTP_FROM=Backenly <noreply@yourdomain.com> # a domain your provider has verified
  128. ```
  129. Without it, the reset page says email is unavailable rather than pretending a
  130. code was sent, and later signups are refused rather than created unverified.
  131. To reset a password without email, run this on the server:
  132. ```bash
  133. npm run auth:reset-password -- --email you@example.com # prompts
  134. npm run auth:reset-password -- --email you@example.com --generate # prints one
  135. ```
  136. It ends every session for that account. Access to the machine is the
  137. authority, as it is for the setup token.
  138. #### The four credentials
  139. The install creates a separate PostgreSQL role for each job, rather than one
  140. that does everything:
  141. | Role | Used by | Properties |
  142. | --- | --- | --- |
  143. | `backenly_user` | the install scripts only | `SUPERUSER`. Creates roles, installs event triggers. Never in `DATABASE_URL`. |
  144. | `backenly_app` | web and runtime | **`NOSUPERUSER NOBYPASSRLS`**. Owns the platform tables and workspace schemas, so governed typed actions keep their DDL rights. |
  145. | `backenly_authenticator` | PostgREST | `NOINHERIT`; can only switch into `anon` / `authenticated` / `service_role`. |
  146. | `backenly_backup` | `pg_dump` only | `NOSUPERUSER BYPASSRLS`, with `CONNECT`, `USAGE`, `SELECT` and nothing else. |
  147. `backenly_app` not being a superuser is the one that matters most. A superuser
  148. bypasses row-level security — including `FORCE ROW LEVEL SECURITY` — so an
  149. application running as one has its own policies applied only by convention.
  150. Ownership plus `FORCE` is what keeps DDL working while leaving RLS in force.
  151. Restore runs over the application connection, not the backup one, so the
  152. application keeps ownership of the schema it restored.
  153. `npm run selfhost` is **safe to rerun**. It fills in what is missing and never
  154. rotates a secret that already exists, so a rerun cannot sign out your sessions
  155. or break a running PostgREST.
  156. It does not hide the steps or replace them: it runs the same sequence
  157. [documented below](#doing-it-by-hand), driven by the same module that
  158. `npm run bootstrap` prints its guidance from. Read that section if you are
  159. bringing your own database, if a step failed and you want to run it yourself,
  160. or if you would simply rather see what is being done to your machine.
  161. The installer generates everything except one choice: which AI provider
  162. serves the natural-language tools (`backend_chat`, function generation). Set
  163. `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in `.env`, or `AI_PROVIDER=bedrock`
  164. with `BEDROCK_REGION` to use Claude through your AWS account. Without one,
  165. those tools say AI is unavailable; the typed tools and the self-healing loop
  166. need no model.
  167. <a name="doing-it-by-hand"></a>
  168. ## Doing it by hand
  169. The same install, one step at a time. `npm run bootstrap` is the centre of it:
  170. it provisions the project, and it is a reconciler rather than an installer, so
  171. rerunning it repairs whatever is missing and changes nothing else. You will run
  172. it at least twice, and that is the intended path, not a failure.
  173. **You install on the host:**
  174. - **Node.js 20+** — the app, the scripts and the CLI all run here, not in a
  175. container
  176. - **Docker**, with Compose
  177. **The Compose stack provides:**
  178. - **PostgreSQL 15**, with `pg_stat_statements` preloaded
  179. - **Redis**
  180. - **PostgREST**, pinned — this is the `/db/*` data plane
  181. Docker does not provide Node. If you would rather run your own PostgreSQL or
  182. PostgREST, read [Bringing your own database](#bringing-your-own-database) first;
  183. the steps below describe the Compose path.
  184. > **Use a PostgreSQL cluster dedicated to this deployment.**
  185. >
  186. > PostgREST authenticates through cluster-global roles, and the list of schemas
  187. > it serves is stored as a role setting with no `IN DATABASE` scope. Two
  188. > Backenly databases on one cluster therefore overwrite each other's
  189. > served-schema registry, and the loser's data plane answers `PGRST106` on every
  190. > table. This is a known limitation being redesigned, not something you can
  191. > configure around. The Compose stack gives you a dedicated one.
  192. #### 1. Install
  193. ```bash
  194. git clone https://github.com/backenly/backenly.git
  195. cd backenly
  196. npm install
  197. cp .env.example .env
  198. docker compose -f docker-compose.dev.yml up -d
  199. ```
  200. `postgrest` will restart in a loop until step 4 issues its password. That is
  201. expected, and it is deliberate that it serves nothing until then.
  202. Then set these in `.env`, adding any line the template does not already carry —
  203. today that is `BACKENLY_PROJECT_ID`:
  204. ```bash
  205. BACKENLY_PROJECT_ID=<uuid> # any UUID, e.g. `uuidgen`
  206. JWT_SECRET=<openssl rand -hex 32>
  207. POSTGREST_JWT_SECRET=<openssl rand -hex 32>
  208. STORAGE_SECRET=<openssl rand -hex 32>
  209. ANTHROPIC_API_KEY=<your key> # or OPENAI_API_KEY, or AI_PROVIDER=bedrock + BEDROCK_REGION
  210. ```
  211. `BACKENLY_EDITION` is already `single-tenant` in the template and you can leave
  212. it there. Backenly resolves an unset edition to `single-tenant` too, so the line
  213. is not what makes this a self-host install — it is there because
  214. `scripts/deploy.sh` composes through `scripts/compose-cloud.sh`, which refuses to
  215. guess an edition rather than risk cloning a private repository you cannot read.
  216. `DATABASE_URL` already matches the Compose stack, so leave it alone unless you
  217. changed `POSTGRES_USER` or `POSTGRES_PASSWORD`.
  218. `BACKENLY_PROJECT_ID` is the identity of this deployment and must never change
  219. afterwards: it names the `workspace_<uuid>` schema your tables live in. Bootstrap
  220. refuses to run against a database that already holds a different one. You may
  221. leave it unset and pin the id bootstrap generates instead, but then step 4's
  222. command has to be copied from bootstrap's output rather than from here.
  223. `JWT_SECRET` signs every platform session. `POSTGREST_JWT_SECRET` is separate and
  224. must match the value Compose passes to PostgREST, because the gateway mints
  225. short-lived internal tokens with it. `STORAGE_SECRET` signs the access tokens for
  226. stored files — without it every upload fails with a 500 whose only explanation is
  227. in the server log. None of the three has a default, deliberately: a fallback
  228. baked into a public repository is a key everybody already knows.
  229. The AI provider key powers the natural-language tools; `.env.example` lists the
  230. providers, per-purpose model overrides and monthly AI spending limits. See
  231. [`.env.example`](.env.example) for the rest.
  232. #### 2. Tell the database which role Backenly connects as
  233. **Skip this on the Compose path.** The stack already uses `backenly_user`, which
  234. is what the SQL defaults to.
  235. It applies only if you brought your own database and the role in your
  236. `DATABASE_URL` is something else, in which case run, as a superuser:
  237. ```bash
  238. psql -c "ALTER DATABASE <db> SET backenly.app_role = '<your role>'"
  239. ```
  240. Skipping it there makes the next section fail with
  241. `role "backenly_user" does not exist`.
  242. #### 3. Create the tables and bootstrap
  243. ```bash
  244. npm run db:generate && npm run db:push
  245. npm run bootstrap
  246. ```
  247. > **`db:push` belongs to this step only — do not rerun it later.**
  248. >
  249. > The PostgREST support objects are created by SQL in step 4, not by Prisma: a
  250. > registry table and two event triggers that fire on schema DDL. `prisma db
  251. > push` does not know about them, so on an installed deployment it treats them
  252. > as objects to drop, which is exactly what `--accept-data-loss` authorises.
  253. > The registry is what the data plane reads to decide which schemas PostgREST
  254. > serves, so losing it takes `/db/*` down.
  255. >
  256. > `npm run bootstrap` is the command that is safe to rerun. It is a reconciler
  257. > and repairs whatever is missing.
  258. **This first run is expected to exit 3.** Bootstrap creates the project row, its
  259. workspace schema and its signing secret, then reports what it cannot install
  260. itself. Its exit code is the state, and deployment automation should read it:
  261. | exit | meaning |
  262. | --- | --- |
  263. | `0` | ready |
  264. | `2` | refused. The database is in a state bootstrap will not touch, either more than one project or a `BACKENLY_PROJECT_ID` that does not match what is already there. Nothing was written. |
  265. | `3` | core bootstrapped, prerequisites still unmet. **Not** ready: the `/db/*` data plane will answer `PGRST106` until step 4 is done. |
  266. #### 4. Install the prerequisites bootstrap cannot install itself
  267. These reach the database as a superuser. Bootstrap prints this same list, with
  268. your real project id filled in; run what it prints.
  269. ```bash
  270. # 1. support objects: registry functions, DDL event triggers, and the
  271. # anon / authenticated / service_role / backenly_authenticator roles.
  272. bash scripts/postgrest-install.sh
  273. # 2. passwords, role membership and the per-schema grants.
  274. # Prints the connection string PostgREST authenticates with. Store it: it is
  275. # not recoverable, and this command will not print it again.
  276. npx tsx scripts/setup-postgrest-roles.ts --project <PROJECT_ID> --apply
  277. # 3. put that password in .env as POSTGREST_AUTHENTICATOR_PASSWORD, then start
  278. # the data plane. It has been restarting in a loop until now.
  279. docker compose -f docker-compose.dev.yml up -d postgrest
  280. # 4. optional. Only needed to hand out direct psql credentials to a project.
  281. # Backenly is fully operational without it. The first line marks the database
  282. # as holding this deployment's one project, so its admin may allow schema
  283. # changes over a read-write login; a database left unmarked is treated as
  284. # shared by several projects, where such a login changes rows only.
  285. bash scripts/install-sql.sh scripts/sql/dedicated-database.sql
  286. bash scripts/install-sql.sh scripts/setup-direct-access.sql
  287. ```
  288. Those scripts talk to PostgreSQL through one explicit mechanism, chosen by
  289. `BACKENLY_DB_ADMIN`, so the same command works wherever the database lives:
  290. | `BACKENLY_DB_ADMIN` | how it connects |
  291. | --- | --- |
  292. | `docker` (default) | `psql` inside the Compose `postgres` service |
  293. | `url` | `psql -d "$BACKENLY_ADMIN_DATABASE_URL"` — any reachable database |
  294. | `local` | `sudo -u postgres psql` — a cluster installed on this host |
  295. That order is not arbitrary and cannot be collapsed into one command. The first
  296. has to create the roles, because the event triggers it installs grant to them,
  297. and a `CREATE SCHEMA` that grants to a role nobody created aborts. The second
  298. grants per workspace schema, so it needs the schema `npm run bootstrap` already
  299. created above. This is why bootstrap runs, reports NOT ready, and is rerun: it is
  300. a reconciler, and rerunning is the mechanism.
  301. Then rerun:
  302. ```bash
  303. npm run bootstrap
  304. ```
  305. **Exit 0 means ready.** Anything else, read what it printed and fix that; it is
  306. safe to rerun as many times as you need.
  307. #### 5. Run it
  308. ```bash
  309. npm run dev # dashboard :3000 · runtime :3001
  310. ```
  311. `npm run dev` starts both processes together. There is no account yet, so sign up
  312. in the dashboard, then run `npm run bootstrap` once more to issue the anon key
  313. your frontend embeds.
  314. #### Autonomy
  315. The self-healing loop runs by itself. There is nothing to schedule.
  316. `instrumentation.ts` starts an in-process scheduler when the app boots, and it
  317. is active whenever `VERCEL` is unset — which is every self-hosted deployment. The
  318. reconciler ticks **every minute**. `.env.example` already sets the two flags it
  319. needs, so a `.env` copied from it has autonomy on:
  320. ```bash
  321. ENABLE_AUTONOMY_RECONCILER=true # the loop runs at all
  322. ENABLE_AUTONOMY_LIVE_EXECUTION=true # it may apply fixes, not just observe
  323. ```
  324. Confirm it is ticking by watching the process output:
  325. ```
  326. [AutonomyReconciler] Cron run complete — 1 projects, 0 fixes applied, 0 frozen
  327. ```
  328. **`0 projects` is normal on a new install, and does not mean it is broken.** A
  329. project is only reconciled once something has been built in it (a table other
  330. than the built-in `users` table, a function, a bucket, a trigger, a webhook or
  331. enabled auth) *and* it shows recent activity. A project that has only been named
  332. has nothing to be right or wrong about, so the loop skips it and files nothing
  333. against it. Create a table through your agent and the count becomes 1 on the
  334. next tick.
  335. `CRON_SECRET` is **not** required for any of the above. It guards one ad-hoc
  336. endpoint, for forcing a tick without waiting for the minute:
  337. ```bash
  338. CRON_SECRET=<openssl rand -hex 32> # add to .env, then restart
  339. curl -H "x-cron-secret: $CRON_SECRET" http://127.0.0.1:3000/api/cron/autonomy
  340. ```
  341. Nothing calls that URL on its own. The in-process scheduler is the mechanism;
  342. the endpoint is for operators.
  343. #### Backups
  344. Backups are a Backenly Cloud capability and the routes answer 404 on a
  345. self-hosted deployment. Nothing below is needed to run Backenly; it is here
  346. because the same code runs in both editions and the failure it describes is
  347. silent.
  348. A backup is `pg_dump` of one project's `workspace_<id>` schema, gzipped under
  349. `BACKUP_DIR`. It carries tables, rows, indexes, constraints, RLS policies,
  350. `FORCE ROW LEVEL SECURITY` and the end-user `users` table. It is **not** PITR
  351. and not deployment-level disaster recovery: project secrets, API keys, storage
  352. objects and function definitions all live outside that schema.
  353. **`npm run selfhost` creates the backup credential for you.** It converges a
  354. dedicated `backenly_backup` role and records `BACKUP_DATABASE_URL` in `.env`,
  355. as the last step of the install — last because the objects it must be able to
  356. read are created at different times: the platform tables by the migration
  357. chain, the PostgREST registry and event triggers by the elevated SQL after it,
  358. and the workspace schema by bootstrap after that.
  359. This used to be a manual step, and the instructions here were incomplete: they
  360. granted the workspace schema and not `public`, so an operator who followed them
  361. exactly still could not produce a Deployment Recovery bundle. `pg_dump --schema
  362. public` takes a `LOCK TABLE` on every table in the schema and stopped at the
  363. registry:
  364. ```
  365. pg_dump: error: query failed:
  366. ERROR: permission denied for table backenly_pgrst_schema_registry
  367. ```
  368. The credential is needed because workspace tables are `FORCE ROW LEVEL
  369. SECURITY`, and under FORCE even the owner is subject to its policies, so
  370. `pg_dump` over the application role aborts on the first protected table:
  371. ```
  372. pg_dump: error: query failed: ERROR: query would be affected by
  373. row-level security policy for table "users"
  374. ```
  375. On production that meant every nightly backup failed for four days while the
  376. pruner deleted the last good ones, ending at zero on disk. The Compose stack
  377. hides it, because `POSTGRES_USER` there is the bootstrap superuser and
  378. superusers bypass RLS. Managed Postgres does not hide it.
  379. Do **not** fix this by granting `BYPASSRLS` to the application role — that
  380. disables every RLS policy on every tenant at once. The installer creates a role
  381. with exactly this much and no more:
  382. ```
  383. LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE BYPASSRLS NOINHERIT
  384. CONNECT on the database
  385. USAGE + SELECT on public and on every workspace schema
  386. no CREATE, no INSERT/UPDATE/DELETE/TRUNCATE, member of nothing, owns nothing
  387. ```
  388. To converge it by hand on an existing deployment, or after adding a schema:
  389. ```bash
  390. npx tsx scripts/setup-backup-role.ts --apply
  391. ```
  392. Restore deliberately writes back over `DATABASE_URL` instead, so the
  393. application keeps ownership of its own schema — restoring over the backup role
  394. would re-own every table to it, and `FORCE ROW LEVEL SECURITY` keys on the
  395. owner. `tests/integration/backup-role-contract.spec.ts` builds both roles for
  396. real and proves the whole contract, including that the application role is
  397. refused where the backup role succeeds.
  398. #### Bringing your own database
  399. The Compose stack is the supported path. If you already operate PostgreSQL, or
  400. run PostgREST under your own service manager, the differences are:
  401. - Point `DATABASE_URL` and `DIRECT_URL` at your database, and do step 2 above.
  402. - Run the step 4 scripts with `BACKENLY_DB_ADMIN=url` and
  403. `BACKENLY_ADMIN_DATABASE_URL` set to a superuser connection string, or with
  404. `BACKENLY_DB_ADMIN=local` if PostgreSQL is on this machine.
  405. - Start your own PostgREST against the connection string step 4.2 prints, with
  406. `POSTGREST_URL` in `.env` pointing at it and its JWT secret set to
  407. `POSTGREST_JWT_SECRET`. Use the version pinned in
  408. [`docker-compose.dev.yml`](docker-compose.dev.yml): PostgREST reads its
  409. configuration out of the database, so a version difference changes what the
  410. data plane serves.
  411. - Enable `pg_stat_statements` yourself:
  412. ```conf
  413. # postgresql.conf, then restart the server
  414. shared_preload_libraries = 'pg_stat_statements'
  415. ```
  416. ```sql
  417. CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
  418. ```
  419. It is how Backenly finds indexes that are missing by *measurement* — the columns
  420. Postgres is actually spending milliseconds filtering on — rather than only by
  421. schema shape. Without it that check reports itself as unchecked rather than
  422. passing, so nothing claims a guarantee it never evaluated. The Compose stack sets
  423. it already.
  424. ## Connecting a coding agent
  425. Backenly is built to be driven over MCP. Point your agent at the MCP server:
  426. ```bash
  427. npx @backenly/mcp-server init
  428. ```
  429. Works with Claude Code, Cursor, Codex, Cline, and Claude Desktop. Keys are scoped
  430. and revocable, and read-only keys serve a reduced tool set.
  431. > **Restart your MCP host after installing.** Tools stay absent until it
  432. > reconnects, which looks like a broken install but is not one.
  433. Verify the connection by asking your agent:
  434. ```
  435. Call Backenly's read_backend_state tool and tell me what exists in this project.
  436. ```
  437. Then describe what you want. The SDK is for the app you ship:
  438. ```js
  439. const backend = new BackenlyClient({ projectId, apiKey })
  440. await backend.auth.signUp({ email, password })
  441. await backend.posts.create({ title: 'Hello' })
  442. await backend.posts.list({ filter: { published: true } })
  443. ```
  444. ## Repository layout
  445. | Path | What lives there |
  446. |------|------------------|
  447. | `app/` | Next.js routes: dashboard UI, platform APIs, and the public `/api/v1/*` runtime |
  448. | `lib/ai/` | The Brain: planning, the tool loop, and `executeAction`, the governed mutation kernel |
  449. | `lib/orchestration/` | The nine-phase pipeline from intent to verified change |
  450. | `lib/autonomy/` | The MAPE-K loop that monitors and repairs running backends |
  451. | `lib/execution/` | Schema writes, migrations, and rollback beneath the kernel |
  452. | `lib/tenant/` | Schema isolation and the tenant boundary |
  453. | `packages/` | Client libraries: SDK, CLI, MCP server (MIT) |
  454. | `prisma/` | Platform schema: the `public` schema, not tenant data |
  455. | `server/` | Express runtime serving the end-user API |
  456. | `scripts/` | Operational tooling, probes, and the demo recording pipeline |
  457. [`AGENTS.md`](AGENTS.md) is the deeper architectural guide, and is written for
  458. coding agents working in this repo as much as for people.
  459. ## Self-hosting vs Cloud
  460. Self-hosting is free and complete. This repository is the whole platform:
  461. runtime, governance, and the full self-healing engine, not a stripped community
  462. edition. You bring the servers, the Postgres, and an AI provider key.
  463. [Backenly Cloud](https://backenly.com/pricing) runs the same codebase, and
  464. handles infrastructure, backups, upgrades, and the autonomy tokens. `pg_dump`
  465. moves your data between the two in either direction.
  466. ## Contributing
  467. **Pull requests are open and welcome.** Bug reports, feature requests, questions,
  468. and code all help. Good first places to look are open issues, the probe and
  469. detector suite under `lib/autonomy/`, and client library ergonomics in
  470. `packages/`. If a change is large or moves an architectural boundary, open an
  471. issue first so we can agree the approach before you spend the time.
  472. Before opening a PR:
  473. ```bash
  474. npm run lint
  475. npx tsc --noEmit
  476. npm test
  477. npx tsx scripts/preflight-oss.ts --tree # no credentials in what you committed
  478. ```
  479. Two things worth knowing before you write code here. Tests run against a real
  480. PostgreSQL instance, and the database is never mocked, because mocking it has
  481. caused production incidents here before. And every schema mutation goes through
  482. `executeAction`; a patch that writes DDL around the kernel will be sent back, no
  483. matter how correct the SQL is.
  484. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
  485. ## Security
  486. Please do not open a public issue for a security problem. See
  487. [SECURITY.md](SECURITY.md) for the private reporting route.
  488. ## License
  489. The platform is licensed under the [Apache License 2.0](LICENSE).
  490. The client libraries under [`packages/`](packages/), the SDK, CLI, and MCP
  491. server, are MIT, so they impose nothing on the applications that embed them.
  492. ## Trademark
  493. Apache-2.0 §6 grants no rights to the Backenly name or logo, and this project
  494. does not grant them separately. You may fork, modify, self-host, and
  495. commercialise the software. Distributing it under the Backenly name requires
  496. written permission.
  497. Describing your project as "built on Backenly" or "a fork of Backenly" is
  498. accurate and always welcome. See [TRADEMARK.md](TRADEMARK.md) for the full
  499. policy, including what you may do without asking.
  500. ---
  501. <div align="center">
  502. **[Star Backenly on GitHub](https://github.com/backenly/backenly)** to get notified about new releases.
  503. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.