Let any AI agent query your SQL databases: personal data comes back masked,
connections and writes wait for you, and the agent never holds a password.
An agent (here Claude Code, left) and lox run (right, in manual mode: every ticket is asked).
Quick start · How it works · Docs · Lock Family · locksql.com
locksql is a Lock of the Lock Family, harness security for AI agents. A console sits between your agent and MariaDB, MySQL, PostgreSQL or SQLite: it holds the credentials, weighs every statement and masks personal data. The agent only asks.
Note
Pre-release (v0.x): a release may still change the config files,
the MCP tools or the CLI. See the path to 1.0.
- The agent never holds a password. Credentials are typed at console start or read from Vault, in an account and a container the agent cannot reach.
- Approval outside the agent. Each statement becomes a ticket on
lockhub, decided in
lox run(or runs inside a grant you approved once). Reads pass on your rules; connections, writes and schema changes wait for you. - Personal data stays masked. Every output column is traced to its source column and masked there, whatever the query calls it.
- Fail closed. What the classifier cannot classify with certainty is refused, with a code the agent can act on.
In-agent approval is a convenience; a separate approval process is a boundary.
brew trust davidgodefroid/tap
brew install davidgodefroid/tap/locksql davidgodefroid/tap/lox cosignlocksql runs in Docker: Homebrew installs the locksql launcher, which runs
every command in the release's image. It also takes lockhub's CLI lox
v0.12.0 or later and cosign v2.5.0 or later: lox add and lox run verify
every image with cosign. The whole family instead, lox and cosign included:
brew install davidgodefroid/tap/lockfamily.
Without Homebrew, the install script of a release tag (it verifies the
release's cosign signatures, so it needs cosign v2.5.0 or later on PATH;
install lockhub's lox v0.12.0 or later beside it):
V=vX.Y.Z
curl -fsSLO "https://raw.githubusercontent.com/DavidGodefroid/locksql/$V/scripts/install.sh"
less install.sh
LOCKSQL_VERSION=$V sh install.shLinux and macOS; on Windows, WSL 2 with Docker Desktop. Launcher, image, Vault image, lea and building from source: docs/install.md.
-
In your project, add the database.
lox addasks where it is (never the password), writes the profile, wires your agent and starts the console:lox add locksql
-
In a terminal of its own, outside any agent, keep
lox runopen. Every ticket shows up there:lox run
-
Start your agent in the project (
claude,codex,gemini, …) and ask: "how many orders were placed yesterday?"
lox add wires Claude Code; for Codex, Cursor or Gemini CLI, also run
locksql init codex (or cursor, gemini). With
lea, run lox add in lea's projects
directory, then lea stop and lea. Step by step, by hand:
docs/install.md.
|
🔑 One key holder |
👤 Your rules, your decisions |
|
🕶️ PII masked at the source |
⚖️ Weighed before it runs |
More: OS separation, grants, writes, remote databases, and the console's switches.
Two processes in two containers. Only the console holds the key.
sequenceDiagram
autonumber
participant A as 🤖 AI agent<br/>(locksql mcp / CLI)
participant C as 🔐 locksql console
participant L as 🎫 lockhub (lox run)
participant D as 🗄️ Database
A->>C: plan "SELECT … LIMIT 20"
C->>D: EXPLAIN
C-->>A: plan id + verdict (OK / WARN / REFUSE)
A->>C: run PLAN_ID
C->>L: ticket, every literal masked
C-->>A: pending, ticket T
L-->>C: signed decision (your rule, or you)
A->>C: run T
C->>D: the statement
C-->>A: masked, capped rows (untrusted data)
- The agent plans a statement (
locksql plan, or thelocksql_planMCP tool). The console classifies it, traces every output column, runsEXPLAINand answers with a verdict. - The agent runs the plan. The console sends lockhub a ticket and answers
pending. lox rundecides, on your profile's rules or by asking you. The console checks the signed decision, runs the statement, masks and caps the rows.
Engines: MariaDB 10.11+, MySQL 8.0+, PostgreSQL 13+, SQLite 3, all pure Go, on amd64 and arm64. The approval screen, the process layout and the engines table: docs/architecture.md.
- The console is the enforcement point. Skills, rules and MCP tool descriptions only guide the agent; the console's checks are the guarantee.
- OS separation. The console runs as its own account in its own container; the kernel checks every peer on the socket.
- The AI tightens, the human loosens. Agents may add mask rules; any loosening of the policy waits for your confirmation in the console.
- Audit. Every decision, refusal and run goes to a hash-chained JSONL log, never with secrets or result rows.
- Known limits. Masking is best effort, k-anonymity is a warning (on a
read the default auto rule approves without asking), and
whoever can run
dockercommands can reach the console's container.
Every rule and limit: docs/safety.md. Threat model: docs/security-model.md.
| Doc | What it covers |
|---|---|
| docs/install.md | install paths, the launcher and its image, the first query by hand, building |
| docs/docker.md | what runs where in Docker, Vault, an agent in its own container |
| docs/usage.md | the console, client commands, MCP server, agent wiring, grants, auto mode |
| docs/configuration.md | every profile key, TLS, SSH, PII rule sets, sharing a configuration, the company's managed configuration ([locksql] of lockfamily's managed.toml) |
| docs/console.md | --allow-unmask, console keys, clear results (Ctrl-O) |
| docs/architecture.md | the life of a query, the approval screen, engines |
| docs/safety.md | the safety model and the limitations, in full |
| docs/security-model.md | threat model, mitigations, upstream recommendation |
| docs/pii-analysis.md | how the PII analysis works (for contributors) |
| docs/1.0.md | the 1.0 criteria and the versioning policy |
| CHANGELOG.md | what changed, release by release |
The site, locksql.com, is built from site/.
| Repo | What it does |
|---|---|
| lockfamily | The family site (lockfamily.dev) and the one-line installer. |
| locksql | SQL databases: the agent queries, PII comes back masked; connections and writes wait for you. |
| lockmq | RabbitMQ: masked queue inspection; connections, peeks and unmasked reads wait for you. |
| lockfile | Files (S3, SFTP, disk): the agent asks yes/no questions about files it never reads. |
| lockhttp | Outbound HTTP(S): reads of trusted hosts pass; anything that sends data or reaches an unknown host waits for you. |
| locklog | Logs: masked, bounded log search; the agent reads the logs, not the people in them. |
| lockssh | Commands over SSH: allow-listed commands run at once, the rest waits for you; the key never leaves the console. |
| lockhub | The approval hub and its lox CLI: lox run approves outside the agent's harness and never sees values in clear. |
| lockkit | The shared Go core of every Lock: console, policies, masking, signed tickets, audit, MCP. |
| lea | Runs many agents in containers, wired to the Locks. |
- Contributing: CONTRIBUTING.md. Build with
CGO_ENABLED=0 go build ./cmd/locksql(Go 1.26+). - Security: report a vulnerability privately, see SECURITY.md.
- License: Apache License 2.0, see LICENSE and NOTICE.
