Coolify
Coolify
Coolify connects MaxSuite to your Coolify instances, the self-hosted platform that builds and runs your applications, databases and services. You can see what each instance runs, watch deployments, deploy, restart or stop an app, change its settings, and install Coolify on a new server.
In the sidebar under Servers & apps → Coolify. Needs: Projects. Handles secrets: the module holds each instance's API token, so every change an agent makes here goes to a person first.
Every button on this page that changes something runs the same tool an agent would, as you. Where the approval rules say a person must agree, the button shows the approval card instead of doing it at once, and its label starts with "Ask to…". See Agents and approvals.
The page has three tabs: Resources, Map and Instances.
Resources
- Deploying now: builds in progress, with the application, its status, the server it runs on, its project, when it started and how long it has run. A finished build appears briefly under Just finished. Stop a build here; what it has already done to the server stays done.
- Recent deployments: the last ten across every application, newest first, with how each ended, how long it took and its commit. Redeploy builds again from whatever the branch now points at, or rebuild without Coolify's build cache.
- The resource list: every application, database, service, server and Coolify project the instances report. Each row shows its status, address, server and when it was last seen. Each application has Logs and Deployments, and Deploy, Restart and Stop buttons, each confirmed first.
The server re-reads Coolify every five minutes, and the list refreshes each minute while you have it open.
Above the list you can make something new: New app (from a public repository, a private one through a GitHub app, or a private one with a deploy key), New database, New service (a one-click Coolify template) and New Coolify project. Each asks for the Coolify project, Server, Environment and the Max project it serves.
A resource's panel
Open a resource to manage it. The panel shows only the parts that apply to its kind:
- Environment (apps): the variables, used while building, while running or both. Add variable, Edit, or Paste many. Tick It is a secret for a credential; a value that looks like a credential is refused and must come from a named secret.
- Settings (apps): branch, base directory, build, install and start commands, Dockerfile, port, and "Deploy only when these change".
- Domains (apps and services): Set address, Make public (points DNS at the server, adds the hostname and redeploys so a certificate is issued), and Move an address to another app.
- Backups (databases): the backup schedules and their latest backups. Add a schedule with how many to keep and for how many days, and optionally Back up now too. Removing a schedule or a backup file asks first.
- Tasks (apps and services): scheduled commands. Add a task, change one, pause it, run it now, or read its Runs.
- Storage: volumes (a folder that keeps its data) and file mounts (text you write here). Add a volume or file. Removing a volume loses its data.
- Health (apps): the health check path, port, interval, time limit, grace at start and misses allowed.
- Previews (apps): turn pull-request previews on or off, and Deploy a pull request by number.
- Versions (apps): earlier images kept on the server. Ask to roll back? puts one back. Data is not rolled back.
- Manage: Attach to a Max project, Change settings, Copy to another server (with or without its data, and optionally start the copy), and Remove…. Removing is refused while the resource runs or while one of its addresses still points at its server.
Map
Each Coolify instance as a tree: the servers it deploys onto (with their real address and the provider machine behind each), the Coolify projects on them, and the resources in those, each with the MaxSuite projects it Serves. Use Find in the map to search, or Only this project to narrow it to one project. A resource with no project can be filed into one straight from its row.
Instances
Each connected Coolify instance with its address, its state (what its last sync or test said), when it was last synced and how many resources it holds. The token is stored encrypted and never shown again. Servers opens the servers an instance can deploy onto, with their Health and What runs on it; a server can be checked again or removed from Coolify there.
Connect an instance you already have
- Click Add instance, then I already have Coolify.
- Enter a Name, the Base URL and an API token made in Coolify.
- Save, then Test that it answers, and Sync now to bring in what it runs.
You can rename an instance, switch it off with Active, or replace its token. A switched-off instance refuses every deploy, restart and sync until it is switched back on. Disconnecting asks first and deletes what was synced from it here; nothing at Coolify is touched.
Install Coolify on a new server
- Click Install on a new server.
- Let Max in: copy the line shown and run it on the server, so MaxSuite can sign in over SSH with its own key. You never type a server password.
- Where: give the server's address, SSH user and port, a name, the Coolify admin email, and a domain from Domains (or "No domain", which you must confirm).
- Follow the steps live: Check, Install, Configure, Token, Connect. When it is done, take the admin password; it is shown once.
Recent installs lists past installs and where each stopped. A failed one can be tried again. Making a new SSH key asks first, because servers with the old key need the new line before MaxSuite can sign in again.
Who can do what
| Permission | In plain words |
|---|---|
View coolify (coolify:read) | See instances, the map, resources, deployments, logs and status. |
Manage coolify (coolify:write) | Add, change and remove instances; install Coolify; sync and test; deploy, start, stop, restart, cancel and roll back; read and set environment variables; create, change, copy and remove resources, backups, tasks, storage, health checks and previews. |
Reading an application's environment variables needs Manage coolify, not just view. Every instance and resource is visible to everyone who can view Coolify in the workspace. See People, roles and permissions.
What happens on its own
| Job | When | What it does |
|---|---|---|
status-sync | Every 5 minutes | Syncs every active instance, so each resource's status reflects what Coolify says now. A listing that fails is reported and leaves its rows alone, rather than marking them missing. |
Needs
- Projects switched on.
- Putting an app on a hostname also needs DNS and Domains, with the domain's zone linked.
What agents can do
Reads run straight away. Every change asks a person first, because the module holds API tokens; a rule naming the exact tool can let that one tool through. Tokens, keys and secrets are never returned, and log lines are scrubbed. See Agents and approvals.
Instances — read-only: coolify.instances. Asks first: coolify.test, coolify.sync (nothing at Coolify changes), coolify.updateInstance (rename or disable), coolify.removeInstance (disconnect and delete what was synced here).
Install Coolify — read-only: coolify.sshKey, coolify.installDomains, coolify.installJobs, coolify.installJob. Asks first: coolify.installOnServer, coolify.retryInstall, coolify.newSshKey.
What runs where (read-only): coolify.resources, coolify.map, coolify.servers, coolify.serverResources, coolify.status, coolify.projects, coolify.githubApps, coolify.privateKeys (never the key itself), coolify.serverHealth, coolify.serviceTemplates.
Servers (asks first): coolify.checkServer checks a server again over SSH; coolify.removeServer removes one from Coolify. It is refused for the machine Coolify runs on and while anything is still on it. The machine keeps running, and keeps being billed, until you cancel it with its provider.
Deployments and logs — read-only: coolify.deployment, coolify.deployments, coolify.logs, coolify.rollbackImages. Asks first: coolify.deploy, coolify.cancelDeployment, coolify.rollback.
Running and stopping (asks first): coolify.restart, coolify.action (start, stop or restart an app, service or database).
Creating and configuring (asks first): coolify.createProject, coolify.createApp, coolify.createDatabase (private unless asked; its internal address is stored as a named secret), coolify.createService, coolify.updateApp, coolify.linkProject (which MaxSuite project a resource belongs to).
Environment variables — read-only: coolify.envs (a credential reads as a mask). Asks first: coolify.setEnv, coolify.setEnvs, coolify.removeEnv.
Hostnames and moving (asks first): coolify.exposeApp (also needs DNS write and Domains read), coolify.setServiceDomain, coolify.cloneTo, coolify.moveDomain.
Backups — read-only: coolify.backups. Asks first: coolify.setBackupSchedule, coolify.removeBackupSchedule, coolify.removeBackup.
Scheduled tasks — read-only: coolify.tasks, coolify.taskRuns. Asks first: coolify.setTask, coolify.runTask, coolify.removeTask.
Storage — read-only: coolify.storages. Asks first: coolify.setStorage, coolify.removeStorage.
Health checks — read-only: coolify.healthCheck. Asks first: coolify.setHealthCheck.
Previews — read-only: coolify.previews. Asks first: coolify.setPreviews, coolify.deployPreview, coolify.removePreview.
Removing (asks first): coolify.remove deletes a resource in Coolify. It is refused while it runs or while a hostname still points at its server. Data volumes go unless kept.
Some tools need a recent Coolify version; the tool says so when yours is older.