# BasaltDB

> BasaltDB is the action ledger for AI agents on a Postgres you already own. It is not a database. Released under Apache-2.0.

Agents: connect with MCP (`/reference/mcp-tools/`). Call `run_start` with an intent before writing. Every page is also Markdown (append `.md` to the URL path); full export: `/llms-full.txt`.

Engine: https://github.com/BasaltDBHq/BasaltDB


## Get started

- [BasaltDB](https://docs.basaltvault.app/): The action ledger for AI agents on your database. · [Markdown](https://docs.basaltvault.app/index.md)
- [What is BasaltDB](https://docs.basaltvault.app/start/what-is-basaltdb/): What BasaltDB does for an agent that writes to your Postgres, and where it stops. · [Markdown](https://docs.basaltvault.app/start/what-is-basaltdb.md)
- [Quickstart](https://docs.basaltvault.app/start/quickstart/): Let an agent change a sample table, watch it get refused when it tries to drop one, edit a row yourself, then undo the run and keep your edit. · [Markdown](https://docs.basaltvault.app/start/quickstart.md)
- [Install](https://docs.basaltvault.app/start/install/): Install basalt and guard the tables your agent may change on your own Postgres. · [Markdown](https://docs.basaltvault.app/start/install.md)
- [Connect an agent](https://docs.basaltvault.app/start/connect-agent/): Connect OpenCode, Claude Code, Codex, or a bot on its own computer to BasaltDB over MCP. · [Markdown](https://docs.basaltvault.app/start/connect-agent.md)

## How it works

- [Runs](https://docs.basaltvault.app/concepts/runs/): A run is one job with one stated reason. Every write carries the reason, and the run is what you review and undo. · [Markdown](https://docs.basaltvault.app/concepts/runs.md)
- [Rules](https://docs.basaltvault.app/concepts/rules/): What your agent may do by default, and what BasaltDB holds or refuses. · [Markdown](https://docs.basaltvault.app/concepts/rules.md)
- [Undo](https://docs.basaltvault.app/concepts/undo/): How undo works when rows changed after the agent. Your team or your app wins, and undo lists what it left alone. · [Markdown](https://docs.basaltvault.app/concepts/undo.md)
- [The ledger](https://docs.basaltvault.app/concepts/ledger/): What BasaltDB records for every action an agent asks for, where it is kept, and for how long. · [Markdown](https://docs.basaltvault.app/concepts/ledger.md)
- [Approvals](https://docs.basaltvault.app/concepts/approvals/): How a held write waits for your passkey signature, what the approval is bound to, and when it expires. · [Markdown](https://docs.basaltvault.app/concepts/approvals.md)
- [Architecture](https://docs.basaltvault.app/concepts/architecture/): The engine runs next to your agent and the guard runs inside your Postgres. Your data never moves. · [Markdown](https://docs.basaltvault.app/concepts/architecture.md)

## Guides

- [Undo a run](https://docs.basaltvault.app/guides/undo/): Preview an undo, approve it and check the result with basalt revert. Anything your team or your app changed since stays as it is. · [Markdown](https://docs.basaltvault.app/guides/undo.md)
- [See what it did](https://docs.basaltvault.app/guides/see-what-it-did/): Read what an agent did, run by run, with basalt log. Reasons, rows, old and new values, and what was refused. · [Markdown](https://docs.basaltvault.app/guides/see-what-it-did.md)
- [When something is refused](https://docs.basaltvault.app/guides/refused/): Find what your agent reported, such as refused, held, stale read, row limit, intent missing or timeout, and what the agent and you should do next. · [Markdown](https://docs.basaltvault.app/guides/refused.md)
- [A bot on its own computer](https://docs.basaltvault.app/guides/bot-own-computer/): Set up BasaltDB for a bot that runs on a machine you cannot reach. The bot makes a setup code, and you run it on your own computer, where your database password stays. · [Markdown](https://docs.basaltvault.app/guides/bot-own-computer.md)
- [Hosts](https://docs.basaltvault.app/guides/hosts/): Which connection string and which role to use with Supabase, RDS or a Postgres you host yourself, and what to watch for on each. · [Markdown](https://docs.basaltvault.app/guides/hosts.md)
- [Passkeys](https://docs.basaltvault.app/guides/passkeys/): Register, list, check and remove the passkeys that approve held writes and undos, and what to do when you lose one. · [Markdown](https://docs.basaltvault.app/guides/passkeys.md)
- [Upgrade](https://docs.basaltvault.app/guides/upgrade/): Upgrade basalt and the guard in your database with basalt upgrade. It never touches your agent's password, grants or passkeys. · [Markdown](https://docs.basaltvault.app/guides/upgrade.md)
- [Remove BasaltDB](https://docs.basaltvault.app/guides/remove/): Remove the guard, the ledger and the BasaltDB roles from your Postgres with basalt uninstall, and see what is left behind. · [Markdown](https://docs.basaltvault.app/guides/remove.md)

## Reference

- [CLI](https://docs.basaltvault.app/reference/cli/): Every basalt command and flag, with what it does, which credential it needs and its exit codes. · [Markdown](https://docs.basaltvault.app/reference/cli.md)
- [MCP tools](https://docs.basaltvault.app/reference/mcp-tools/): Every tool an agent can call on BasaltDB, with its arguments, its result and the errors it can return. · [Markdown](https://docs.basaltvault.app/reference/mcp-tools.md)
- [Error codes](https://docs.basaltvault.app/reference/errors/): Every BasaltDB error code and its reasons, what each means, why it happens, what the agent should do and what you should do. · [Markdown](https://docs.basaltvault.app/reference/errors.md)
- [For agents](https://docs.basaltvault.app/reference/for-agents/): How an AI agent should use BasaltDB. Start a run with an intent, check status, follow nextSteps, never retry a refusal blindly, and ask the person when told to. · [Markdown](https://docs.basaltvault.app/reference/for-agents.md)
- [Change record](https://docs.basaltvault.app/reference/change-record/): The shape of the record BasaltDB keeps for every action an agent asks for, whether it was applied, held or refused, with every field and value. · [Markdown](https://docs.basaltvault.app/reference/change-record.md)
- [Configuration](https://docs.basaltvault.app/reference/config/): The engine config file engine.json, every key and its default, plus the environment variables, paths and role names BasaltDB uses. · [Markdown](https://docs.basaltvault.app/reference/config.md)
- [Limits and defaults](https://docs.basaltvault.app/reference/limits/): Every number BasaltDB uses, such as row limits, hold thresholds, timeouts, expiries, batch sizes and how long records are kept. · [Markdown](https://docs.basaltvault.app/reference/limits.md)

## Project

- [FAQ](https://docs.basaltvault.app/faq/): Short answers to common questions about BasaltDB, from what it is to how you remove it. · [Markdown](https://docs.basaltvault.app/faq.md)
- [What BasaltDB won't catch](https://docs.basaltvault.app/limits/): The honest list of mistakes BasaltDB does not stop, and what you can do about each one. · [Markdown](https://docs.basaltvault.app/limits.md)
- [Security](https://docs.basaltvault.app/security/): How to report a vulnerability in BasaltDB, and a short summary of what it protects against. · [Markdown](https://docs.basaltvault.app/security.md)
- [License](https://docs.basaltvault.app/license/): BasaltDB is released under Apache-2.0. What that allows, and where to read the full text. · [Markdown](https://docs.basaltvault.app/license.md)

## Optional

- [Engine repository](https://github.com/BasaltDBHq/BasaltDB): Source code, releases and the MCP contracts in api/mcp/.