Coolify SDK for PHP

A fully-typed PHP SDK for the Coolify API, built on Saloon v4. Provides a clean, fluent interface to manage applications, databases, services, servers, deployments, and more — with first-class Laravel integration.

Requirements

PHP 8.1 or higher
Saloon ^4.0
illuminate/support ^10.0 | ^11.0 | ^12.0 | ^13.0

Installation

composer require sq-dev/coolify-sdk

Configuration

Laravel

The package uses Laravel auto-discovery — the service provider and facade are registered automatically.

Add the following environment variables to your .env file:

COOLIFY_TOKEN=your-api-token
COOLIFY_BASE_URL=https://app.coolify.io/api/v1

COOLIFY_BASE_URL defaults to the Coolify Cloud API. Point it at your self-hosted instance if needed.

To publish the config file:

php artisan vendor:publish --tag=coolify-config

This creates config/coolify.php:

return [
    'token'    => env('COOLIFY_TOKEN', ''),
    'base_url' => env('COOLIFY_BASE_URL', 'https://app.coolify.io/api/v1'),
];

Standalone (without Laravel)

Instantiate the connector directly:

use Coolify\CoolifyConnector;

$coolify = new CoolifyConnector(
    token: 'your-api-token',
    baseUrl: 'https://app.coolify.io/api/v1',
);

Quick Start

Using the Facade (Laravel)

use Coolify\Laravel\Facades\Coolify;

// List all applications
$response = Coolify::applications()->list();
$apps = $response->json();

// Get Coolify version
$version = Coolify::version()->json();

// Create a project
$response = Coolify::projects()->create(name: 'My Project', description: 'Production workloads');

// Deploy an application
$response = Coolify::deployments()->deploy(uuid: 'app-uuid', force: true);

Using Dependency Injection (Laravel)

use Coolify\CoolifyConnector;

class DeployController
{
    public function __construct(
        private CoolifyConnector $coolify,
    ) {}

    public function deploy(string $uuid)
    {
        return $this->coolify->deployments()->deploy(uuid: $uuid);
    }
}

Standalone Usage

use Coolify\CoolifyConnector;

$coolify = new CoolifyConnector(token: 'your-api-token');

$servers = $coolify->servers()->list()->json();
$databases = $coolify->databases()->list()->json();

API Resources Reference

All resources are accessed through the CoolifyConnector instance (or the Coolify facade in Laravel). Each method returns a CoolifyResponse object that extends Saloon's Response.

General

Methods available directly on the connector:

Method	Description
`version()`	Get Coolify version
`healthcheck()`	Health check
`enable()`	Enable API
`disable()`	Disable API

$coolify->version()->json();       // "4.x.x"
$coolify->healthcheck()->json();   // "OK"

Applications

$coolify->applications()

Method	Description
`list(?string $tag)`	List all applications, optionally filtered by tag
`get(string $uuid)`	Get application by UUID
`createPublic(...)`	Create from a public Git repository
`createPrivateGithubApp(...)`	Create from a private GitHub App repository
`createPrivateDeployKey(...)`	Create from a repository using a deploy key
`createDockerfile(...)`	Create from a raw Dockerfile
`createDockerImage(...)`	Create from a Docker registry image
`createDockerCompose(...)`	Create from a raw Docker Compose file
`update(string $uuid, array $data)`	Update an application
`delete(string $uuid, ...)`	Delete an application (with optional cleanup flags)
`start(string $uuid, ?bool $force, ?bool $instantDeploy)`	Start / deploy an application
`stop(string $uuid)`	Stop an application
`restart(string $uuid)`	Restart an application
`getLogs(string $uuid, ?int $lines)`	Get application logs
`listEnvs(string $uuid)`	List environment variables
`createEnv(string $uuid, ...)`	Create an environment variable
`updateEnv(string $uuid, ...)`	Update an environment variable
`bulkUpdateEnvs(string $uuid, array $data)`	Bulk update environment variables
`deleteEnv(string $uuid, string $envUuid)`	Delete an environment variable

Creating a public application:

$response = $coolify->applications()->createPublic(
    projectUuid: 'project-uuid',
    serverUuid: 'server-uuid',
    gitRepository: 'https://github.com/user/repo',
    gitBranch: 'main',
    buildPack: 'nixpacks',
    portsExposes: '3000',
);

Managing environment variables:

$coolify->applications()->createEnv(
    uuid: 'app-uuid',
    key: 'APP_ENV',
    value: 'production',
    isPreview: false,
);

