PHPackages                             sq-dev/coolify-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. sq-dev/coolify-sdk

ActiveLibrary[API Development](/categories/api)

sq-dev/coolify-sdk
==================

Coolify.io api integration

v1.0.0(3mo ago)119↓90%MITPHP

Since Mar 26Pushed 3mo agoCompare

[ Source](https://github.com/sq-dev/coolify-sdk)[ Packagist](https://packagist.org/packages/sq-dev/coolify-sdk)[ RSS](/packages/sq-dev-coolify-sdk/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (1)Dependencies (2)Versions (2)Used By (0)

Coolify SDK for PHP
===================

[](#coolify-sdk-for-php)

A fully-typed PHP SDK for the [Coolify](https://coolify.io) API, built on [Saloon v4](https://docs.saloon.dev). Provides a clean, fluent interface to manage applications, databases, services, servers, deployments, and more — with first-class Laravel integration.

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- [Saloon](https://docs.saloon.dev) ^4.0
- [illuminate/support](https://github.com/illuminate/support) ^10.0 | ^11.0 | ^12.0 | ^13.0

Installation
------------

[](#installation)

```
composer require sq-dev/coolify-sdk
```

Configuration
-------------

[](#configuration)

### Laravel

[](#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)

[](#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
-----------

[](#quick-start)

### Using the Facade (Laravel)

[](#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)

[](#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

[](#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
-----------------------

[](#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

[](#general)

Methods available directly on the connector:

MethodDescription`version()`Get Coolify version`healthcheck()`Health check`enable()`Enable API`disable()`Disable API```
$coolify->version()->json();       // "4.x.x"
$coolify->healthcheck()->json();   // "OK"
```

---

### Applications

[](#applications)

`$coolify->applications()`

MethodDescription`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

[](#databases)

`$coolify->databases()`

MethodDescription`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

[](#services)

`$coolify->services()`

MethodDescription`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

[](#servers)

`$coolify->servers()`

MethodDescription`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

[](#projects)

`$coolify->projects()`

MethodDescription`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

[](#deployments)

`$coolify->deployments()`

MethodDescription`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

[](#teams)

`$coolify->teams()`

MethodDescription`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

[](#private-keys)

`$coolify->privateKeys()`

MethodDescription`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

[](#cloud-tokens)

`$coolify->cloudTokens()`

MethodDescription`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

[](#github-apps)

`$coolify->gitHubApps()`

MethodDescription`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

[](#hetzner)

`$coolify->hetzner()`

MethodDescription`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

[](#resources)

`$coolify->resources()`

MethodDescription`list()`List all resources (applications, databases, services)```
$allResources = $coolify->resources()->list()->json();
```

---

Data Transfer Objects
---------------------

[](#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.

ClassDescription`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
--------------

[](#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:**

StatusMessage400Invalid token.401Unauthenticated.404Resource not found.422Validation error.429Rate limit exceeded. Please try again later.---

Architecture
------------

[](#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](https://docs.saloon.dev):

- **`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
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance82

Actively maintained with recent releases

Popularity8

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity34

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

91d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e2a8fade5f2d40f4410f5e9963992b315ea635543f6686bf0d8bf2b21bd8f0b5?d=identicon)[sq-dev](/maintainers/sq-dev)

---

Top Contributors

[![ifedeev](https://avatars.githubusercontent.com/u/130277787?v=4)](https://github.com/ifedeev "ifedeev (3 commits)")

### Embed Badge

![Health badge](/badges/sq-dev-coolify-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/sq-dev-coolify-sdk/health.svg)](https://phpackages.com/packages/sq-dev-coolify-sdk)
```

###  Alternatives

[saloonphp/laravel-plugin

The official Laravel plugin for Saloon

806.6M187](/packages/saloonphp-laravel-plugin)[rapidez/core

Rapidez Core

1822.4k65](/packages/rapidez-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)