Rollcage docs
Everything you need to install Rollcage, point it at your database, and get your data back if something goes wrong.
Setting this up with an AI agent? , or point it at rollcage.dev/llms.txt.
Install
Rollcage is in private testing. Join the waitlist and you'll get one email when it opens.
When it opens, installing takes one line on macOS or Linux:
curl -fsSL https://rollcage.dev/install.sh | sh
It downloads Rollcage for your machine, checks the download against its published
checksum, and puts rollcage in ~/.local/bin. Rollcage also needs the Postgres client
tools (pg_dump, pg_restore, psql), at least as new as your database server:
- macOS:
brew install libpq - Ubuntu/Debian:
sudo apt install postgresql-client
Quick start
In your project folder:
rollcage init
A settings page opens in your browser (rollcage settings opens it again later). On it
you pick:
- Which database to protect. It finds Postgres and MySQL connection strings in your
.envfiles, or you can name an env var or paste a connection string, and test the connection. You can protect more than one. - Where snapshots go. Cloudflare R2, DigitalOcean Spaces, AWS S3 or any S3-compatible bucket (recommended), or a folder on this computer, and how long to keep them (default 7 days).
- Protected folders the agent must ask about before deleting or changing (it
suggests ones it finds, like
uploads/orprisma/migrations/). - Close-call alerts (optional): paste a Slack or Discord webhook and every ask or block shows up in your channel. Rollcage sends a test message when you save.
The page runs on your own computer only (127.0.0.1, behind a random secret link) and
closes when you click Done. Over SSH, or with rollcage init --terminal, the same
questions are asked in the terminal instead. An agent can't open the page: it needs a
person at a real terminal. The same goes for every command that switches protection off
or changes where it reports (settings, uninstall, connect, notify, a second
init). They refuse inside an agent's shell, or when an AI agent's program (claude,
codex, gemini, opencode, cline, ...) started them by any route, expect included.
Then it creates your encryption key, writes rollcage.toml, adds the hook to
.claude/settings.json (merged with anything already there), adds hooks for Cursor
(.cursor/hooks.json) and Codex (.codex/hooks.json) too if they're on your computer,
and runs rollcage doctor to check everything works.
Back up the key it shows you (a password manager is a good place). Snapshots can't be restored without it.
Now start Claude Code from the same folder (or open the folder in Cursor or Codex):
claude
That's it. Ask it to drop a table on production and Rollcage steps in.
Commands
| Command | What it does |
|---|---|
rollcage init |
One-time setup in your project folder, on a settings page in your browser (--terminal for prompts). Your key is kept if you run it again. |
rollcage settings |
Change what's protected, on the same settings page. |
rollcage status [--json] |
What's protected, where snapshots go, the latest snapshot (and whether it was checked), which agents are hooked in, and the dashboard and alerts. --json prints it all for scripts (what the dashboard would get: never connection strings or keys). |
rollcage doctor |
Checks the Postgres or MySQL tools (and that pg_dump is new enough for your server), the database connection (and, for Postgres, that its role can make the schema copy-back uses, and whether rows a copy-back set aside are still waiting there), the storage bucket, the hook and the key. Every problem comes with a fix. Calls each installed hook with a harmless test call to make sure it answers. |
rollcage snapshot [--db NAME] [--note "..."] |
Take a snapshot now (of every protected database, or just one). |
rollcage list [--db NAME] [--json] |
Your snapshots: id, database, time, size, and why each was taken. |
rollcage list <id> |
One snapshot (or latest): its details and the tables in it, read back from the snapshot itself (which also proves it restores). |
rollcage undo |
After a command went wrong: shows the latest close call and the snapshot Rollcage took before it, finds the tables it took (dropped, emptied, shrunk or changed since), and restores them into a new database (asks first in a terminal; --yes, --into NAME, --dry-run, --all for tables the command didn't name). Then prints the rollcage copy-back command that puts them back. Also rollcage recover. Nothing is overwritten. |
rollcage uninstall |
Takes Rollcage's hooks out of this project's agents, leaving their other hooks as they were (each file it changes is saved next to it first). --global also takes out the ones in your home folder that serve every project (Gemini's for subfolders, Antigravity's, opencode's and Amp's plugins). Your settings, encryption key and snapshots are kept: the key is the only way to restore old snapshots. The home-folder hooks keep checking this project while its rollcage.toml is here. A Cline hook other projects in the repository use is kept. A person runs it, in a terminal. |
rollcage copy-back <file> |
Put restored rows back into production, from the file undo or restore --table wrote. Shows what it does, asks you to type the database's name (in a real terminal; an agent can't), snapshots the database first, and runs in one transaction. Without a file, it runs the one waiting for this project, or lists them when there are several (so does status). --preview runs it and rolls it back, to show exactly what it would do. |
rollcage diff [id] [--json] |
What changed in the database since a snapshot (default: the newest): tables dropped, emptied, shrunk, grown or new, from row counts recorded with the snapshot. Prints the rollcage restore ... --table line that brings the lost ones back. Only reads the database. |
rollcage restore latest |
The same, for the newest snapshot (it says which one it picked). latest works wherever an id does in restore. |
rollcage restore <id> |
Restore a snapshot into a new database, so nothing is overwritten. Asks for a name (or pass --into NAME, or --target-url postgres://...). A SQLite snapshot goes into a new file next to the original. |
rollcage restore <id> --table orders |
Just that table's rows (repeat --table for more), with its keys, indexes, sequences, row-level security and partitions, into a new database (the other tables come back empty). Rollcage writes the file that copies it back into production and prints the rollcage copy-back command that runs it (see "Getting tables back" below), and any foreign keys to add back. --alongside <table> puts the snapshot's rows next to the table instead, to compare. |
rollcage restore <id> --in-place |
Overwrite the original database. You have to type its name to confirm, in a real terminal (an agent can't do it), and Rollcage snapshots the current state first. |
rollcage verify [id] [--all] |
Prove snapshots can be restored: each is downloaded, decrypted with your key and read back with pg_restore, touching no database. Default: the newest snapshot of each database. |
rollcage log [-n 30] [--since 2h] [--json] |
Everything Rollcage allowed, asked about, warned about or blocked. --agent cursor shows one agent's, --decision blocked one outcome's (allowed, warned, asked, blocked). -f keeps going, printing each new decision as it happens. |
rollcage rules |
The detection rules that are switched on. |
rollcage explain '<command>' [--json] |
What Rollcage would do if your agent ran that command, and why: which rules match, which database, whether it snapshots first. A command that reaches into another Rollcage project (cd ../api && ...) is checked under that one too, as the hook does, and says so. Nothing is run and no snapshot is taken. Handy when an ask surprises you or you're writing a rule. |
rollcage connect [--server URL] |
Optional: link this project to your Rollcage dashboard. Shows a code, you approve it in the browser. Metadata only (see The dashboard). |
rollcage sync |
Send the dashboard an update now. Once connected, Rollcage does this by itself after anything it catches. |
rollcage disconnect |
Stop sending updates and cancel this computer's token. |
rollcage notify <webhook url> |
Optional: post close calls to Slack, Discord or any webhook (--test, --off). See Close-call alerts. |
rollcage check |
The hook itself. Each agent runs it (opencode through its plugin); you don't. |
Example:
$ rollcage list
ID DATABASE TAKEN SIZE REASON
rc_20261116_2201 production Nov 16 22:01 (1 minute ago) 2.0 KB before DROP TABLE users (Claude Code)
$ rollcage log
Nov 16 22:01 ASKED DROP TABLE users on production
set -a; source .env; set +a; psql "$DATABASE_URL" -c "DROP TABLE users"
snapshot: rc_20261116_2201
How detection works
Before every Bash command, file read or edit, and MCP tool call, Claude Code sends the call to
rollcage check. Cursor does the same for shell commands, MCP calls, file reads, and file
writes and deletes (Cursor), and Codex for shell commands, apply_patch edits
and MCP tools (Codex). Rollcage parses it (no network, about 4 ms) and sorts it into one of
these outcomes:
| What Rollcage finds | What happens |
|---|---|
| Nothing risky | Nothing. Your agent's normal permissions apply. Not logged. |
| Destructive, but not aimed at a protected database (your local dev DB, say) | Allowed and logged. |
| Destructive and aimed at a protected database | Snapshot first, then ask you. If the snapshot fails, the command is blocked and you're told why. A destructive production command never runs without a snapshot. |
A lighter risk (rm -rf src, force-pushing main, git reset --hard with uncommitted work) |
Allowed, logged, and a heads-up is shown. |
Something that would switch Rollcage off or get around it (editing rollcage.toml, the hooks or the activity log, reading or deleting the encryption key or storage credentials, deleting snapshots, opening the settings, connecting the dashboard or changing alerts, even through another program; starting another agent with its hooks off, such as claude --bare, --safe-mode, --settings or --plugin-dir; installing a plugin, whose hooks or mods could approve what Rollcage blocks), or rm -rf ~ |
Ask you first (in agents that can't ask, such as Codex and Cursor, blocked instead). |
What counts as destructive
SQL, wherever it appears: psql -c, .sql files passed with -f or < (and files
they pull in with psql's \i), heredocs,
echo ... | psql, supabase db query, prisma db execute, raw queries inside
node -e/python -c/bun/deno/tsx one-liners and the script files they run, curl
bodies sent to database APIs, and MCP tools like Supabase's execute_sql or a Postgres
MCP's query:
DROP TABLE,DROP SCHEMA,DROP DATABASE,DROP OWNED BY(everything a role owns),DROP EXTENSION|TYPE|DOMAIN ... CASCADE(drops every column that uses it)TRUNCATEDELETEwithout aWHERE(or withWHERE 1=1/WHERE true)UPDATEwithout aWHEREALTER TABLE ... DROP COLUMN
It reads SQL properly: comments are ignored (-- DROP TABLE users is fine), case doesn't
matter, and it looks inside WITH ... AS (DELETE ...), EXPLAIN ANALYZE, DO $$ ... $$
blocks, functions created and called in the same SQL, dynamic SQL (EXECUTE format('DROP
TABLE %I', ...), a variable holding it, 'DR' || 'OP ...', chr(68), decode(...,
'base64'), psql's \gexec), PREPARE ... AS, MERGE ... DELETE, dblink_exec, and
psql -c "$(cat file.sql)". echo, printf and $'...' are decoded the way the shell
prints them (echo -e '\x44ROP ...'). A file written earlier in the same command is read
as it will be by then (cat > x.sh <<'EOF' ... EOF && bash x.sh, echo ... > seed.sql &&
psql -f seed.sql). SQL it can't see on production asks: psql -c "$QUERY", a file that
doesn't exist yet, was just downloaded or was changed in place (sed -i), or SQL piped in
from a program that changes it (rev, base64 -d, sed). So does running a SQL file
already on disk there (psql -f seed.sql, mysql shop < seed.sql), whatever it says
now: another of the agent's calls running at the same time could change it before it
runs. (Destructive SQL in it still gets a snapshot first.) So does opening an SSH tunnel to
a protected database (ssh -L 6543:db-host:5432 ...): commands sent through it later look
local.
ORM calls that wipe tables, in one-liners, scripts, rails runner, manage.py shell
and artisan tinker: Prisma deleteMany() with no filter, Rails Model.delete_all,
Django .objects.all().delete(), SQLAlchemy metadata.drop_all, Knex .del()/.truncate(),
Laravel DB::table(...)->truncate() and Schema::drop, TypeORM .clear(), Sequelize
sync({ force: true }) and destroy({ where: {} }), Drizzle db.delete(table) and
SQLAlchemy delete(Model) with no .where. Code piped into rails console or tinker
counts too.
Database CLIs and APIs: supabase db reset (remote only), supabase projects delete,
prisma migrate reset, prisma db push --force-reset / --accept-data-loss,
drizzle-kit push, dropdb, pg_restore --clean, Railway volume/service/environment/project
deletes (CLI and GraphQL API), Neon project/branch/database deletes and branch resets (CLI
and API), and the Supabase Management API's project delete. MCP tools named like
delete_project, reset_branch or volume_delete on database servers count too.
Docker volumes: docker compose down -v, docker rm -v, docker volume rm/prune
and docker system prune --volumes delete the volume a database running in Docker keeps its data
in, so they count as aimed at production when a protected database runs on the same
machine (localhost, or a Compose service name like db).
Framework and migration tools that drop, wipe or roll back a database: Rails
(db:drop, db:reset, db:schema:load, db:rollback and friends), Django (flush,
reset_db, migrate <app> zero), Laravel (migrate:fresh, migrate:reset,
migrate:rollback, db:wipe), Ecto, Sequelize, TypeORM, MikroORM, Knex, Payload,
Alembic, Flask-Migrate, Flyway, Liquibase, Atlas, dbmate, goose, sqlx, Diesel, and
heroku pg:reset. They're found behind bundle exec, uv run, poetry run,
python manage.py, python -m django and php artisan, and they count as production
when the environment or .env they'd read points at a protected database.
Migrations about to run: commands that apply migrations (prisma migrate deploy,
rails db:migrate, supabase db push, alembic upgrade, php artisan migrate,
manage.py migrate, knex migrate:latest, drizzle-kit migrate, Flyway, goose, sqlx,
Diesel and more) look harmless, but they run whatever the migration files say, and an
agent can write a migration that drops a table and then deploy it. Rollcage reads the
migrations changed in the last 7 days, skips their rollback half (def down,
downgrade(), -- migrate:down), turns ORM operations like drop_table :users,
op.drop_column(...) or $table->dropColumn(...) into SQL, and treats anything
destructive in them like the same SQL typed directly: on production, snapshot first,
then ask, naming the migration file.
Shell tricks don't hide anything: chains (&&, ;, ||, |), subshells, $(...)
and backticks, heredocs and here-strings, quoting and escapes, $VAR and ${VAR:-default}
expansion, export/source .env, cd, and wrappers like sudo, env, time, npx,
bunx, npm run <script> (it reads package.json), bash -c, sh script.sh, eval,
ssh host "...", docker exec, kubectl exec, railway run, doppler run,
dotenv -e, script (pseudo-terminals), env -S, timeout, flock, setsid,
cross-env, mise exec, direnv exec, pipenv run, conda run, nix develop -c,
GNU parallel, and a program name hidden as $(echo npx). Scripts are followed too:
./script.sh, source script.sh, bash < file, bash -c "$(cat file)", source <(cat
file), make and just recipes, npm --prefix/pnpm --filter/yarn workspace/turbo
run scripts, find ... -exec, node node_modules/.bin/<tool>, and code that shells out
(os.system(...), subprocess.run([...]), execSync(...), Ruby and Perl system and
backticks), inline or in the script file it runs. A .env.production
named anywhere in a command counts as loaded, and commands over ssh or fly ssh count
as aimed at production.
It follows the shell the way it would run: shell functions defined in a command are
checked where they're called, with their arguments (q() { psql ... -c "$1"; }; q 'DROP
...'); for loops value by value (for t in users orders; do ...); positional
parameters (bash -c '...' _ args, set --); writes that might not happen (after ||,
inside if) don't hide the file on disk; and dry runs (make -n, just --show, bash -n,
migrate --plan) run nothing. More wrappers and runners: tmux and screen (including
send-keys), strace, gdb --args, taskset, aws-vault exec, envchain, sops
exec-env, runuser/su -c, watch, watchexec, entr, hyperfine, concurrently,
npm-run-all/run-s, and every package at once (pnpm -r, npm --workspaces, yarn
workspaces foreach, lerna run/exec, nx run-many).
Cloud and infrastructure deletes always count as aimed at production (a cloud name
can't be matched to a host): aws rds delete-db-*, gcloud sql ... delete, doctl
databases delete, az postgres ... delete, fly apps|volumes destroy, terraform
destroy / apply -destroy, pulumi destroy, cdk destroy, sst remove, serverless
remove, aws cloudformation delete-stack, kubectl delete pvc|pv|namespace and Postgres
operator clusters, terragrunt destroy, terraform apply -replace, fly mpg destroy,
az group delete, Vercel database deletes. helm uninstall asks.
Files and other databases: Rollcage snapshots Postgres and MySQL, so deleting stored
files (aws s3 rm --recursive, Vercel Blob, Supabase Storage, Railway buckets), a database
it can't snapshot (DynamoDB, Firestore, Cosmos DB, Turso, D1, MongoDB), or a whole
database through a provider's CLI (pscale database delete) asks first, with no snapshot. redis-cli FLUSHALL gets a heads-up. Seed commands (prisma db seed,
rails db:seed, knex seed:run, ...) ask on production, since seeds usually clear tables
first.
Interactive sessions on production: psql "$DATABASE_URL" with no command opens a
session that anything can be typed into later, out of Rollcage's sight (some agents, like
Codex, can keep a terminal open and write to it). So that asks first; one-off queries
with -c or -f are checked as usual.
What "aimed at production" means
At setup Rollcage records how to recognize each protected database, without storing anything secret: its hosts, port, database name, provider project refs (like a Supabase ref) and the env vars that point at it. A command is aimed at production when it:
- mentions one of those hosts or refs, or contains a connection string for that database
(
postgres://[email protected]/...,psql -h ... -p ... -d ...,PGHOST=...); - references one of its env vars (
psql "$DATABASE_URL"); - builds its connection when it runs (
psql "$(grep DATABASE_URL .env | cut -d= -f2-)",DATABASE_URL=$(cat url.txt) npx prisma migrate reset): that could be anything, so it's treated as production; or - is a tool that reads env vars and
.envfiles by itself (Prisma, Drizzle, a Node or Python script) and those currently point at the protected database.
Local databases need the host, port and database name to match, so your dev database on
localhost:5432 is never confused with a protected one on localhost:55432. The
Supabase CLI works on your local stack unless you pass --linked/--remote/--db-url,
and Rollcage respects that. When it can't tell (a secret injector like railway run, or
an MCP server it can't trace), it assumes production. DECISIONS.md has the
details.
Protected folders
Some files can't be rebuilt from git: user uploads, generated migrations, a CSV of
customers. List them in rollcage.toml (or on the settings page) and the agent has to
ask before deleting, moving or changing anything in them:
[detection]
protected_paths = ["uploads", "prisma/migrations", "data/customers.csv"]
That covers rm, mv, cp over or into them, find ... -delete, git clean, git rm,
git checkout -- <path>, git stash --all, sed -i, truncate, > file redirects,
globs and braces (rm uploads/*, rm data/customers.{csv,bak}), and Claude Code's own
Write and Edit tools, including through cd, sudo and bash -c. Reading them is fine.
Paths are relative to the project folder. The rule is called protected-paths, so
disable_rules = ["protected-paths"] turns it off.
Your own rules
Add rules to rollcage.toml. They use the same format as the
built-in rules:
[[rule]]
name = "nuke-script"
command = "npm run nuke" # commands starting with these words
level = "database" # snapshot + ask when aimed at production
what = "run the nuke script"
[[rule]]
name = "sessions-cleanup-is-fine"
sql = '(?i)^TRUNCATE\s+(TABLE\s+)?sessions\b' # checked against each SQL statement
level = "allow" # silence a false alarm
[[rule]]
name = "no-deploys-without-me"
regex = '^fly deploy' # checked against the whole command
level = "ask"
[detection]
disable_rules = ["git-force-push-main"] # turn off a built-in rule
safe_delete_dirs = ["generated"] # more folders that are fine to rm -rf
protected_paths = ["uploads"] # ask before anything deletes or changes these
Levels: database (snapshot + ask on production, log elsewhere), ask, warn, block
(never allowed), allow. An allow covers only what it matches: a regex allow covers
a command when its match starts at that command's program (after runners like npx or
sudo) and stays inside it, so ^npm run build doesn't cover a psql chained after the
build; a sql allow judges each table of a statement on its own (TRUNCATE sessions,
users still asks); and no allow switches off Rollcage's self-protection. Matchers: command ("a|b" means either word; flags in between
are skipped; a trailing * matches any word that starts with the rest, like db:drop:*),
flags_any (also with a trailing *, like VERSION=*), regex, sql, mcp_tool. target controls how "aimed at
production" is decided (auto, args, pg, supabase, railway, neon, local,
always).
To try a rule before you add it, use the playground:
it runs this engine in your browser against a sample project whose rollcage.toml you
can edit.
Snapshots
pg_dump --format=custom, compressed with zstd, then encrypted on your machine with age before it goes anywhere.- Stored as
<id>.rcsnapplus<id>.json(details like time, size and the redacted command that triggered it) in your bucket or folder. - Kept for
retention_days(default 7). Older ones are deleted after each new snapshot, but the newest snapshot of each database is always kept. -
The key is a standard age key file, so you can decrypt a snapshot without Rollcage:
age -d -i ~/.config/rollcage/keys/<project>.txt rc_x.rcsnap | zstd -d > dump.pgc && pg_restore -d <url> dump.pgc. -
rollcage verifychecks that a snapshot really comes back: it downloads it, decrypts it, and reads it with the samepg_restorea restore would use, without connecting to any database.rollcage statusand the dashboard show when each was last checked.
Big databases (experimental). Before a destructive command, the agent waits while the
snapshot is taken, and a full dump of a large database can take minutes (past
timeout_secs, the command is blocked). With scope = "tables" under [snapshots] (or
the checkbox in rollcage settings), a plain command on named tables (TRUNCATE
sessions, DROP TABLE old_orders, DELETE FROM users with no WHERE, ALTER TABLE users
DROP COLUMN phone) gets a snapshot with the whole schema but the rows of just those
tables, plus the tables their foreign keys would change. Anything with an expression in it
(a WHERE clause, a SELECT, a function), anything else in the same call, CASCADE, SET,
triggers, rules, row-level security, checks that call functions, event triggers, or a
command that doesn't name its tables (prisma migrate reset, a migration) gets a full
snapshot. These snapshots restore into a new database (the other tables come back
empty), never over your database. rollcage list and the dashboard mark them. The
default is scope = "full".
Tip: turn on object versioning or a retention lock for your bucket in your provider's dashboard. Then even someone holding the bucket keys can't erase old snapshots.
Getting tables back
What it looks like after an agent ran TRUNCATE users, orders RESTART IDENTITY and a
new user signed up before anyone noticed:
$ rollcage undo
The last close call: Claude Code tried to run this 6 minutes ago:
psql "$DATABASE_URL" -c "TRUNCATE users, orders RESTART IDENTITY"
Rollcage snapshotted production first: rc_20261119_0134.
users 2 rows -> 1 (-1)
orders 3 rows -> 1 (-2)
Restore them now? yes
...
To put them back into production, run this in your project folder:
rollcage copy-back rc_20261119_0134-20261119-013421.sql
$ rollcage copy-back rc_20261119_0134-20261119-013421.sql
Type the database name (production) to go ahead: production
✓ Saved the current state first: rc_20261119_0141
✓ users: 1 of the snapshot's 2 rows put back, 0 still there; 1 kept in
rollcage_recovery.users_kept_20261119_0134 (their key belongs to a different row now)
✓ orders: 1 of the snapshot's 3 rows put back; 2 kept in
rollcage_recovery.orders_kept_20261119_0134 (... or their parent row was kept aside)
The new user kept id 1; the old user who had id 1 (and that user's orders) wait in
rollcage_recovery to be given new ids by hand, instead of being merged into someone
else's account.
rollcage undo (after a command went wrong) and rollcage restore <id> --table ...
restore tables into a new database, then write a copy-back file into Rollcage's private
folder and print the one command that runs it:
rollcage copy-back ~/.config/rollcage/copy-back/rc_x.sql
copy-back uses the connection Rollcage has for that database (rollcage.toml and .env,
not whatever your shell has), shows what the file does, needs you to type the database's
name in a real terminal (an agent can't), and snapshots the database first.
rollcage copy-back --preview <file> runs it inside a transaction that's rolled back and
prints what it would do now (rows put back, kept aside, tables made again), changing
nothing. It holds the same locks while it runs. The file
checks it's in the database it was written for (its name, and the ids of the database
and its tables) and runs in one transaction: if anything fails, nothing is changed.
- Rows from the snapshot travel only as COPY data, as Postgres writes it, so nothing in a row can be run as SQL.
undorestores what the command took: the tables it named, and any table dropped, emptied or missing a column. Rows that went down or changed elsewhere (usually your app's own work: a revoked session, a sign-up) are listed, not put back;undo --allincludes them.- A table that's still there (emptied, or rows deleted) gets the missing rows back. Rows
still there are left as they are, and id counters only move forward. A row whose key
(or another unique value) belongs to a different row now (ids used again after
TRUNCATE ... RESTART IDENTITY) is kept aside inrollcage_recovery, never merged. - A table that's gone comes back whole, with its keys, indexes, triggers, policies, and exactly the snapshot's permissions (sequences too; grants from default privileges are taken off). A partition that's gone comes back attached to its table. Foreign keys from other tables that went with it are printed, to add back after a look.
- Left out, and named: tables without a usable key (a primary key, or a unique key on columns that can't be empty), and tables whose columns changed in production since.
- Production's INSERT triggers on those tables run for each row put back; they're named.
- A table whose rows were changed in place (an
UPDATEwith noWHERE) isn't changed: the snapshot's rows go intorollcage_recovery.<table>_before_<snapshot>, with the snapshot's columns, to compare and fix (restore --alongside <table>does the same by hand). - Rows whose parent row was kept aside (by a foreign key, through any chain or loop of tables) are kept aside with it, so nothing ends up under someone else's row. Rows put back that point at a table that isn't put back get a warning: if its ids were used again, check them.
- The file waits at most 10 seconds for a lock on a live table, then stops with nothing changed (a busy table): run it again when it's quieter. The steps that take strong locks on live tables run last, so they're held only for the end of the run.
- The
rollcage_recoveryschema and its tables are closed to everyone but their owner: no grants, row-level security on. Drop them once you're done (rollcage doctorreminds you they're there).
rollcage diff shows what changed first, from the row counts recorded with each snapshot
(tables dropped, emptied, shrunk, renamed, or with a column gone), and a checksum of each
table under 100,000 rows (rows changed in place, same count). Tables a close call names
are counted exactly, however big.
MySQL
Set up the same way: rollcage init finds a mysql:// connection string and writes
engine = "mysql" for that database. Tested with MySQL 8.4 and MariaDB 11.4 (MySQL's
or MariaDB's own client tools both work).
- Snapshots are
mysqldump --single-transactionSQL, compressed and encrypted like Postgres ones. By hand:age -d -i <key> rc_x.rcsnap | zstd -d | mysql <database>. - The hook reads the
mysqlclient's options (-h,-P,-Dor the database name,MYSQL_HOST) and MySQL URLs, somysql -h db.example.com shop -e 'DROP TABLE users'aimed at a protected database gets a snapshot first, andmysqladmin drop shoptoo. rollcage restoregoes into a new database by default. If the database user can't create databases (common on hosted MySQL), create an empty one and use--target-url.--table ordersrestores one table;--in-placeworks as it does for Postgres.- If the database user can't read stored procedures, or can't create triggers when restoring, those are left out and each one is named. Tables and rows still come back.
- Getting tables back works as for Postgres (
rollcage undo,restore --table, thenrollcage copy-back <file>). The file sets its own session (strict mode, foreign keys checked, the escaping mysqldump expects, whatever production'ssql_modeis), checks the database and the server's UUID, and puts every row back in one transaction, parents before children: a value too long or a missing parent row stops it with no row changed. Rows still there are skipped byte for byte; rows whose key now belongs to a different row go intorollcage_<table>_kept_<snapshot>; nothing is updated, so no UPDATE trigger runs. MySQL commits each CREATE TABLE, so the tables it needs are made first (they stay, empty, if it stops). Tables that are gone come back whole, their triggers after their rows. Rows changed in place go intorollcage_<table>_before_<snapshot>, next to the table (MySQL has no schemas inside a database). Works on servers with GTID on (Cloud SQL, RDS). - Big-database table snapshots (
scope = "tables") are Postgres only; MySQL snapshots are always full.
SQLite
A SQLite database is a file in your project: Rails 8 apps, Django's db.sqlite3,
Prisma's file:./dev.db. rollcage init finds those files and asks which to protect,
writing engine = "sqlite" and the file's path (or url_env for one named by a
file: URL in .env):
[[database]]
name = "production"
engine = "sqlite"
path = "storage/production.sqlite3"
- Snapshots use SQLite's online backup (
sqlite3's.backup). The copy is consistent even while your app writes to the database. It's compressed and encrypted like the others. It needs thesqlite3tool, which macOS has; on Linux,apt install sqlite3. - The hook takes a snapshot, then asks, before:
sqlite3 <file>SQL that changes data, and its.restore,.backuponto the file, and.shell.- Deleting, moving, emptying or copying over the file, or its
-waland-journalfiles (rm,mv,cp,>,git clean, an agent's own file tools). - App commands that reset it: Prisma by its
file:URL; Rails in the environment whoseconfig/database.ymlsection names the file (RAILS_ENV, development by default); Django. - An interactive
sqlite3session, or a SQL file run on it (.read,< file), asks as it does for psql.
rollcage restore <id>writes the snapshot to a new file next to the original (production-restored-<id>.sqlite3). Your live database isn't touched.--into <file>picks the name.--table ordersrestores the whole file and prints the SQL that copies those tables back: missing rows come back and rows that are there stay.--in-placereplaces the live database with SQLite's own restore (an app that has it open sees one clean change), after a snapshot of what's there now.
verifyhas SQLite check every page of the snapshot.diffandundocompare the tables and row counts now with the snapshot's, as for the other engines.
Configuration
rollcage.toml lives in your project and is safe to commit: it never contains a password,
key or connection string.
[project]
id = "my-app-7f3k2a"
name = "my-app"
[[database]]
name = "production"
provider = "supabase"
url_env = "DATABASE_URL" # where the connection string comes from
env_file = ".env" # read from here if it isn't set in your shell
hosts = ["db.abcdefghijklmnopqrst.supabase.co"]
port = 5432
dbname = "postgres"
project_refs = ["abcdefghijklmnopqrst"]
env_vars = ["DIRECT_URL"] # other env vars that point at the same database
mcp_servers = ["supabase"] # MCP servers (from .mcp.json) that talk to it
# engine = "mysql" # for a MySQL database (Postgres when left out)
[storage]
type = "s3" # or: type = "local", path = "~/rollcage-snapshots/my-app"
endpoint = "https://<account>.r2.cloudflarestorage.com"
bucket = "my-snapshots"
region = "auto"
prefix = "my-app-7f3k2a"
# access_key_env / secret_key_env: env vars with the keys. Otherwise they're read from
# ~/.config/rollcage/secrets/<project id>.toml, which `rollcage init` writes.
# type = "none": no place for snapshots yet (trying Rollcage out). With a database listed,
# a destructive command on it is then blocked: one never runs without a snapshot.
[encryption]
recipient = "age1..." # public key: can encrypt, can't decrypt
key_file = "~/.config/rollcage/keys/my-app-7f3k2a.txt"
[snapshots]
retention_days = 7
timeout_secs = 540 # the hook gives up (and blocks) after this
scope = "full" # or "tables": see "Big databases" under Snapshots
[postgres]
bin_dir = "/opt/homebrew/opt/postgresql@17/bin" # optional: which pg_dump to use
[mysql]
bin_dir = "/opt/homebrew/opt/mysql-client/bin" # optional: which mysqldump to use
Where things live
| What | Where |
|---|---|
| Settings | rollcage.toml (project, commit it) |
| Hooks | .claude/settings.json, plus .cursor/hooks.json and .codex/hooks.json when you use those (project). Each previous version is saved next to it as *.rollcage-backup. |
| Activity log | .rollcage/activity.jsonl (project, git-ignored; at 10 MB it moves to activity.1.jsonl and a new one starts), and .rollcage/verified.json from rollcage verify |
| Encryption key | ~/.config/rollcage/keys/<project id>.txt (0600). Back it up. |
| Pasted connection strings, storage keys | ~/.config/rollcage/secrets/<project id>.toml (0600) |
Dashboard connection (only if you ran rollcage connect) |
~/.config/rollcage/secrets/<project id>.dashboard.toml (0600) |
Alert webhook (only if you ran rollcage notify) |
~/.config/rollcage/secrets/<project id>.notify.toml (0600) |
| Snapshots | Your bucket, or the folder you chose |
Set ROLLCAGE_CONFIG_DIR to use a different folder than ~/.config/rollcage.
The dashboard (optional)
Rollcage works entirely on your computer. If you'd also like to see what it caught and every snapshot it took in a browser (and on your phone), connect the project to the web dashboard:
rollcage connect
It prints a short code and opens the dashboard. Sign in, check the code matches, and
click Connect. From then on, after anything it logs and after rollcage snapshot,
Rollcage sends an update in the background. The hook never waits for it, and safe
commands never send anything.
What's sent: database names, providers and hostnames, the env var names they come from, a one-line description of where snapshots are stored, protected folders and switched-off rules, the activity log (commands are redacted before they're logged, and again before they're sent), snapshot ids, sizes and reasons, the names and row counts of the tables in the newest 30 snapshots (60 tables each), copy-back files waiting to be run (their database, snapshot, date and what they'll put back, by table name), and this computer's name and Rollcage version. Never connection strings or passwords, storage keys, your encryption key, or anything inside a snapshot. The dashboard never connects to your database; restores are shown as commands to run on your computer.
The token connect saves can only send updates for that one project; it can't read
anything back. Remove the project on the dashboard (or run rollcage disconnect) to
cancel it. rollcage connect needs a person at a terminal, and agents are asked before
running connect or disconnect, so an agent can't quietly send your activity somewhere
else. Self-hosting the dashboard: rollcage connect --server https://your-host (or set
ROLLCAGE_DASHBOARD_URL); plain http:// is only accepted for this computer and private
network addresses.
Close-call alerts
Get a message in Slack or Discord whenever Rollcage asks about or blocks something:
rollcage notify https://hooks.slack.com/services/... # or a Discord webhook URL
It sends a test message first, then, after each close call, a line like "Rollcage blocked Codex in shop: it tried to DELETE every row from orders on production. Snapshot saved: rc_20261117_2245", with the command (passwords hidden) and a dashboard link if the project is connected. Heads-ups and allowed commands aren't sent. At most five messages go out at once; anything beyond that is summed up.
The webhook URL works like a password, so it's kept in
~/.config/rollcage/secrets/<project id>.notify.toml, not in rollcage.toml. Setting it
or turning it off (rollcage notify --off) needs a person at a terminal, and agents are
asked before running rollcage notify. Any HTTPS endpoint that accepts JSON works:
it gets {"text": "..."}.
Answering close calls from the dashboard
Codex, Devin, Cline, opencode and Droid can't stop and ask you a question, Cursor doesn't
reliably show one, and neither can Gemini CLI or Qwen Code run headless, agy
--dangerously-skip-permissions or Claude Code with permissions bypassed, so Rollcage
blocks their close calls. If you're away from the computer, you can
answer them from the dashboard (on your phone, say) instead:
[approvals]
dashboard = true # or tick it on `rollcage settings`
wait_secs = 300 # how long to wait for an answer (30 to 1800)
The project has to be connected (rollcage connect) to a dashboard on another server, over
https (a dashboard on your own computer or local network can't answer: anything running
there could pretend to be it). Then, for a destructive command on a protected database,
Rollcage takes the snapshot as always, puts the close call on the dashboard (and in your
Slack or Discord alerts, with a link), and holds the agent while it waits. Approve
(with your password) and the command runs; Deny, or don't answer in time, and it's
blocked. The wait ends before the time limit the agent gives the hook.
Only the database close call is ever held. If the same command also does something else Rollcage would ask about (touching Rollcage's own files, opening an interactive database session), or it's too long to show in full, it's blocked as before. And if what the command would do changes while it waits (a SQL file it runs was edited), it's blocked even after you approve. Agents that can ask you themselves (Claude Code, Copilot, Gemini CLI, Antigravity, Qwen Code) keep asking there.
Only you can answer: signed in to the dashboard, and with your password to approve (the sign-in cookie alone sits in the browser's files on your computer). The project's token can create a request and read the answer to its own requests, nothing else, and it's kept where agents can't read it.
The other agents
Rollcage protects every agent with the same rules and snapshots. These are the differences that come from the agents themselves.
| Agent | Hook file (rollcage init writes it) |
Close calls | Once, by you |
|---|---|---|---|
| Claude Code | .claude/settings.json |
asks you | start claude from the project folder |
| Cursor | .cursor/hooks.json |
blocks (or a dashboard approval): Cursor can run a command its hook asked about | |
| Codex | .codex/hooks.json |
blocks (or a dashboard approval) | trust the hook in Codex's /hooks |
| Copilot (CLI, VS Code) | .github/hooks/rollcage.json |
asks you (blocks in autopilot) | commit the file |
| Devin (Windsurf) | .devin/hooks.v1.json |
blocks (or a dashboard approval) | trust the workspace (no hooks in Restricted Mode) |
| Gemini CLI (retired for most accounts: see Antigravity) | .gemini/settings.json, plus ~/.gemini/settings.json for subfolders |
asks you (blocks when headless, and for MCP tools) | trust the folder |
| Cline (CLI 3.x) | .clinerules/hooks/PreToolUse |
stops the run (or a dashboard approval) | run it inside the project's git repository |
Antigravity (the app, its IDE and the agy CLI) |
~/.gemini/config/hooks.json (yours, used only in Rollcage projects) |
asks you, even for calls you set to "Always allow" (blocks under agy --dangerously-skip-permissions, or a dashboard approval) |
|
| opencode | ~/.config/opencode/plugin/rollcage.js (yours, used only in Rollcage projects) |
blocks (or a dashboard approval) | |
| Amp | ~/.config/amp/plugins/rollcage.ts (yours, used only in Rollcage projects) |
asks you (blocks in amp -x) |
check amp plugins list shows it |
| Droid (Factory) | .factory/hooks.json at the top of the git repository |
blocks (or a dashboard approval) | trust the folder |
| Qwen Code | .qwen/settings.json |
asks you (blocks when headless) | approve the hook once |
rollcage doctor calls each installed hook with a harmless test call to make sure it
answers, and rollcage settings shows which agents are protected.
The hooks in your home folder (Gemini's for subfolders, Antigravity's, opencode's, Amp's):
- A call that runs in another Rollcage project's folder, or
cds or reaches into one, is checked under each project. The stricter answer wins, so a folder can't bring a laxer config. When two projects' databases are hit, each gets a snapshot. (The project hooks work the same way.) - In a folder that holds Rollcage projects without being one (a session started in
~/Coding, say), they check what touches those projects: their databases and Rollcage's own files. Their other rules stay quiet there. - Cline's hook at the top of a monorepo works the same way.
Cursor
rollcage init (and saving on rollcage settings) adds Rollcage to
.cursor/hooks.json when the project has a .cursor folder or Cursor is installed,
keeping any hooks you already have there. Cursor then checks with Rollcage before shell
commands (beforeShellExecution), MCP tool calls (beforeMCPExecution), file reads
(beforeReadFile) and file writes and deletes (preToolUse). The same rules and
snapshots apply, and the activity log and dashboard show these as Cursor's.
Two differences come from Cursor itself:
- Rollcage doesn't ask in Cursor; it blocks. Cursor doesn't reliably show a hook's question. In its Auto-review mode, a command Auto-review thinks is safe runs without the question (Cursor's staff confirmed this in October 2026, for Cursor 3.21.16), and the hook can't tell which mode is on. File reads and writes can't be asked about at all. So where Rollcage would ask, it blocks the call in Cursor and says why. A production close call is still snapshotted first. To say yes without running it yourself, turn on dashboard approvals.
- Cursor needs an answer from every hook, so safe calls get an explicit "allow", the way Cursor's own hook examples do.
Codex
rollcage init (and saving on rollcage settings) adds a PreToolUse hook to
.codex/hooks.json when Codex is on your computer or the project has a .codex
folder. It covers shell commands, file edits (apply_patch: every file the patch
touches is checked) and MCP tools. Codex asks you to trust new hooks once: open Codex,
run /hooks, and trust Rollcage's.
Codex hooks can't ask you a question (Codex ignores "ask" and runs the tool anyway), so wherever Rollcage would ask, it blocks instead and says so. For a destructive command on production, the snapshot is still taken first; if you really mean it, run the command yourself, or answer it from the dashboard.
Copilot
rollcage init (and saving on rollcage settings) writes .github/hooks/rollcage.json
when Copilot is on your computer or the project uses it (a .github/hooks or
.github/copilot folder, or copilot-instructions.md). Copilot CLI and Copilot's agent in
VS Code then check with Rollcage before every tool call: shell commands, file reads and
edits, and MCP tools. Commit the file like the other hook files; on a computer without
Rollcage (a teammate's, or Copilot's cloud agent), it does nothing.
Differences that come from Copilot itself:
- Copilot also runs the hooks in
.claude/settings.json, Rollcage's Claude Code hook included. Rollcage recognizes Copilot there and answers in Copilot's format; when Copilot would run.github/hooks/rollcage.json(switched on, at the repository root), that one does the checking, so each call is checked (and snapshotted) once. - Where nobody can answer (autopilot, or Copilot's cloud agent), Copilot turns Rollcage's "ask" into a block.
- A hook that runs past its time limit is skipped and the tool runs, so
initgives Copilot the same generous limit as the other agents (timeout_secsplus a minute). - With Copilot's sandbox on, hooks run inside it: let it reach your database and
~/.config/rollcage, or snapshots fail and risky commands are blocked. - Rollcage protects every file in
.github/hooks/(Copilot loads them all, so a new one could switch Rollcage off or rewrite a command after it was checked), and Copilot's settings that can switch hooks off. - Not covered yet: Copilot on Windows (PowerShell hooks); there, the Claude Code hook in
.claude/settings.jsonstill blocks what it would block.
Devin
Devin (Devin Desktop, formerly Windsurf, and the Devin CLI): rollcage init adds a hook
to .devin/hooks.v1.json when Devin or Windsurf is on your computer or the project has a
.devin folder, keeping any hooks you already have there. Devin then checks every tool
call with Rollcage: shell commands, text typed into a running shell or program, file edits,
reads of Rollcage's keys, and MCP tools (called directly or through Devin's
mcp_call_tool).
Like Codex, Devin can't ask you a question: where Rollcage would ask, it blocks and
says so (or, with dashboard approvals on,
holds a production close call for your answer). Devin also runs the hooks in
.claude/settings.json; Rollcage recognizes Devin there and answers in Devin's format,
and leaves the work to .devin/hooks.v1.json when it's installed. Devin runs no hooks in
Restricted Mode, so trust the workspace. Windsurf's older Cascade hooks
(.windsurf/hooks.json) aren't covered.
Gemini CLI
Google moved Gemini CLI's users to the Antigravity CLI (agy) in June 2026. Gemini CLI
still runs with a paid Gemini API key, so Rollcage still covers it. If you've switched to
agy, the Antigravity hook covers it, and this section isn't needed.
rollcage init adds a BeforeTool hook named rollcage to .gemini/settings.json when
Gemini CLI is on your computer (~/.gemini) or the project has a .gemini folder,
keeping your other settings. Gemini CLI then checks every tool call with Rollcage: shell
commands (in the folder they run in), file writes and edits, reads and searches of
Rollcage's keys (read_many_files included), and MCP tools.
Gemini reads project settings only from the folder it starts in, not from parent
folders. So init also adds a hook named rollcage-subfolders to your own
~/.gemini/settings.json (not on Windows). It checks sessions started in a subfolder of a
Rollcage project and does nothing anywhere else: not outside Rollcage projects, not where
the project hook already runs, and not if Rollcage is uninstalled. rollcage status says
whether it's there.
One thing Gemini needs from you: trust the folder when it asks (it runs no hooks at
all in folders it doesn't trust). rollcage doctor checks it.
Gemini CLI asks you about close calls on its own tools, even in YOLO mode. It doesn't
for MCP tools whose server you trust or chose to always allow, so a close call through an
MCP tool is blocked instead. Run headless (gemini -p, piped input or output, or CI) it
can't ask, so Rollcage blocks there too (or, with dashboard
approvals on, holds a production close call
for your answer). Installing an extension, changing MCP servers (gemini mcp add) or
rewriting hooks (gemini hooks migrate) asks first, and Gemini's settings and trusted
folders are protected like the other agents' hooks. Not covered: hooks that installed
extensions add, and one call in a parallel batch changing a file another call in the same
batch runs (Gemini checks the whole batch before running any of it). A Rollcage question
also lets you approve a call your own Gemini policy would deny.
Cline
rollcage init adds a PreToolUse hook file to .clinerules/hooks/ when Cline is on your
computer (~/.cline) or the project uses it. Cline runs it before every tool call:
shell commands (run_commands, however they're spelled), file edits (editor,
apply_patch), file reads and MCP tools. Cline finds hooks at the top of the git
repository it runs in.
Cline can't ask you from a hook. A close call is stopped, and so is the run it's part of, with the reason shown. With dashboard approvals on, a production close call waits for your answer there instead. Cline gives a hook two minutes and then runs the call anyway, so Rollcage answers within that time: a snapshot that would take longer is stopped, and the command blocked.
Rollcage protects Cline's hook folders (.clinerules/hooks, .cline/hooks,
~/.cline/hooks, ~/Documents/Cline/Hooks) and plugin folders. It asks before
cline schedule (scheduled runs skip hooks) and before cline plugin install. Not
covered: if the Rollcage program is removed, or a hook file can't run, Cline goes ahead
without it, and rollcage status and doctor show that.
Droid
rollcage init adds a PreToolUse hook for every tool when Droid is on your computer
(~/.factory) or the project uses it. It goes in .factory/hooks.json at the top of the git
repository, or in the hooks of .factory/settings.json when the project keeps its hooks
there (Droid reads only one of the two). Droid's own tool names are read as what they are:
Execute is a shell command, Create and Edit write files, ApplyPatch is a patch.
Droid can't be made to ask from a hook: its own permission rules decide, and at a high autonomy level the call would just run. So a close call is blocked, with the reason shown (or, with dashboard approvals on, a production one waits for your answer there). The hook is set to block the call if Rollcage itself fails or runs out of time.
Droid runs no hooks in a folder you haven't trusted yet, so trust it when Droid asks.
Rollcage protects Droid's hook, settings and plugin files (in the project, its subfolders
and ~/.factory), and asks before droid --settings and the variables that move settings
elsewhere (other settings can switch hooks off with hooksDisabled), and before installing a
plugin (whose hooks run after Rollcage's). rollcage status says when hooksDisabled is set
for the project or for you.
Qwen Code
rollcage init adds a PreToolUse hook for every tool to .qwen/settings.json when Qwen
Code is on your computer (~/.qwen) or the project uses it, keeping your other settings
(comments are allowed there; the file is saved next to itself first). Its tools are Gemini
CLI's: run_shell_command, write_file, edit, read_file and MCP tools.
Qwen Code asks you about close calls, even in YOLO mode. Run headless (qwen -p), it
can't ask, and blocks instead.
One thing Qwen Code needs from you: it runs a project's hooks only after you approve them
(or trust the folder), so start qwen in the project and approve Rollcage's. Qwen asks again
whenever the project's hooks or its .env files change (rollcage init changing the hook's
time limit counts), and a headless run (qwen -p) never asks: until you've approved, the
hook doesn't run there. Rollcage protects .qwen/settings.json, ~/.qwen/settings.json,
its .env files, extensions and your hook approvals, and asks before qwen --safe-mode,
qwen --bare, the variables that do the same, and installing an extension (whose hooks run
after Rollcage's).
Both were built from their published hook documentation; neither has been run against the real agent yet.
Antigravity
This covers the Antigravity app, its IDE and the Antigravity CLI (agy, which replaced
Gemini CLI for most people in June 2026): all three run the same agent and load the same
hooks file.
Antigravity loads a project's hooks only in a trusted workspace, so rollcage init adds a
PreToolUse hook named rollcage to your own ~/.gemini/config/hooks.json when
Antigravity is on your computer, keeping your other hooks. It checks every tool call
(terminal commands, file writes and edits, MCP tools) and does nothing outside a
Rollcage project. A close call is asked about with Antigravity's force_ask, so it asks
even where you chose "Always allow".
agy --dangerously-skip-permissions approves every permission request, so it would
approve Rollcage's question too. So does the setting the flag stands for,
"toolPermission": "always-proceed" in ~/.gemini/antigravity-cli/settings.json (which
/config saves). Rollcage sees the flag on the agy it runs under, and reads the
setting, and blocks the close call instead, the way it does for Claude Code with permissions bypassed
(with dashboard approvals on, it holds a
production close call for your answer there).
Rollcage protects Antigravity's settings and hooks (~/.gemini/config/, plugins
included, and a project's .agents/hooks.json and plugins), and asks before agy plugin
install, enable and import (a plugin's hooks can change a call after Rollcage checked
it). Not covered: Antigravity skips a hook that fails to run
(for example if the Rollcage program is removed), and it runs another hook's argument
changes after Rollcage's check. This adapter was built from Antigravity 2.33's own
code and documentation; it hasn't been run inside the app yet.
opencode
opencode checks tool calls through plugins, so rollcage init adds a small plugin,
rollcage.js, to your opencode config folder (~/.config/opencode/plugin/) when
opencode is on your computer. It hands every tool call (shell commands, file writes and
edits, patches, reads, MCP tools, subagents' calls) to Rollcage, and does nothing outside
a Rollcage project or if Rollcage isn't installed. A plugin can't make opencode ask, so a
close call is blocked, with the reason shown (or, with dashboard approvals on, waits for
your answer). If Rollcage fails or doesn't answer in time, the call is blocked.
Rollcage protects opencode's config and plugin folders (~/.config/opencode, a project's
.opencode/ and opencode.json). Not covered: opencode started with --pure (or
OPENCODE_PURE=1) loads no plugins, and commands you type yourself with ! don't go
through plugins.
Amp
Amp checks tool calls through plugins, so rollcage init adds a small plugin,
rollcage.ts, to your Amp plugin folder (~/.config/amp/plugins/) when Amp is on your
computer (~/.config/amp). Its tool.call handler hands every tool call to Rollcage, and
does nothing outside a Rollcage project or if Rollcage isn't installed. A close call is
asked about with Amp's own confirm dialog; with no one to ask (amp -x), it's blocked.
If Rollcage fails, dies or doesn't answer in time, the call is blocked. Plugins load by
default; new threads load Rollcage's, and amp plugins list shows it. For amp -x, pass
--plugin-ready-timeout so the run waits for plugins to load (without it, Amp's docs say
the first calls can go before they have).
Amp's MCP tools reach the plugin as server.function, or inside code_exec code that
calls them; both are checked as calls to that server. File writes are checked by the
files Amp itself says a call changes.
Rollcage protects Amp's plugin folders and settings (~/.config/amp/plugins/, a
project's .amp/plugins/, where a rollcage.ts would take the place of Rollcage's:
rollcage status says the project isn't covered when one is there), and asks before
amp plugins add, import and update and amp clone. This adapter was built from
Amp's plugin documentation and hasn't been run inside Amp yet; the documentation doesn't
say what Amp does when a plugin's handler fails or hangs.
What Rollcage can't do
- It sees what the agent runs, not what your app does. If the agent writes app code that deletes data, and you deploy it, that code isn't checked.
- Scripts the agent downloads and runs (
curl ... | bash,curl -o x.sh ... && bash x.sh) aren't judged: Rollcage can't see what they'll do. Downloaded SQL fed to a protected database does ask. - A command too big to check before the agent's hook time limit asks instead: more than
2,000 commands on one line, command substitutions nested too deeply to read, or more
than 100,000 commands once loops, scripts and function calls are followed. Ordinary
commands are nowhere near (a
forloop is followed for up to 32 values; past that its variable counts as unknown). - If the agent has its own way to reach the database that Rollcage can't see (an
unknown CLI that reads a config file, say), Rollcage only catches it if the command
shows it's aimed at production. Add a
[[rule]]for tools you use. -
Where an agent may not show a hook's question, Rollcage blocks instead (after taking the snapshot) and says how to allow the command. That covers:
- Claude Code with permissions bypassed (
--dangerously-skip-permissions) - the Antigravity CLI with
--dangerously-skip-permissionsortoolPermission: "always-proceed" - Cursor, whose Auto-review mode runs a command its hook asked about
With dashboard approvals on, a production close call waits for your answer there. - Plugins, extensions and mods run inside some agents and can change or approve a call after Rollcage checked it. Installing one through the agent asks, and their folders are protected, but ones you installed yourself are trusted. - Claude Code loads hooks from the
.claude/settings.jsonof the folder you start it in, so startclaudefrom your project folder. - Switching Rollcage off needs a person at a terminal, and the hook asks before any command it can tell would do it, through another program or not. Commands started by an agent's program are refused too. An agent set on getting around it could still hide such a command well enough (a disguised command handed to a background process, say): that is what the snapshots are for. - Copilot and Devin keep a shell open between calls, and Rollcage checks each call on its own. It asks when a call points that shell at a protected database (export DATABASE_URL=...,source .env.production), goes into a folder that holds hook files, or leaves a command half-typed, but it can't follow everything a long session builds up (aliases or functions defined earlier, say). - Claude Code with permissions bypassed (
Every built-in rule
What Rollcage watches for out of the box. database rules snapshot first and ask when the command is aimed at production (and only log it elsewhere), ask rules ask before it runs, and warn rules let it run with a heads-up. Turn any of them off with disable_rules under [detection] in rollcage.toml, or add your own (see Your own rules). To see which ones a command trips before you install, type it into the Command X-ray (or press Cmd K here), or write rules of your own in the playground: Rollcage's real engine checks them in your browser.
Loading the rules...