Remove BasaltDB

Removing BasaltDB takes a few commands. Your tables and your rows are not touched. The record of what agents did is deleted with it, so you cannot undo agent runs afterwards. Read what goes and what stays first.

1. Disconnect the agent

Remove the BasaltDB server from the agent’s MCP client, so the agent stops calling it. For Claude Code:

claude mcp remove basalt-demo_bot

For another client, delete the basalt-<name> entry from its config. See Connect an agent.

2. Remove the passkey from the database

Skip this if you do not mind leaving the passkey on your devices. basalt passkey remove also prints a link that asks your devices to drop the passkey, and it only works while the guard still exists.

basalt passkey list --agent NAME
basalt passkey remove PASSKEY_ID

Take PASSKEY_ID from the list output. remove asks for the admin connection string, then asks you to confirm. If it is your last passkey, the command refuses unless you add --force, and then asks you to type the passkey’s label to confirm, even with --yes. That is fine here, because you are removing everything. The command prints a /passkeys/forget link: open it on each device that holds the passkey.

See Passkeys.

3. Uninstall the guard

basalt uninstall

It asks for the admin connection string, the same way basalt init does: a hidden prompt, or BASALT_ADMIN_DATABASE_URL. It then asks:

Drop basalt_meta, the ledger, every basalt_* role and the demo schema basalt_demo, if init --demo made it? [y/N]

Answer y. You see:

basalt: guard uninstalled; credential files of its agents no longer work

4. Remove the engine service

If you installed the engine as a background service:

sudo basalt service uninstall

This stops the service and removes it. If you ran the engine in the foreground, stop it with Ctrl-C.

5. Remove the demo data

basalt uninstall already drops the sample schema basalt_demo when basalt init --demo made it. If you ran the demo on Docker, you can also remove the container.

docker rm -f basalt-demo

6. Check that nothing is left

Run both queries as your admin role. Each returns no rows.

SELECT nspname FROM pg_namespace WHERE nspname IN ('basalt_meta', 'basalt_demo');
SELECT rolname FROM pg_roles WHERE rolname LIKE 'basalt\_%';

What goes and what stays

Removed by basalt uninstall:

• The basalt_meta schema, which holds the ledger, the old values and your passkeys’ public keys.
• The guard’s triggers and policies on your tables.
• The basalt_* roles, including every agent’s role. The agents’ credential files stop working.

Removed by sudo basalt service uninstall: the engine’s background service.

Left in place:

• Your tables and your rows. Rows an agent changed stay as they are now. Nothing is undone.
• Policies you wrote by hand. Uninstall drops the policies that basalt init added, such as the one that lets an agent see rows. A policy you created yourself stays.
• The engine’s files on its machine: the config (engine.json), the agent’s credential file and the state directory. They are of no use after uninstall, so you can delete them. The config is /etc/basalt/engine.json on Linux and /Library/Application Support/Basalt/engine.json on macOS.
• The basalt program. Delete it as you installed it.
• Your passkey on your devices. Uninstall cannot reach them. Delete it in your password manager or browser settings, if you do not want to keep it. Step 2 prints a link that asks the browser to forget it, where the browser supports it.

A bot on its own computer

basalt uninstall runs on your own computer, with the admin connection string. Never run it on the bot’s machine. Ask the bot to stop its engine and remove its files on its own machine. Then run steps 3, 5 and 6 yourself.

Next

• Install: set BasaltDB up again.
• The ledger: what is deleted with basalt_meta.