Install locksql

Install script (Linux, macOS)

Downloads the archive for your OS and architecture, checks it against checksums.txt (and the signature when cosign is on PATH), then installs /usr/local/bin/locksql, with sudo if needed:

curl -fsSLO https://raw.githubusercontent.com/DavidGodefroid/locksql/main/scripts/install.sh
less install.sh                     # read it first
sh install.sh                       # LOCKSQL_VERSION=v0.8.0 to pin a version

Or, in one line:

curl -fsSL https://raw.githubusercontent.com/DavidGodefroid/locksql/main/scripts/install.sh | sh

LOCKSQL_INSTALL_DIR=~/.local/bin installs without sudo, but the binary is then owned by your account and locksql doctor warns: in separated mode, the console must run a binary the agent cannot replace (sudo locksql install copies it to /usr/local/bin). To upgrade, run locksql update from your own account: it checks the cosign signature and the checksum of the new release, and asks sudo only for the final copy. locksql console and locksql doctor tell you when a newer release exists (at most one check a day; LOCKSQL_NO_UPDATE_CHECK=1 turns it off).

Read the install script source

Debian, Ubuntu, Fedora, RHEL, Alpine

Packages install /usr/bin/locksql, owned by root. Copy-paste, the latest version and your architecture are detected:

V=$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/DavidGodefroid/locksql/releases/latest); V=${V##*/v}
A=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
U=https://github.com/DavidGodefroid/locksql/releases/download/v$V/locksql_${V}_linux_$A

# Debian, Ubuntu
curl -fsSLO $U.deb && sudo apt install ./locksql_${V}_linux_$A.deb
# Fedora, RHEL
sudo dnf install $U.rpm
# Alpine
curl -fsSLO $U.apk && sudo apk add --allow-untrusted ./locksql_${V}_linux_$A.apk

To upgrade, run the same lines again; to remove, sudo apt remove locksql (or dnf remove, apk del).

By hand, with signature check

Download locksql_<version>_<os>_<arch>.tar.gz, checksums.txt and checksums.txt.sigstore.json from the releases page, then:

cosign verify-blob --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp '^https://github.com/DavidGodefroid/locksql/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt
sha256sum --ignore-missing -c checksums.txt   # macOS: shasum -a 256 --ignore-missing -c checksums.txt
tar -xzf locksql_<version>_<os>_<arch>.tar.gz locksql
sudo install -m 0755 locksql /usr/local/bin/locksql

From source

go install github.com/DavidGodefroid/locksql/cmd/locksql@latest (Go 1.26 or later). To build from a checkout:

CGO_ENABLED=0 go build ./cmd/locksql

Requires Go 1.26 or later. See CONTRIBUTING.md for building and testing.

After installing: set up

One command: locksql setup

From your account (the one your agents run as), in the project:

locksql setup [--project DIR] [--client USER] [--trust-binary] [--yes]

locksql setup --yes --engine sqlite --path demo.db
locksql setup --yes --profile uat --engine postgres --host db.internal --user reporting
locksql setup --yes --profile prod --engine postgres --host db.internal --credentials vault --vault-path database/creds/ro

locksql profile add, with the same profile flags or its questions, adds another profile to the project without the other steps.

The steps below are what setup does, one by one. locksql setup in the usage guide.

Wire your agents

Separate the console from the agent

The console runs only in an account of its own: an agent in the console’s account could read its terminal, type into it and read its keychain session. locksql console refuses to start without this setup. On Linux and macOS, locksql install sets it up once:

locksql install [--client USER] [--user locksql] [--group locksql-clients] [--print] [--trust-binary] [--yes]

Describe your databases

[profiles.uat]
engine      = "mariadb"             # mariadb | mysql | postgres | sqlite
host        = "db.uat.example.com"  # or path = "app.db" for sqlite
port        = 3306                  # default 3306, or 5432 for postgres
user        = ""                    # empty: asked at console start
database    = ""                    # empty: chosen per query (--db)
credentials = "ask"                 # ask | keychain | vault
vault_path  = ""                    # with vault: "database/creds/<role>" or a KV secret
tls         = "verify-full"         # disable | prefer | require | verify-ca | verify-full
tls_ca      = ""                    # optional PEM bundle replacing the system roots
tls_cert    = ""                    # optional client certificate (PEM)
tls_key     = ""                    # its private key (PEM, unencrypted, mode 0600)
tls_server_name = ""                # optional: the name verify-full checks instead of host
credentials_ttl = "20m"             # optional: ask for the secret again
tier        = "read"                # read | write | ddl | admin
production  = false
detectors   = ["email", "phone", "iban", "card", "be_niss"]

[profiles.uat.limits]
statement_timeout   = "30s"
explain_rows_warn   = 100000
explain_rows_refuse = 1000000
max_rows            = 200
max_cell_chars      = 200
max_output_bytes    = 65536
k_anonymity         = 5
explain_cost_refuse = 0             # engine cost units; 0 = off

A remote host defaults to tls = "verify-full": the server certificate must verify, against tls_ca for a private CA; tls_server_name names the certificate’s host when host is an IP address or an alias. tls_cert and tls_key go together, need require or stronger, and present a client certificate when the server asks for one (PostgreSQL clientcert/cert in pg_hba.conf, MySQL REQUIRE X509); keep both files in the console account’s home, the key readable by that account only. On MariaDB and MySQL, a remote host whose certificate is not verified answers no request for the password in clear: connect with verify-ca or verify-full, or use an account with mysql_native_password or ed25519. TLS to the database.

A database reachable only from a bastion gets an ssh table: the console opens the SSH connection itself, with no local listening port, and checks the bastion against the console account’s ~/.ssh/known_hosts, asking on first use and refusing a changed key. host is then the database as seen from the bastion.

[profiles.prod]
engine      = "postgres"
host        = "db.internal"         # as seen from the bastion
tls         = "verify-full"
production  = true

[profiles.prod.ssh]
host        = "bastion.example.com"
user        = "deploy"
auth        = "key"                 # key | agent | password
key         = "~/.ssh/id_ed25519"   # in the console account's home

All profile keys

Check the machine

locksql doctor [--profile P] [--fix [--yes]]

Start the console

In a terminal you keep in view, in the locksql session (switch user on the desktop, or log in on a text console with Ctrl-Alt-F3):

locksql console [--profile dev] [--project DIR] [--auto] [--allow-unmask] [--show-results]

Never in a terminal of your account, where the agents run and could read what you type: run from there, locksql console prints the command for the locksql session instead of starting. When your agents run under an account of their own, locksql console from yours opens the console as locksql through sudo -u, machinectl shell or su -l.

Starting the console, in the usage guide

Docker

docker build -t locksql https://github.com/DavidGodefroid/locksql.git

Mount the project at its own path: the socket name is derived from it, so the console and the agent must see the same one. In the project directory, write the agent files, then add a database profile with the wizard (it asks for no password):

docker run --rm --user "$(id -u):$(id -g)" -e HOME=/tmp \
  -v "$PWD:$PWD" -w "$PWD" locksql init claude
docker run -it --rm --user "$(id -u):$(id -g)" -e HOME=/tmp \
  -v "$PWD:$PWD" -w "$PWD" locksql profile add

docker run -it --rm --name locksql-console --user locksql \
  -v "$PWD:$PWD" \
  -v locksql-run:/run/locksql \
  -v locksql-home:/home/locksql \
  locksql console --project "$PWD"

The locksql-home volume keeps the approved policy, the audit log and known_hosts between runs. The agent starts the MCP server in a throwaway container; for Claude Code:

claude mcp add --scope user locksql -- \
  sh -c 'exec docker run -i --rm -v "$PWD:$PWD" -w "$PWD" -v locksql-run:/run/locksql locksql mcp'

Windows: inside WSL2