> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agenium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a Supabase database

> Give Agenium its shared database through Supabase's own sign-in, with no credentials to copy.

> [!NOTE]
>
> Draft: these steps await verification against the current release of Agenium.

**Outcome:** Agenium, and every capability on your Mac, works against a Supabase project with a database role and schema of Agenium's own, over encrypted connections only.

Agenium keeps your agents, tasks, Inbox and its own marks in one shared database. Supabase is the default way to get one; the other is a [Postgres of your own](https://docs.agenium.io/app/settings.md#database).

```mermaid theme={null}
flowchart LR
  ak["Agenium"] -- "Supabase sign-in<br/>in your browser" --> sb["Supabase"]
  sb --> proj["Project<br/>(new or existing)"]
  ak -- "creates role and schema,<br/>turns on SSL enforcement" --> proj
  caps["Capabilities"] --> proj
  ak -- "reads" --> proj
```

## What you need

* A Supabase account, or the willingness to create one at sign-in.
* For an existing project: knowing that once Agenium turns on SSL enforcement, any client of that project that connects without encryption stops connecting.

## Steps in the app

**1. Open the Database settings**

In the onboarding this is the **Database** step. Later, open **Settings** (⌘,) and go to **Database**. Choose the **Supabase** tab; it is the first and the default.

**2. Sign in to Supabase**

Start the sign-in. Supabase's own sign-in opens in your browser; sign in and allow Agenium. You copy no credentials.

**3. Choose or create a project**

Agenium lists your projects. Choose one, or create a new one.

For an existing project, Agenium says first that clients without encryption will stop connecting. Confirm only if nothing of yours relies on unencrypted connections.

**4. Let Agenium set it up**

Agenium creates a database role and schema of its own in the project and turns on its SSL enforcement. The form then shows the connection and a connection indicator.

**5. Set the pool size, if needed**

While the database is a Supabase session pooler, the page holds its **pool size**, 15 by default. Set it to your pooler's size, since the pooler does not report it; the sidebar's Database row measures against it.

## Steps by command line

The form reads and writes the machine's database setting through the capabilities manager. To see what is set, or to check it:

```bash theme={null}
capabilities store show
capabilities store doctor
```

`capabilities help` gives the full reference for the database setting.

## Check it worked

1. The Database page shows the connection indicator as connected.
2. The sidebar's **Database** row is grey and shows used of available connections, such as `4/15`. Hover it for the host and mode, the round trip, and when it was last read.
3. **Agents** lists your agents; a new Mac's onboarding goes on to **First Agent**.

## Common failures

| What you see | Why, and what to do |
| - | - |
| The Database row is red with **Unreachable** | The project does not answer. Check it is not paused in Supabase, and your network. |
| The Database row is red with **Auth failed** | The login was refused. Run the sign-in again from Settings > Database. |
| The Database row is red with **Pool full** | Every pooler place is taken. Check the pool size matches your Supabase pooler, and what else holds connections. |
| The Database row is orange | 70% of places used, a connection idle in a transaction for long, or slow round trips. Hover it for which. |
| Another tool of yours stopped connecting to the project | Agenium turned on SSL enforcement. Configure that tool to connect with encryption. |
| The database check fails at the step | It says why in one line, with the database's own words under **Details**. |

## Related

* [Settings > Database](https://docs.agenium.io/app/settings.md#database)
* [Install Agenium](https://docs.agenium.io/install.md#the-onboarding)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.