$coolify->applications()->bulkUpdateEnvs('app-uuid', [
    ['key' => 'DB_HOST', 'value' => 'localhost'],
    ['key' => 'DB_PORT', 'value' => '5432'],
]);

Databases

$coolify->databases()

Method	Description
`list()`	List all databases
`get(string $uuid)`	Get database by UUID
`update(string $uuid, array $data)`	Update a database
`delete(string $uuid, ...)`	Delete a database (with optional cleanup flags)
`start(string $uuid)`	Start a database
`stop(string $uuid)`	Stop a database
`restart(string $uuid)`	Restart a database
`createPostgresql(...)`	Create a PostgreSQL database
`createMysql(...)`	Create a MySQL database
`createMariadb(...)`	Create a MariaDB database
`createMongodb(...)`	Create a MongoDB database
`createRedis(...)`	Create a Redis database
`createKeydb(...)`	Create a KeyDB database
`createDragonfly(...)`	Create a Dragonfly database
`createClickhouse(...)`	Create a ClickHouse database
`getBackups(string $uuid)`	Get database backups
`createBackup(string $uuid, string $frequency, ...)`	Create a backup schedule
`updateBackup(string $uuid, string $scheduledBackupUuid, array $data)`	Update a backup schedule
`deleteBackup(string $uuid, string $scheduledBackupUuid, ...)`	Delete a backup schedule
`listBackupExecutions(string $uuid, string $scheduledBackupUuid)`	List backup executions
`deleteBackupExecution(string $uuid, string $scheduledBackupUuid, string $executionUuid)`	Delete a backup execution

Creating a PostgreSQL database:

$response = $coolify->databases()->createPostgresql(
    projectUuid: 'project-uuid',
    serverUuid: 'server-uuid',
    environmentName: 'production',
);

Setting up automated backups:

$coolify->databases()->createBackup(
    uuid: 'db-uuid',
    frequency: '0 2 * * *',
    enabled: true,
    saveS3: true,
    s3StorageUuid: 's3-uuid',
    retentionDaysLocally: 7,
);

Services

$coolify->services()

Method	Description
`list()`	List all services
`get(string $uuid)`	Get service by UUID
`create(string $serverUuid, string $projectUuid, ...)`	Create a new service
`update(string $uuid, ...)`	Update a service
`delete(string $uuid, ...)`	Delete a service (with optional cleanup flags)
`start(string $uuid)`	Start a service
`stop(string $uuid)`	Stop a service
`restart(string $uuid, ?bool $latest)`	Restart a service
`listEnvs(string $uuid)`	List environment variables
`createEnv(string $uuid, ...)`	Create an environment variable
`updateEnv(string $uuid, ...)`	Update an environment variable
`bulkUpdateEnvs(string $uuid, array $data)`	Bulk update environment variables
`deleteEnv(string $uuid, string $envUuid)`	Delete an environment variable

$response = $coolify->services()->create(
    serverUuid: 'server-uuid',
    projectUuid: 'project-uuid',
    type: 'plausible',
    name: 'Analytics',
    instantDeploy: true,
);

Servers

$coolify->servers()

Method	Description
`list()`	List all servers
`get(string $uuid)`	Get server by UUID
`create(...)`	Create a new server
`update(string $uuid, ...)`	Update a server
`delete(string $uuid)`	Delete a server
`getResources(string $uuid)`	Get server resources (apps, databases, services)
`getDomains(string $uuid)`	Get all domains on a server
`validate(string $uuid)`	Validate server connectivity

$response = $coolify->servers()->create(
    name: 'production-01',
    ip: '10.0.0.1',
    port: 22,
    user: 'root',
    privateKeyUuid: 'key-uuid',
);

$domains = $coolify->servers()->getDomains('server-uuid')->json();

Projects

$coolify->projects()

Method	Description
`list()`	List all projects
`get(string $uuid)`	Get project by UUID
`create(?string $name, ?string $description)`	Create a new project
`update(string $uuid, ?string $name, ?string $description)`	Update a project
`delete(string $uuid)`	Delete a project
`listEnvironments(string $uuid)`	List environments for a project
`getEnvironment(string $uuid, string $environmentNameOrUuid)`	Get a specific environment
`createEnvironment(string $uuid, string $name)`	Create an environment
`deleteEnvironment(string $uuid, string $environmentNameOrUuid)`	Delete an environment

$project = $coolify->projects()->create(
    name: 'E-Commerce',
    description: 'Production e-commerce stack',
);

