Skip to main content
A Coolify Secret Sync pushes secrets from Infisical into the environment variables of a Coolify application, service, or database, where Coolify passes them to the resource’s containers. Each Infisical secret becomes an environment variable with the same name, unless you customize key names to add a prefix or suffix.
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, and delete
  • Resources: All resources in the team, or Selected projects, environments, or resources to limit the token to the resources you plan to sync to
Then select Create token.
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

To create the sync using the API, use the Coolify Create endpoint.
1
In your project, go to Integrations and open the Secret Syncs tab. Select + Add Sync.Secret Syncs TabThen, select the Coolify sync.
2
Under Source, choose which secrets to sync from Infisical:
  • 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.
If you need to sync secrets from multiple folder locations, use secret imports.
Then select Continue.
3
Under Destination, create or select the Coolify app connection the sync will use, then choose the resource that receives the environment variables.
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.io for Coolify Cloud (filled in by default), or the URL of your self-hosted Coolify dashboard, such as https://coolify.example.com
  • Coolify API Token: The token you copied when creating a Coolify API token
Select Connect to Coolify. Infisical returns you to the sync form with the new connection selected.
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
Then select Continue.
4
Under Initial Sync Behavior, choose how Infisical handles environment variables that already exist on the resource on the first sync:
  • 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.
Then select Continue.
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
A Coolify resource also holds environment variables that people and other tools create, so a sync can change variables that were created outside Infisical. If you don’t customize key names, the sync treats every environment variable on the resource as one it manages, except the ones whose names start with SERVICE_:
  • If a variable has the same name as an Infisical secret, the sync overwrites the variable’s value
  • If Prevent secret deletion is off, every variable that isn’t in Infisical is deleted
With customized key names, the sync writes only names with your prefix or suffix, and deletes only variables whose names match it.Before the first sync, customize key names or keep Prevent secret deletion on. Prevent secret deletion is on by default when you create the sync in the UI, but off unless you set disableSecretDeletion when you create it through the API.
Then select Continue.
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

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.
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.