The Coolify Secret Sync requires a Coolify app connection. This guide walks you through creating a project-scoped app connection.
Prerequisites
- A project with secrets configured
- The Owner or Admin role in the Coolify team that owns the resource you plan to sync to
- If you self-host Coolify, API access turned on under Settings > Advanced in Coolify
- If your Coolify instance isn’t reachable from the internet, a Gateway with network access to it
Step 1: Create a Coolify API token
Infisical needs a Coolify API token that can read, write, and delete environment variables.1
Log in to Coolify and switch to the team that owns the resources you plan to sync to. A token can only access its own team’s resources.
2
In the sidebar, select Keys & Tokens, then API Tokens, and select New token.
3
Fill in the New API token form:
- Description: A name that identifies the token, such as
infisical - Expires in: How long the token stays valid; once it expires, the sync fails until you update the connection with a new token
- Permissions:
read,read:sensitive,write, anddelete - Resources: All resources in the team, or Selected projects, environments, or resources to limit the token to the resources you plan to sync to
4
Copy the token from the Copy your token window and store it securely. Coolify shows it only once.
Step 2: Set up the sync in Infisical
1
In your project, go to Integrations and open the Secret Syncs tab. Select + Add Sync.
Then, select the Coolify sync.
Then, select the Coolify sync.2
Under Source, choose which secrets to sync from Infisical:Then select Continue.
- Environment: The project environment to retrieve secrets from
- Secret Path: The folder path to retrieve secrets from
- Include secrets from all subfolders: Also syncs the secrets in every folder beneath the path
Coolify environment variable names must start with a letter or underscore, and can only contain letters, numbers, underscores (
_), and periods (.). Names that start with SERVICE_ are reserved for the variables Coolify generates, such as a service’s database password. If a secret’s name breaks either rule, the sync fails with an error that names the secret.3
Under Destination, create or select the Coolify app connection the sync will use, then choose the resource that receives the environment variables.
- Create a new app connection
- Use an existing connection
Under Coolify Connection, select Create Connection in the dropdown, then fill in:
- Name: A descriptive name for the connection; it must be slug-friendly
- Description (optional): A note for future reference
- Gateway: The Gateway or Gateway pool to route requests through if your Coolify instance isn’t reachable from the internet; otherwise leave it as Internet Gateway
- Method: API Token, the only method the connection supports
- Instance URL:
https://app.coolify.iofor Coolify Cloud (filled in by default), or the URL of your self-hosted Coolify dashboard, such ashttps://coolify.example.com - Coolify API Token: The token you copied when creating a Coolify API token
This creates a connection scoped to the current project. To share the connection across other projects, create it at the organization level first, then select it here.
- Resource: The Coolify application, service, or database to sync to, listed under its project and environment
- Scope (applications only): Production for the application’s production variables, or Preview Deployments for the variables Coolify gives preview deployments of pull requests
4
Under Initial Sync Behavior, choose how Infisical handles environment variables that already exist on the resource on the first sync:Then select Continue.
- Overwrite Destination Secrets: Infisical writes its secrets to the resource without importing anything first
- Import Destination Secrets - Prioritize Infisical Values: Infisical first imports the resource’s environment variables; if a name exists in both places, Infisical keeps its own value
- Import Destination Secrets - Prioritize Coolify Values: Infisical first imports the resource’s environment variables; if a name exists in both places, the Coolify value replaces the Infisical value
Coolify never returns the value of a locked environment variable, so an import fails if the resource has one. For that resource, choose Overwrite Destination Secrets instead.
5
Under Sync Options, choose how secrets are synced:
- Prevent secret deletion: When enabled, Infisical adds and updates environment variables in Coolify but never deletes them; enable this if you manage some of the resource’s environment variables outside of Infisical
- Auto-sync on changes: When enabled, secrets sync to Coolify automatically as the source changes; turn it off to sync manually only
- Customize key names: Adds a prefix or suffix to every environment variable name, using
{{secretKey}}for the original name and{{environment}}for the environment slug
6
Give the sync a Name and an optional Description. The name must be slug-friendly.Then select Continue.
7
Review your Coolify Sync configuration, then select Create Sync.
The sync is created. If Auto-sync on changes is enabled, it begins syncing secrets to Coolify right away.
Step 3: Restart the resource in Coolify
Coolify passes environment variables to a resource’s containers when they start, so the containers keep the old values until the resource restarts. After each sync that changes a value, open the resource in Coolify and restart it. If an application reads the variable while it builds, redeploy the application instead.FAQ
Does the sync update preview deployments?
Does the sync update preview deployments?
Only if you choose the Preview Deployments scope. A sync with the Production scope writes only the application’s production variables and keeps them out of preview deployments. It doesn’t touch preview variables that you or other tools created.To give preview deployments their own values, create a second sync with the Preview Deployments scope from a non-production environment, such as
staging.What happens to a value that starts with $?
What happens to a value that starts with $?
Coolify keeps the value as written. The sync marks every variable it writes as literal, so Coolify doesn’t replace a value such as
$DATABASE_URL with another variable’s value.Next steps
Coolify
Create an organization-level Coolify connection to share across projects.
Secret syncs
Learn how secret syncs work and how to manage them.