> ## 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 Coolify and create an instance

> Pair Agenium with an existing Coolify instance, or have Oracle install Coolify on a fresh server.

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

**Outcome:** Agenium holds its own Coolify connection, the platform where it places your agents' server nodes.

Agenium holds one Coolify connection of its own. It belongs to the app, not to any agent, and no agent's vault holds its token. There are two ways to get it: connect an instance you already have, or create one on a fresh server.

```mermaid theme={null}
flowchart LR
  subgraph a["Connect"]
    addr["Address + API token"] --> ak1["Agenium validates<br/>and keeps it"]
  end
  subgraph b["Create instance"]
    ip["Server IP<br/>(root over SSH)"] --> oracle["Oracle session"]
    oracle -- "installs" --> coolify["Coolify + Postgres<br/>on the server"]
    coolify -- "paired" --> ak2["Agenium"]
  end
```

## What you need

* **To connect**: an existing Coolify instance's address and an API token for it.
* **To create**: a fresh server your Mac reaches as root over SSH, and its IP address.

## Steps in the app

> [tab] Connect an existing instance
>
> **1. Open Settings > Coolify**
>
> Open **Settings** (⌘,) and go to **Coolify**.
>
> **2. Enter the address and token**
>
> Type the instance's address and paste its API token. Agenium validates the token against the instance and keeps it in a file of its own, readable only by you, that leaves the Mac only for that Coolify.

> [tab] Create an instance
>
> **1. Open Settings > Coolify and choose Create instance**
>
> Type the IP address of the server.
>
> **2. Press Create**
>
> Your press is the confirmation for everything the install needs, so it runs to its end without further questions. Agenium starts an [Oracle](https://docs.agenium.io/app/oracle.md) session that installs Coolify on the server by the Coolify capability's bootstrap procedure. Oracle works around what a script would not foresee, and says what you must do when it cannot finish.
>
> **3. Answer the database question, if asked**
>
> The install also sets up a Postgres on the new server, but never switches your Mac's database on its own:
>
> * With a database already configured, Oracle leaves it and says the new server's Postgres can take over later; your data does not move by itself.
> * With none configured, Oracle asks you to choose between the new server's Postgres and Supabase. The server's Postgres needs no outside account, but lives and fails with that server, and you back it up. Supabase does not depend on the server, and its free plan has its own limits.
>
> **4. Wait for the pairing**
>
> The session ends with the new instance paired with your Mac, and it becomes Agenium's Coolify when none was set.

## Steps by command line

Oracle follows the Coolify capability's own bootstrap procedure, which you can read:

```bash theme={null}
coolify guide bootstrap
coolify help
```

## Check it worked

1. **Settings > Coolify** shows the connected instance.
2. An agent's **Add Node** offers the servers of this Coolify, each with its free memory. See [Add a server node](https://docs.agenium.io/recipes/add-a-server-node-and-move-a-service.md).

## Common failures

| What you see | Why, and what to do |
| - | - |
| The token is refused | It is wrong or lacks rights on that instance. Create a new API token in Coolify. |
| Oracle cannot reach the server | Your Mac must reach it as root over SSH. Check `ssh root@<server-ip>` works from a terminal. |
| Oracle stops and asks you to do something | A step needs you, such as a DNS or firewall change. Do it and tell Oracle in the session. |
| Your agents still use the old database after Create | That is by design: Oracle never switches the database on its own. |

> [!NOTE]
>
> TODO: the exact labels of the Connect form's fields and buttons, and whether several Coolify connections can be held, await verification.

## Related

* [Settings > Coolify](https://docs.agenium.io/app/settings.md#coolify)
* [Coolify capability](https://docs.agenium.io/capabilities/coolify.md)
* [Oracle](https://docs.agenium.io/app/oracle.md)


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