$coolify->projects()->createEnvironment(
    uuid: 'project-uuid',
    name: 'staging',
);

Deployments

$coolify->deployments()

Method	Description
`list()`	List all deployments
`get(string $uuid)`	Get deployment by UUID
`deploy(?string $tag, ?string $uuid, ?bool $force, ?int $pr)`	Trigger a deployment
`cancel(string $uuid)`	Cancel a running deployment
`listByApplication(string $uuid, ?int $skip, ?int $take)`	List deployments for a specific application

$coolify->deployments()->deploy(uuid: 'app-uuid', force: true);

$history = $coolify->deployments()->listByApplication(
    uuid: 'app-uuid',
    take: 10,
)->json();

Teams

$coolify->teams()

Method	Description
`list()`	List all teams
`get(int $id)`	Get team by ID
`getMembers(int $id)`	Get team members
`current()`	Get the current team
`currentMembers()`	Get current team members

$team = $coolify->teams()->current()->json();
$members = $coolify->teams()->currentMembers()->json();

Private Keys

$coolify->privateKeys()

Method	Description
`list()`	List all private keys
`get(string $uuid)`	Get private key by UUID
`create(string $privateKey, ?string $name, ?string $description)`	Create a private key
`update(string $privateKey, ?string $name, ?string $description)`	Update a private key
`delete(string $uuid)`	Delete a private key

$coolify->privateKeys()->create(
    privateKey: file_get_contents('/path/to/id_rsa'),
    name: 'Deploy Key',
    description: 'Production server deploy key',
);

Cloud Tokens

$coolify->cloudTokens()

Method	Description
`list()`	List all cloud tokens
`get(string $uuid)`	Get cloud token by UUID
`create(string $provider, string $token, string $name)`	Create a cloud token
`update(string $uuid, ?string $name)`	Update a cloud token
`delete(string $uuid)`	Delete a cloud token
`validate(string $uuid)`	Validate a cloud token

$coolify->cloudTokens()->create(
    provider: 'hetzner',
    token: 'hcloud-api-token',
    name: 'Hetzner Production',
);

GitHub Apps

$coolify->gitHubApps()

Method	Description
`list()`	List all GitHub Apps
`create(...)`	Register a new GitHub App
`update(int $githubAppId, ...)`	Update a GitHub App
`delete(int $githubAppId)`	Delete a GitHub App
`loadRepositories(int $githubAppId)`	Load repositories from a GitHub App
`loadBranches(int $githubAppId, string $owner, string $repo)`	Load branches for a repository

$repos = $coolify->gitHubApps()->loadRepositories(githubAppId: 42)->json();
$branches = $coolify->gitHubApps()->loadBranches(
    githubAppId: 42,
    owner: 'my-org',
    repo: 'my-repo',
)->json();

Hetzner

$coolify->hetzner()

Method	Description
`locations(?string $cloudProviderTokenUuid)`	Get available Hetzner locations
`serverTypes(?string $cloudProviderTokenUuid)`	Get available server types
`images(?string $cloudProviderTokenUuid)`	Get available images
`sshKeys(?string $cloudProviderTokenUuid)`	Get SSH keys
`createServer(...)`	Create a Hetzner server

$locations = $coolify->hetzner()->locations('token-uuid')->json();

$coolify->hetzner()->createServer(
    location: 'fsn1',
    serverType: 'cx22',
    image: 114690387,
    privateKeyUuid: 'key-uuid',
    cloudProviderTokenUuid: 'token-uuid',
    name: 'web-01',
);

Resources

$coolify->resources()

Method	Description
`list()`	List all resources (applications, databases, services)

$allResources = $coolify->resources()->list()->json();

Data Transfer Objects

The SDK provides readonly DTO classes in the Coolify\Data namespace for typed access to API responses. Each class has a static fromArray() factory method that maps snake_case API keys to camelCase properties.

Class	Description
`ApplicationData`	Application details (git config, build pack, health checks, limits, etc.)
`ApplicationDeploymentQueueData`	Deployment queue entry with status, logs, commit info
`EnvironmentData`	Project environment (id, name, project association)
`EnvironmentVariableData`	Environment variable with preview/literal/multiline flags
`PrivateKeyData`	SSH private key metadata
`ProjectData`	Project with UUID, name, description
`ServerData`	Server with IP, proxy config, nested `ServerSettingData`
`ServerSettingData`	Server settings (build concurrency, sentinel, log drains, etc.)
`ServiceData`	Service with Docker Compose config and metadata
`TeamData`	Team with nested `UserData` members array
`UserData`	User profile (name, email, 2FA status)

