Loading
Also from Kynth Studios
Also from Kynth Studios
Also from Kynth Studios
1# AGENTS.md23This file provides guidance to agentic coding tools when working with code in this repository.45## Project Overview67Coolify is an open-source, self-hostable PaaS (alternative to Heroku/Netlify/Vercel). It manages servers, applications, databases, and services via SSH. Built with Laravel 12 (using Laravel 10 file structure), Livewire 3, and Tailwind CSS v4.89## Design Reference1011For UI/UX design specifications, principles, and visual standards, consult the local [`DESIGN.md`](DESIGN.md). It is the source of truth for frontend design work in this repository.1213## Development Environment1415Docker Compose-based dev setup with services: coolify (app), postgres, redis, soketi (WebSockets), vite, testing-host, mailpit, minio.1617```bash18# Start dev environment (uses docker-compose.dev.yml)19docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d20docker compose -f docker-compose.yml -f docker-compose.dev.yml down # stop services2122# Two local Coolify instances (isolated stacks; server transfer / multi-control-plane)23./scripts/dev-instances up # a:8000 + b:8001 (uses npm run build for CSS/JS)24./scripts/dev-instances up a --with vite # HMR only when starting a single instance25./scripts/dev-instances urls26./scripts/dev-instances down27# Compose: docker-compose.dev-multi.yml Env: .dev-instances/{a,b}.env (gitignored)28# Note: dual Vite HMR is unsupported (shared public/hot); multi-instance always uses public/build.29```3031The app runs at `localhost:8000` by default. Instance **b** is on `8001` (db `5433`, redis `6380`, …); see `./scripts/dev-instances`.3233## Testing the Self-Hosted Upgrade Process3435Use the following workflow to test a self-hosted upgrade:36371. Install the source version with the upgrade script:3839```bash40 bash upgrade.sh sha-6492d081362c009519481ac70e50873e39ba186141```42432. Set the current Coolify version and rebuild the cached configuration:4445```bash46 docker exec -e COOLIFY_VERSION=4.3.0 coolify php artisan config:cache47```48493. In the Coolify UI, click **Check for Updates**.504. Confirm that an upgrade is available, then click **Upgrade** and verify that the upgrade completes successfully.5152## Common Commands5354```bash55# Tests (Pest 4)56php artisan test --compact # all tests57php artisan test --compact --filter=testName # single test58php artisan test --compact tests/Feature/SomeTest.php # specific file5960# Code formatting (Pint, Laravel preset)61vendor/bin/pint --dirty --format agent # format changed files6263# Frontend64npm run dev # vite dev server65npm run build # production build66```6768## Browser Tests (Pest Browser Plugin)6970Uses `pestphp/pest-plugin-browser` with Laravel Dusk 8. New browser tests go in `tests/v4/Browser/`.7172```bash73# Run all browser tests74php artisan test --compact tests/v4/Browser/7576# Run a specific browser test file77php artisan test --compact tests/v4/Browser/LoginTest.php7879# Run a specific test by name80php artisan test --compact --filter='can login with valid credentials'81```8283### Writing Browser Tests8485- Place new tests in `tests/v4/Browser/` — legacy Dusk tests in `tests/Browser/` should not be used as reference.86- Use `RefreshDatabase` and seed required data (at minimum `InstanceSettings::create(['id' => 0])`) in `beforeEach`.87- Key API: `visit()`, `fill(field, value)`, `click(text)`, `assertSee()`, `assertDontSee()`, `assertPathIs()`, `screenshot()`.88- Always call `screenshot()` at the end of each test for debugging.89- For authenticated tests, create a helper function that logs in via the UI:9091```php92function loginAsRoot(): mixed93{94 return visit('/login')95 ->fill('email', 'test@example.com')96 ->fill('password', 'password')97 ->click('Login');98}99```100101- See `tests/v4/Browser/LoginTest.php`, `tests/v4/Browser/DashboardTest.php`, and `tests/v4/Browser/RegistrationTest.php` for conventions.102- Chrome driver runs on `localhost:4444`, app on `localhost:8000` (configured in `tests/DuskTestCase.php`).103- Legacy Dusk macros in `app/Providers/DuskServiceProvider.php` use the old `type()`/`press()` API — do not mix with Pest Browser Plugin's `fill()`/`click()` API.104105## Architecture106107### Backend Structure (app/)108- **Actions/** — Domain actions organized by area (Application, Database, Docker, Proxy, Server, Service, Shared, Stripe, User, CoolifyTask, Fortify). Uses `lorisleiva/laravel-actions` with `AsAction` trait — actions can be called as objects, dispatched as jobs, or used as controllers.109- **Livewire/** — All UI components (Livewire 3). Pages organized by domain: Server, Project, Settings, Security, Notifications, Terminal, Subscription, SharedVariables. This is the primary UI layer — no traditional Blade controllers. Components listen to private team channels for real-time status updates via Soketi.110- **Jobs/** — Queue jobs for deployments (`ApplicationDeploymentJob`), backups, Docker cleanup, server management, proxy configuration. Uses Redis queue with Horizon for monitoring.111- **Models/** — Eloquent models extending `BaseModel` which provides auto-CUID2 UUID generation. Key models: `Server`, `Application`, `Service`, `Project`, `Environment`, `Team`, plus standalone database models (`StandalonePostgresql`, `StandaloneMysql`, etc.). Common traits: `HasConfiguration`, `HasMetrics`, `HasSafeStringAttribute`, `ClearsGlobalSearchCache`.112- **Services/** — Business logic services (ConfigurationGenerator, DockerImageParser, ContainerStatusAggregator, HetznerService, etc.). Use Services for complex orchestration; use Actions for single-purpose domain operations.113- **Helpers/** — Global helpers loaded via `bootstrap/includeHelpers.php` from `bootstrap/helpers/` — organized into `shared.php`, `constants.php`, `versions.php`, `subscriptions.php`, `domains.php`, `docker.php`, `services.php`, `github.php`, `proxy.php`, `notifications.php`.114- **Data/** — Spatie Laravel Data DTOs (e.g., `ServerMetadata`).115- **Enums/** — PHP enums (TitleCase keys). Key enums: `ProcessStatus`, `Role` (MEMBER/ADMIN/OWNER with rank comparison), `BuildPackTypes`, `ProxyTypes`, `ContainerStatusTypes`.116- **Rules/** — Custom validation rules (`ValidGitRepositoryUrl`, `ValidServerIp`, `ValidHostname`, `DockerImageFormat`, etc.).117118### API Layer119- REST API at `/api/v1/` with OpenAPI 3.0 attributes (`use OpenApi\Attributes as OA`) for auto-generated docs120- Authentication via Laravel Sanctum with custom `ApiAbility` middleware for token abilities (read, write, deploy)121- `ApiSensitiveData` middleware masks sensitive fields (IDs, credentials) in responses122- API controllers in `app/Http/Controllers/Api/` use inline `Validator` (not Form Request classes)123- Response serialization via `serializeApiResponse()` helper124125### Authorization126- Policy-based authorization with ~15 model-to-policy mappings in `AuthServiceProvider`127- Custom gates: `createAnyResource`, `canAccessTerminal`128- Role hierarchy: `Role::MEMBER` (1) < `Role::ADMIN` (2) < `Role::OWNER` (3) with `lt()`/`gt()` comparison methods129- Multi-tenancy via Teams — team auto-initializes notification settings on creation130131### Event Broadcasting132- Soketi WebSocket server for real-time updates (ports 6001-6002 in dev)133- Status change events: `ApplicationStatusChanged`, `ServiceStatusChanged`, `DatabaseStatusChanged`, `ProxyStatusChanged`134- Livewire components subscribe to private team channels via `getListeners()`135136### Key Domain Concepts137- **Server** — A managed host connected via SSH. Has settings, proxy config, and destinations.138- **Application** — A deployed app (from Git or Docker image) with environment variables, previews, deployment queue.139- **Service** — A pre-configured service stack from templates (`templates/service-templates-latest.json`).140- **Standalone Databases** — Individual database instances (Postgres, MySQL, MariaDB, MongoDB, Redis, Clickhouse, KeyDB, Dragonfly).141- **Project/Environment** — Organizational hierarchy: Team → Project → Environment → Resources.142- **Proxy** — Traefik reverse proxy managed per server.143144### Instance sentinels (`id = 0`)145146Coolify seeds **instance-owned** rows at primary key `0`. That value is a sentinel meaning “this is the Coolify instance itself”, not a normal autoincrement id. Do not migrate, resequence, or “fix” these to a positive id.147148| Record | Model / lookup | Meaning |149|---|---|---|150| Root team | `Team::find(0)`, `team_id === 0` | Instance / root team. Cloud billing and many skip-checks exempt `team_id === 0`. |151| Localhost server | `Server::find(0)` / `findOrFail(0)` | The machine running Coolify. Upgrades, instance backups, and docker inspect target this server. |152| Instance settings | `InstanceSettings` with `id = 0` | Singleton settings row. Tests must seed `InstanceSettings::create(['id' => 0])` (or `forceCreate`). |153| Instance Postgres | `StandalonePostgresql` `id = 0`, name `coolify-db` | Coolify’s own database. UI treats `database_id === 0` as the instance DB (e.g. hide delete on backup screens). |154| Local docker dest | `StandaloneDocker` `id = 0` | Destination on the localhost server (`destination_id = 0`). |155| Root user / default GitHub App | seeders | First-install defaults. |156157**Do not assign `id = 0` to new or non-instance rows.** In particular, `ScheduledDatabaseBackup` and `ScheduledTask` are ordinary schedules. Legacy installs may still have a `coolify-db` backup at `id = 0`; resolve that backup via the `coolify-db` relation / uuid, not `ScheduledDatabaseBackup::find(0)`.158159`0` is a PHP/Eloquent landmine (`empty(0)` is true; keyset pagination `where('id', '>', $cursor)` starting at `0` skips the row). Queries that page by id must include `id = 0` on the first page (no lower bound, or cursor `< 0`). Prefer `chunkById()` over a hand-rolled `id > 0` cursor.160161### Frontend162- Livewire 3 components with Alpine.js for client-side interactivity163- Blade templates in `resources/views/livewire/`164- Tailwind CSS v4 with `@tailwindcss/forms` and `@tailwindcss/typography`165- Vite for asset bundling166167### Laravel 10 Structure (NOT Laravel 11+ slim structure)168- Middleware in `app/Http/Middleware/` — custom middleware includes `CheckForcePasswordReset`, `DecideWhatToDoWithUser`, `ApiAbility`, `ApiSensitiveData`169- Kernels: `app/Http/Kernel.php`, `app/Console/Kernel.php`170- Exception handler: `app/Exceptions/Handler.php`171- Service providers in `app/Providers/`172173## Key Conventions174175- Use `php artisan make:*` commands with `--no-interaction` to create files176- Use Eloquent relationships, avoid `DB::` facade — prefer `Model::query()`177- PHP 8.5: constructor property promotion, explicit return types, type hints178- Validation uses inline `Validator` facade in controllers/Livewire components and custom rules in `app/Rules/` — not Form Request classes179- Run `vendor/bin/pint --dirty --format agent` before finalizing changes180- Every change must have tests — write or update tests, then run them. For bug fixes, follow TDD: write a failing test first, then fix the bug (see Test Enforcement below)181- Check sibling files for conventions before creating new files182183## Git Workflow184185- Production branch: `main`186- Development branch: `next`187- Fix PRs should target the current production branch; feature PRs should target `next`188189<laravel-boost-guidelines>190=== foundation rules ===191192# Laravel Boost Guidelines193194The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to ensure the best experience when building Laravel applications.195196## Foundational Context197198This application is a Laravel application and its main Laravel ecosystems package & versions are below. You are an expert with them all. Ensure you abide by these specific packages & versions.199200- php - 8.5201- laravel/fortify (FORTIFY) - v1202- laravel/framework (LARAVEL) - v12203- laravel/horizon (HORIZON) - v5204- laravel/mcp (MCP) - v0205- laravel/nightwatch (NIGHTWATCH) - v1206- laravel/pail (PAIL) - v1207- laravel/prompts (PROMPTS) - v0208- laravel/sanctum (SANCTUM) - v4209- laravel/socialite (SOCIALITE) - v5210- livewire/livewire (LIVEWIRE) - v3211- laravel/boost (BOOST) - v2212- laravel/dusk (DUSK) - v8213- laravel/pint (PINT) - v1214- pestphp/pest (PEST) - v4215- phpunit/phpunit (PHPUNIT) - v12216- rector/rector (RECTOR) - v2217- tailwindcss (TAILWINDCSS) - v4218219## Skills Activation220221This project has domain-specific skills available in `**/skills/**`. You MUST activate the relevant skill whenever you work in that domain—don't wait until you're stuck.222223## Conventions224225- You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming.226- Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`.227- Check for existing components to reuse before writing a new one.228229## Verification Scripts230231- Do not create verification scripts or tinker when tests cover that functionality and prove they work. Unit and feature tests are more important.232233## Application Structure & Architecture234235- Stick to existing directory structure; don't create new base folders without approval.236- Do not change the application's dependencies without approval.237238## Frontend Bundling239240- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `npm run build`, `npm run dev`, or `composer run dev`. Ask them.241242## Documentation Files243244- You must only create documentation files if explicitly requested by the user.245246## Replies247248- Be concise in your explanations - focus on what's important rather than explaining obvious details.249250=== boost rules ===251252# Laravel Boost253254## Tools255256- Laravel Boost is an MCP server with tools designed specifically for this application. Prefer Boost tools over manual alternatives like shell commands or file reads.257- Use `database-query` to run read-only queries against the database instead of writing raw SQL in tinker.258- Use `database-schema` to inspect table structure before writing migrations or models.259- Use `get-absolute-url` to resolve the correct scheme, domain, and port for project URLs. Always use this before sharing a URL with the user.260- Use `browser-logs` to read browser logs, errors, and exceptions. Only recent logs are useful, ignore old entries.261262## Searching Documentation (IMPORTANT)263264- Always use `search-docs` before making code changes. Do not skip this step. It returns version-specific docs based on installed packages automatically.265- Pass a `packages` array to scope results when you know which packages are relevant.266- Use multiple broad, topic-based queries: `['rate limiting', 'routing rate limiting', 'routing']`. Expect the most relevant results first.267- Do not add package names to queries because package info is already shared. Use `test resource table`, not `filament 4 test resource table`.268269### Search Syntax2702711. Use words for auto-stemmed AND logic: `rate limit` matches both "rate" AND "limit".2722. Use `"quoted phrases"` for exact position matching: `"infinite scroll"` requires adjacent words in order.2733. Combine words and phrases for mixed queries: `middleware "rate limit"`.2744. Use multiple queries for OR logic: `queries=["authentication", "middleware"]`.275276## Artisan277278- Run Artisan commands directly via the command line (e.g., `php artisan route:list`). Use `php artisan list` to discover available commands and `php artisan [command] --help` to check parameters.279- Inspect routes with `php artisan route:list`. Filter with: `--method=GET`, `--name=users`, `--path=api`, `--except-vendor`, `--only-vendor`.280- Read configuration values using dot notation: `php artisan config:show app.name`, `php artisan config:show database.default`. Or read config files directly from the `config/` directory.281282## Tinker283284- Execute PHP in app context for debugging and testing code. Do not create models without user approval, prefer tests with factories instead. Prefer existing Artisan commands over custom tinker code.285- Always use single quotes to prevent shell expansion: `php artisan tinker --execute 'Your::code();'`286 - Double quotes for PHP strings inside: `php artisan tinker --execute 'User::where("active", true)->count();'`287288=== php rules ===289290# PHP291292- Always use curly braces for control structures, even for single-line bodies.293- Use PHP 8 constructor property promotion: `public function __construct(public GitHub $github) { }`. Do not leave empty zero-parameter `__construct()` methods unless the constructor is private.294- Use explicit return type declarations and type hints for all method parameters: `function isAccessible(User $user, ?string $path = null): bool`295- Follow existing application Enum naming conventions.296- Prefer PHPDoc blocks over inline comments. Only add inline comments for exceptionally complex logic.297- Use array shape type definitions in PHPDoc blocks.298299=== deployments rules ===300301# Deployment302303- Laravel can be deployed using [Laravel Cloud](https://cloud.laravel.com/), which is the fastest way to deploy and scale production Laravel applications.304305=== tests rules ===306307# Test Enforcement308309- Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass.310- Run the minimum number of tests needed to ensure code quality and speed. Use `php artisan test --compact` with a specific filename or filter.311312=== laravel/core rules ===313314# Do Things the Laravel Way315316- Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using `php artisan list` and check their parameters with `php artisan [command] --help`.317- If you're creating a generic PHP class, use `php artisan make:class`.318- Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior.319320### Model Creation321322- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `php artisan make:model --help` to check the available options.323324## APIs & Eloquent Resources325326- For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention.327328## URL Generation329330- When generating links to other pages, prefer named routes and the `route()` function.331332## Testing333334- When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model.335- Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`.336- When creating tests, make use of `php artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests.337338## Vite Error339340- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `npm run build` or ask the user to run `npm run dev` or `composer run dev`.341342=== laravel/v12 rules ===343344# Laravel 12345346- CRITICAL: ALWAYS use `search-docs` tool for version-specific Laravel documentation and updated code examples.347- This project upgraded from Laravel 10 without migrating to the new streamlined Laravel file structure.348- This is perfectly fine and recommended by Laravel. Follow the existing structure from Laravel 10. We do not need to migrate to the new Laravel structure unless the user explicitly requests it.349350## Laravel 10 Structure351352- Middleware typically lives in `app/Http/Middleware/` and service providers in `app/Providers/`.353- There is no `bootstrap/app.php` application configuration in a Laravel 10 structure:354 - Middleware registration happens in `app/Http/Kernel.php`355 - Exception handling is in `app/Exceptions/Handler.php`356 - Console commands and schedule register in `app/Console/Kernel.php`357 - Rate limits likely exist in `RouteServiceProvider` or `app/Http/Kernel.php`358359## Database360361- When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost.362- Laravel 12 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`.363364### Models365366- Casts can and likely should be set in a `casts()` method on a model rather than the `$casts` property. Follow existing conventions from other models.367368=== livewire/core rules ===369370# Livewire371372- Livewire allow to build dynamic, reactive interfaces in PHP without writing JavaScript.373- You can use Alpine.js for client-side interactions instead of JavaScript frameworks.374- Keep state server-side so the UI reflects it. Validate and authorize in actions as you would in HTTP requests.375376=== pint/core rules ===377378# Laravel Pint Code Formatter379380- If you have modified any PHP files, you must run `vendor/bin/pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style.381- Do not run `vendor/bin/pint --test --format agent`, simply run `vendor/bin/pint --format agent` to fix any formatting issues.382383=== pest/core rules ===384385## Pest386387- This project uses Pest for testing. Create tests: `php artisan make:test --pest {name}`.388- The `{name}` argument should not include the test suite directory. Use `php artisan make:test --pest SomeFeatureTest` instead of `php artisan make:test --pest Feature/SomeFeatureTest`.389- Run tests: `php artisan test --compact` or filter: `php artisan test --compact --filter=testName`.390- Do NOT delete tests without approval.391392</laravel-boost-guidelines>393
One repository carrying more than one format is the comparison this product exists for: does anyone actually write different content in each file, or is one a copy of the other?
| Repository | Format | Stack | Covers | Score | Changed |
|---|---|---|---|---|---|
| coollabsio/coolify.cursor/rules/coolify-ai-docs.mdc · 61k | Cursor rules | buildteststylearch+5 | 92/100 | 14 days ago |
Same format, overlapping stack, ranked by quality.
| Repository | Format | Stack | Covers | Score | Changed |
|---|---|---|---|---|---|
| n8n-io/n8npackages/@n8n/agents/AGENTS.md · 201k | AGENTS.md | buildteststylearch+3 | 100/100 | 14 days ago | |
| aaif-goose/gooseAGENTS.md · 53k | AGENTS.md | setupbuildtestlint-format+7 | 100/100 | 8 days ago | |
| duckduckgo/content-scope-scriptsspecial-pages/AGENTS.md · 70 | AGENTS.md | buildteststylearch+3 | 100/100 | 14 days ago | |
| deepseek-ai/deepseek-harnessnative/landlock-run/AGENTS.md · 104k | AGENTS.md | setupteststylearch+3 | 100/100 | today | |
| code-yeongyu/oh-my-openagentpackages/web/AGENTS.md · 68k | AGENTS.md | setupbuildtestlint-format+6 | 100/100 | 13 days ago | |
| TryGhost/Ghoste2e/AGENTS.md · 55k | AGENTS.md | setupteststylearch+2 | 100/100 | today | |
| mui/material-uiAGENTS.md · 99k | AGENTS.md | setupbuildtestlint-format+9 | 100/100 | 14 days ago | |
| elastic/elasticsearchx-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/ml/AGENTS.md · 78k | AGENTS.md | buildtestlint-formatstyle+2 | 100/100 | 14 days ago |
A badge carrying the measured quality of the strongest agent config file in this repository, out of 100. It reads from this index every time somebody loads your page, so it changes when the measurement changes and there is nothing to keep up to date. Free, no account, and the value is not something you or we can set by hand.
[](https://rulestack.kynth.studio/configs/coollabsio-coolify-agents)Would rather not hotlink us? Every badge is also served in shields.io’s endpoint schema, so shields renders the image and your readers never talk to our domain:
Published by Toolproof, the masthead over this index and eight others. The method behind the number is at toolproof.kynth.studio/methodology, and the whole thing is readable as JSON with no key at /api.