Install

Get gmonk running in ~10 minutes

gmonk is self-hosted — it runs entirely in your own infrastructure against your own database. Below is the fastest path: run the image, protect a database, and reverse a run. Everything uses the published image gmonkdev/gmonk:0.5.0.

The one command

gmonk protects two things — a database and an agent's files & shell — and gmonk setup is the guided wizard that wires up whichever you want (schema, agent hook, and the database-proxy config) in one command.

bash

# 1. in an empty directory, get the compose file and bring up the store + UI
curl -O https://gmonk.dev/docker-compose.yml
docker compose up -d

# 2. make 'gmonk' run through the image
#    (-v lets the wizard install the agent hook onto your host;
#     -e passes your database URL through)
alias gmonk='docker compose run --rm -e APP_DB_URL -v "$HOME/.claude:/root/.claude" gmonk'

# 3. run the wizard — it asks what to protect (database / files & shell / both)
gmonk setup

Or drive it with flags (CI-safe):

bash

gmonk setup --all      --backend-ref APP_DB_URL --auth password   # both
gmonk setup --files    --scope user                              # agent hook only
gmonk setup --database --backend-ref APP_DB_URL --auth password   # database only

For the database, setup configures capture and prints the proxy command — run the proxy as a long-lived service (Step 4 below, or the production guide) rather than in the wizard's foreground. Building gmonk from source instead? Then gmonk is npm run gmonk -- and you can drop the Docker wrapper.

Or set it up step by step

Install Docker

The only prerequisite on the host is Docker. gmonk ships as a self-contained image plus a Postgres database — nothing else to install.

Verify Docker is available:

bash

docker --version

Start the engine + review UI

Pull the published image and bring up the stack: Postgres, a one-shot schema migration, and the review UI on 127.0.0.1:4319 (loopback only).

bash

# in an empty directory, grab the quickstart compose file
curl -O https://gmonk.dev/docker-compose.yml

# bring up Postgres + a one-shot schema migration + the review UI
docker compose up

# to pin or upgrade the version, set GMONK_IMAGE first:
#   GMONK_IMAGE=gmonkdev/gmonk:0.5.0 docker compose up

That one file is all you need — it pulls the published image, so there's nothing to build. The review UI is then at http://127.0.0.1:4319 (loopback only). The annotated version lives in the deployment guide.

Two databases, kept separate. The compose stack runs gmonk's own store. The database you want to protect is a separate one you pass in the next steps — gmonk never installs its tables in your target.

Make the CLI convenient

Every gmonk command runs through the container. Add a shell alias so the rest of the guide reads as plain `gmonk …` commands.

bash

# there's no gmonk binary — run every command through the image.
# -e passes your DB URL through; -v lets hook commands reach your host's Claude Code.
alias gmonk='docker compose run --rm -e APP_DB_URL -v "$HOME/.claude:/root/.claude" gmonk'

gmonk --help

Every gmonk <command> below assumes this alias. (Long-running commands like the proxy need a published port — see Step 4.)

Protect your database

Put your database URL in an env var and run gmonk in front of it with undo capture on. gmonk auto-detects Postgres vs MySQL from the URL scheme.

bash

# your database URL lives in an env var — never passed on the CLI or stored
export APP_DB_URL=postgres://user:pw@db-host:5432/appdb

# the proxy is long-lived and needs its port published to the host, so run it
# explicitly (not via the alias) with -p. It stays in the foreground.
docker compose run --rm -e APP_DB_URL -p 127.0.0.1:6432:6432 \
  gmonk protect --backend-ref APP_DB_URL --listen 6432

MySQL works the same way — a mysql://… backend launches the MySQL wire proxy automatically. For a proxy that runs as a managed background service (not tying up a terminal), use the production compose's protect profile.

Optional hardening

--guarantee — refuse any write gmonk can't prove it can undo (prove-then-commit).
GMONK_PROXY_PASSWORD + --tls-key/--tls-cert — require a password and encrypt the client→gmonk connection.
Backend TLS (gmonk→database) to a remote target is encrypted by default.
gmonk enforce --agent-role <role> — revoke the agent's direct DB access so gmonk is the only way in.

Point your agent at gmonk

Change the agent's connection string from your database to gmonk's listen port. From here every write is captured and reversible.

text

# before — agent talks directly to the database
postgres://agent@db-host:5432/appdb

# after — agent talks to gmonk, which captures & gates every write
postgres://agent@localhost:6432/appdb

Now every UPDATE / DELETE / INSERT is recorded with a before-image, and unrecoverable statements (DROP, TRUNCATE, no-WHERE DELETE) are refused at the wire.

Reverse a run when something goes wrong

Find the run, preview the undo with a live drift check, then apply it. Only safe steps run; drifted steps are skipped; blocked steps wait for a human.

bash

gmonk runs                      # find the session
gmonk reverse-plan <run-id>     # preview — read-only, live drift check
gmonk reverse-run <run-id> --dry-run   # show exactly what an undo would do
gmonk reverse-run <run-id>      # apply — only 'ready' steps run

The same preview-and-apply flow is available as one-click actions in the review UI.

Optional paths

See it end-to-end first

Watch gmonk work against a throwaway table before wiring anything up — capture, the gate, anti-bypass, one-click undo, and the recoverability monitor, all in one run.

bash

gmonk migrate   # once — create gmonk's tables
gmonk demo      # runs the full story, cleans up after itself

Capture an agent's files & commands

The proxy only sees SQL. To capture file edits, shell commands, and tool calls, register gmonk's hook into Claude Code (or use the MCP gateway). Full guide: Capture an agent.

bash

curl -O https://gmonk.dev/docker-compose.yml   # if you don't have it yet
docker compose up -d
docker compose run --rm -v "$HOME/.claude:/root/.claude" \
  gmonk install-hook --scope user
# then restart Claude Code / start a new session

Reverse external effects (charges, SaaS)

Effects like a Stripe charge are undone with a compensating call you define, using the open-source SDK. gmonk never calls a third party on its own.

bash

npm install @gmonk/sdk

Protect a database you can't proxy

For a locked-down managed database (RDS / Cloud SQL) you can't run a proxy in front of, gmonk captures out-of-band via WAL / logical decoding or triggers.

bash

export GMONK_TARGET_URL="…the database to protect…"
gmonk protect-db   # picks WAL or triggers; prints the one change to apply if needed

That's it — your agent now has an undo button.

Read the docs Back to overview

Questions? hello@gmonk.dev