Usage example:

use Coolify\Data\ApplicationData;

$response = $coolify->applications()->get('app-uuid');
$app = ApplicationData::fromArray($response->json());

echo $app->name;          // "My App"
echo $app->gitBranch;     // "main"
echo $app->buildPack;     // "nixpacks"
echo $app->status;        // "running"

Server with nested settings:

use Coolify\Data\ServerData;

$response = $coolify->servers()->get('server-uuid');
$server = ServerData::fromArray($response->json());

echo $server->name;                          // "production-01"
echo $server->ip;                            // "10.0.0.1"
echo $server->settings?->isBuildServer;      // false
echo $server->settings?->isReachable;        // true

Error Handling

The SDK uses the AlwaysThrowOnErrors Saloon trait, which means any non-2xx API response automatically throws a Coolify\Exceptions\CoolifyException.

use Coolify\Exceptions\CoolifyException;

try {
    $coolify->applications()->get('non-existent-uuid');
} catch (CoolifyException $e) {
    echo $e->getMessage();            // "Resource not found."
    echo $e->getResponse()->status(); // 404
}

Handling validation errors (422):

try {
    $coolify->applications()->createPublic(
        projectUuid: 'uuid',
        serverUuid: 'uuid',
        gitRepository: '',
        gitBranch: '',
        buildPack: 'nixpacks',
        portsExposes: '3000',
    );
} catch (CoolifyException $e) {
    if ($e->getResponse()->status() === 422) {
        $errors = $e->getValidationErrors();
        // ['git_repository' => ['The git repository field is required.'], ...]
    }
}

Status code mapping:

Status	Message
400	Invalid token.
401	Unauthenticated.
404	Resource not found.
422	Validation error.
429	Rate limit exceeded. Please try again later.

Architecture

CoolifyConnector
├── applications()  → ApplicationsResource  → 19 Request classes → Coolify API
├── databases()     → DatabasesResource     → 22 Request classes → Coolify API
├── services()      → ServicesResource       → 14 Request classes → Coolify API
├── servers()       → ServersResource        → 8 Request classes  → Coolify API
├── projects()      → ProjectsResource       → 9 Request classes  → Coolify API
├── deployments()   → DeploymentsResource    → 5 Request classes  → Coolify API
├── teams()         → TeamsResource          → 5 Request classes  → Coolify API
├── privateKeys()   → PrivateKeysResource    → 5 Request classes  → Coolify API
├── cloudTokens()   → CloudTokensResource    → 6 Request classes  → Coolify API
├── gitHubApps()    → GitHubAppsResource     → 6 Request classes  → Coolify API
├── hetzner()       → HetznerResource        → 5 Request classes  → Coolify API
├── resources()     → ResourcesResource      → 1 Request class    → Coolify API
├── version()       ─────────────────────────────────────────────→ Coolify API
├── enable()        ─────────────────────────────────────────────→ Coolify API
├── disable()       ─────────────────────────────────────────────→ Coolify API
└── healthcheck()   ─────────────────────────────────────────────→ Coolify API

The SDK follows a layered architecture built on top of Saloon v4:

CoolifyConnector — the entry point. Configures base URL, Bearer token authentication, JSON headers, and the AlwaysThrowOnErrors trait. Returns resource instances.
*Resource — resource classes (extend Saloon\Http\BaseResource) that group related API operations and provide a fluent, typed interface.
*Request — individual Saloon request classes (one per API endpoint) that define the HTTP method, endpoint path, query parameters, and JSON body.
CoolifyResponse — extends Saloon's Response to throw CoolifyException on failure.
CoolifyException — extends Saloon's RequestException with human-readable status messages and structured validation error access.
Coolify\Data\* — readonly DTO classes for typed response deserialization.

License

This package is open-sourced software licensed under the MIT license.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
config		config
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json
coolify-api.yml		coolify-api.yml

Folders and files

Latest commit

History

Repository files navigation

Coolify SDK for PHP

Requirements

Installation

Configuration

Laravel

Standalone (without Laravel)

Quick Start

Using the Facade (Laravel)

Using Dependency Injection (Laravel)

Standalone Usage

API Resources Reference

General

Applications

Databases

Services

Servers

Projects

Deployments

Teams

Private Keys

Cloud Tokens

GitHub Apps

Hetzner

Resources

Data Transfer Objects

Error Handling

Architecture

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages