# Install

Install basalt and guard the tables your agent may change on your own Postgres.

Use this page to put BasaltDB on a Postgres you own and choose the tables your agent may touch. To try it first on a sample database, use the [Quickstart](/start/quickstart/).

You need:

- macOS and Linux.
- A Postgres you own: Supabase, RDS, or one you host yourself. You need its admin connection string, the one for the `postgres` user.
- A browser on the same machine, with a passkey (Touch ID, a security key, or a password manager that stores passkeys).
- An agent that supports MCP. See [Connect an agent](/start/connect-agent/).

The admin connection string is used once, by `basalt init`, typed into its hidden prompt. It is never stored. Do not export it or put it on a command line.

## 1. Install basalt

This is an alpha prerelease. Expect breaking changes.

### Homebrew

```sh
brew install basaltdbhq/tap/basaltdb
```

### Release archive

Download an archive from [GitHub Releases](https://github.com/BasaltDBHq/BasaltDB/releases), together with `SHA256SUMS`. Check the archive against `SHA256SUMS`, unpack it, and put `basalt` on your `PATH`.

```sh
curl -fsSL -O https://github.com/BasaltDBHq/BasaltDB/releases/download/v0.0.1-alpha.2/basaltdb_0.0.1-alpha.2_linux_amd64.tar.gz
curl -fsSL -O https://github.com/BasaltDBHq/BasaltDB/releases/download/v0.0.1-alpha.2/SHA256SUMS
grep 'basaltdb_0.0.1-alpha.2_linux_amd64.tar.gz$' SHA256SUMS | sha256sum -c -
tar -xzf basaltdb_0.0.1-alpha.2_linux_amd64.tar.gz
```

### Build from source

You need Go 1.26 or newer, and `git`. Then put `basalt` on your `PATH`.

```sh
git clone https://github.com/BasaltDBHq/BasaltDB.git
cd BasaltDB
go build -o basalt ./cmd/basalt
```

Check the install:

```sh
basalt version
```

## 2. Get the admin connection string

**Supabase.** In the dashboard press **Connect** and copy the string that matches your network.

| String                                                                          | Use it                             |
| ------------------------------------------------------------------------------- | ---------------------------------- |
| Session pooler, port 5432 (`postgres.<ref>@aws-0-<region>.pooler.supabase.com`) | If unsure. Works on IPv4 and IPv6. |
| Direct connection (`db.<ref>.supabase.co`)                                      | Only if your network has IPv6.     |

Fill in `[PASSWORD]` with your database password. URL-encode characters such as `@`, `/`, `:` and `#`. Add `?sslmode=require` at the end.

**Other Postgres.** Use `postgresql://postgres:PASSWORD@HOST:5432/DBNAME?sslmode=require`. See [Hosts](/guides/hosts/) for RDS and self-hosted notes.

## 3. Guard your tables

Name the tables the agent may use. `--write` lists tables it may read and change. `--read` lists tables it may only read. Both take a comma-separated list of `schema.table`.

```sh
basalt init --agent my_bot \
  --write public.leads --read public.lead_notes
```

`my_bot` is the agent's name. Pick any name. Init asks, in order:

1. `Admin connection string (used once, never stored):` Paste the string from step 2. Nothing is echoed.
2. Only if a table has row-level security on and no policy for the agent: `... hides its rows with row-level security. Let my_bot see all <n> rows of this table? [y/N]`. Answer `y` to add a policy for the agent role only. With `n` the agent reads zero rows. Supabase can turn row-level security on for every new table. Init asks before it shows the SQL.
3. It prints the setup SQL, then `Run this SQL as postgres? [y/N]`. Type `y`.
4. `basalt: guard installed; agent role basalt_agent_my_bot`
5. It prints a `http://localhost:8787/passkeys/register#...` link. Open it, press the button, confirm with your passkey, copy the `basalt-passkey.1....` code the page shows, and paste it at `Paste the code the page shows:`. Then `basalt: passkey registered for localhost`.
6. `Install the engine as a background service? ... [Y/n]` Press Enter. Init runs one `sudo`, installs and starts the service, and checks that the engine answers.

Port 8787 must be free while init waits for the passkey, and afterwards for the engine. `lsof -nP -iTCP:8787 -sTCP:LISTEN` shows what holds it.

## 4. Check that it works

```sh
basalt status --agent my_bot
curl -s http://localhost:8787/healthz
```

`basalt status` reports the engine, the guard version and the passkey, and lists any problem with what to do about it. `curl` prints `ok`.

## 5. Connect your agent

Next: [Connect an agent](/start/connect-agent/). The agent starts `basalt mcp --agent my_bot`.

## If something is off

- `tables ... not found in database`: the tables in `--write` or `--read` do not exist in the database this connection string points at. Init checks first and changes nothing.
- The agent reads zero rows from a table that has rows: row-level security is on with no policy for the agent. Run step 3 again and answer `y` to the row-level security question, or add `--agent-rls=all-rows`.
- `/mcp` shows the server failed, or the connection closes at once: the engine admits only the OS user that ran `init`. Start the agent as that user.
- `guard schema vN is older than this build's vM`: run `basalt upgrade --agent my_bot`. See [Upgrade](/guides/upgrade/).
- If `basalt init` or `basalt service install` says the binary is not owned by root: the engine service will only run a copy that root owns and that group and others cannot change. Put `basalt` in a root-owned directory and run that copy, or use `--no-service`.
- No `sudo`, or you do not want a service: add `--no-service` to `basalt init`. It prints the one `basalt engine --config ...` command to run in the foreground as you. Writes are still guarded in Postgres, but your user can read the agent's credential file.

## Remove it

```sh
basalt uninstall
sudo basalt service uninstall
```

`basalt uninstall` asks for the admin connection string, then drops the `basalt_meta` schema, the guard's triggers and policies, and the `basalt_*` roles. `service uninstall` stops and removes the engine service. See [Remove BasaltDB](/guides/remove/).
