Coolify

Coolify v5 is architected as a distributed system with three primary layers. The flow of intent and execution moves from the user/API through a central control plane, which then communicates with host-level agents to manage infrastructure.

The Data Flow Path:

1. User / API / Git webhook: Initiates intent or triggers updates.
2. Coolify Laravel control plane: Manages application state and user intent.
3. Flux: Acts as a router, receiving commands from the control plane via HTTP over /run/coolify/flux.sock and forwarding them via outbound gRPC Agent.Stream.
4. coold: The agent running on each host that executes specific host primitives (Podman, networks, firewall, DNS, Corrosion, builder).

User / API / Git webhook
        ↓
Coolify Laravel control plane
        ↓ HTTP over /run/coolify/flux.sock
Flux
        ↓ outbound gRPC Agent.Stream
coold on each host
        ↓
Podman / networks / firewall / DNS / Corrosion / builder

Coolify v5 is architected as three distinct building blocks to separate product logic, connectivity, and privileged host execution:

1. Coolify Laravel control plane: Manages user intent, durable product state, RBAC, deployment state machines, placement decisions, secrets, proxy configuration rendering, notifications, and audit logs.
2. Flux: Acts as the connectivity broker. It manages long-lived agent streams. The Laravel control plane communicates with Flux via a Unix socket, while coold agents connect to Flux via outbound gRPC. Flux is responsible for routing typed primitive requests to connected hosts and resolving pending responses.
3. coold: A host agent that runs once per host. It manages privileged local execution (Podman, firewall, DNS, Corrosion, and host facts) and exposes a closed set of host primitives. It does not allow raw Podman passthrough; all operations must be explicit primitives with validation.

This separation allows hosts to reside behind NAT (since coold dials out to Flux) and isolates privileged host access to the agent.

The Coolify component acts as the central orchestrator and business logic layer. It manages the high-level product model and user-facing state.

Key Responsibilities:

• Identity & Access: Users, teams, roles, RBAC, API tokens, sessions, and SSO/OAuth.
• Resource Management: Projects, environments, applications, services, databases, and servers.
• Configuration: Resource settings (source, image, build settings, env vars, domains, ports, health checks, resource limits, volumes, schedules, webhooks).
• Lifecycle Management: Deployment state machines (pending, building, pulling, creating, starting, health waiting, cutover, running, failed, rollback, cleanup) and placement/scheduling decisions.
• Infrastructure Intent: Proxy/ingress configuration rendering, TLS intent, and secret storage (encryption, resolution, and injection at deploy time).
• Observability & Business: Business audit, event history, deployment logs, user-facing status, notifications, billing/subscriptions, and cloud-provider integration.

Coolify is designed to allow authenticated users with deployment permissions to execute custom commands during the resource lifecycle. These commands run with the privileges available to the specific deployment environment.

Because these commands are an intentional feature of the deployment configuration, an authorized user executing their own configured commands is not considered a security vulnerability.

Expected use cases for deployment commands include:

• Running package manager commands (e.g., npm install, composer install) during install or build phases.
• Chaining shell commands for complex deployment workflows.
• Running database migrations or framework-specific commands (e.g., php artisan migrate) during pre-deployment or post-deployment phases.
• Utilizing shell features necessary for the application's specific deployment process.

Security boundaries: A security vulnerability is only present if a report demonstrates a bypass of Coolify's authorization boundaries, such as:

• Gaining cross-team access.
• Executing commands without the required deployment permissions.
• Leakage of secrets belonging to other users.
• Unintended access outside the documented deployment trust boundary.

In Coolify v5, Flux serves as the central connection broker that bridges the gap between the Coolify Laravel application and the coold agents running on managed hosts. This architecture allows Coolify to manage hosts located behind NAT, firewalls, or corporate networks.

How it works

• Laravel to Flux: The Coolify Laravel application communicates with Flux via a local Unix socket.
• coold to Flux: Managed host agents (coold) establish an outbound authenticated gRPC stream to Flux.
• Routing: Flux maintains a registry of connected host streams. When Laravel sends a request, Flux routes it to the appropriate host stream, tracks pending request IDs, and resolves the typed responses back to Laravel.

Responsibilities of Flux (Transport Layer)

Flux is strictly a transport-layer component and manages:

• Stream lifecycle and request correlation.
• Timeouts and handling of disconnected hosts.
• Pending-request caps and late-result handling.
• Host-agent authentication for inbound coold streams.
• Transport-level errors (e.g., disconnected host, timeout, or pending-cap overflow).

What Flux is NOT (Product Layer)

To maintain a clean separation of concerns, Flux does not handle Coolify product logic. It treats commands like containers.start or images.pull as raw protocol frames rather than business actions. Flux does not manage:

• User permissions (RBAC) or billing.
• Deployment state or rollback logic.
• Domain management or secrets.
• Application placement (deciding which host runs which app).

In Coolify v5, coold is a per-host agent designed with a narrow, explicit primitive surface. It acts as the bridge between the Laravel control plane and the local host runtime.

Core Responsibilities

coold is responsible for local runtime integration and host safety, including:

• Podman access: Managing container operations via explicit primitives (not raw passthrough).
• Service Discovery: Syncing service discovery and embedded DNS.
• Corrosion: Handling Corrosion writes for host endpoints.
• Host Facts: Reporting local host state.
• Firewall: Managing firewall mutation and reconciliation.

Separation of Concerns

To maintain security and architectural clarity, coold follows strict boundary rules:

Integration Pattern

coold executes host-local operations requested through Flux. It reports typed results back to the control plane and must not expose raw Podman commands; instead, every operation must use an explicit primitive with validation and a stable protocol shape.

When developing or extending Coolify v5, use the responsibility split to decide whether a new feature belongs in the Coolify core, the Flux routing layer, or the coold host agent.

Decision Rule of Thumb

Boundary Test

If an operation could be reused by a different orchestrator using its own app model, it belongs in coold. If the operation only makes sense within the context of Coolify's specific product model, it belongs in Coolify.