Coolify CLI

The Coolify v5 architecture manages a fleet of mesh-connected hosts using a centralized UI/API and per-host agents called coold.

Key Components

• Coolify Central UI/API: The command center. It routes commands to specific hosts using host_id. It listens for outbound TLS connections (:443) from agents.
• coold (Per-host agent): The local agent running on every host. It dials outbound to Central (or an optional gateway) via WSS/gRPC bidi streams. It never accepts inbound connections from the internet or Central, allowing it to work through NAT and firewalls.
• Podman: The container runtime. coold interacts with Podman exclusively through the local /run/podman/podman.sock via a bind-mount. The raw socket is never exposed on a TCP network.
• Per-customer Gateway (Optional): For large-scale deployments, a single host in a mesh can act as a stream aggregator. It dials Central once and proxies commands to other coold agents over the WireGuard (wg0) mesh, reducing the connection load on Central.

Connectivity Model

• Outbound-only: Agents (coold) initiate all connections to Central. This ensures scalability and security.
• Intra-mesh REST API: coold exposes a local REST API on the WireGuard (wg0) management IP (port :8443). This is accessible only to intra-mesh callers (like the coolify firewall CLI or other agents in the same mesh) and is never reachable from the public internet.

┌─────────────────────────────────────┐
│  Coolify central UI / API           │
└────────────────────▲────────────────┘
                     │ outbound TLS :443 (WSS / gRPC bidi)
                     │
   ┌─────────────────┴──────────────────┐
   │      (per-customer gateway,        │
   │       OPTIONAL — one mesh host     │
   └─────────────────▲──────────────────┘
                     │
┌────────────────────┴────────────────┐  ┌─────────────────────────┐
│  coold (per-host agent)             │  │  /run/podman/podman.sock│
└─────────────────────────────────────┘  └─────────────┬───────────┘
                                                      ▼
                                         ┌─────────────────────────────┐
                                         │  podmand (containers, nets) │
                                         └─────────────────────────────┘

Coolify uses an internal DNS system for service discovery.

• TLD: The default Top-Level Domain is .coolify.internal (configurable per-cluster).
• Mechanism: coold manages a local DNS socket on the bridge gateway IP. When a service is registered, its IP is gossiped via Corrosion and becomes resolvable via DNS.
• TTL: The DNS TTL is set to 5s. This provides a balance between fast failover and DNS stability.
• Multi-replica: The resolver returns all healthy A records. Applications should use connection pools (e.g., standard Postgres or Redis clients) to handle multiple targets naturally.

Important Note for Developers: Applications must implement reconnection logic. When a container is redeployed, its IP changes; the application's client must re-resolve the DNS name to find the new IP. Applications with infinite-cache DNS resolvers (like certain Java configurations) will fail to see updates.

The Coolify CLI uses a layered architecture to separate user interaction from API communication. This design ensures that the CLI can manage multiple Coolify instances, handle complex business logic, and provide flexible output formats without tightly coupling the command-line interface to the underlying API.

Architecture Layers

1. Command Layer (cmd/): Handles CLI parsing, flag validation, and user interaction.
2. Service Layer (internal/service/): Implements business logic, validates requests, and transforms API responses into CLI-friendly formats.
3. API Client Layer (internal/api/): Manages HTTP communication, including authentication (Bearer tokens), retry logic with exponential backoff, and error handling.
4. Configuration Layer (internal/config/): Manages multi-instance settings and token storage.
5. Output Layer (internal/output/): Formats data for the terminal (Table, JSON, or Pretty JSON).
6. Models Layer (internal/models/): Defines the data structures (Servers, Projects, etc.) used throughout the application.

The Coolify v5 architecture separates high-level application logic from low-level host management through three primary layers:

1. Central Coolify (SaaS/Self-hosted): The brain of the system. It handles RBAC, tenant scoping, business audit logs, scheduling, ingress templating, and application-aware logic (Compose, Dockerfiles, Nixpacks). It communicates with hosts via an outbound WSS/gRPC bi-directional stream.
2. coold (Host Agent): A lightweight agent running on each host. It is the only process with access to the local podman socket and the sole writer of kernel firewall rules. It acts as the auth/privilege boundary. It exposes a local REST API on the wg0 management IP (http://100.64.0.X:8443) for intra-mesh callers like the coolify firewall CLI.
3. SSH (Provisioning Channel): Used exclusively for the initial host installation and re-convergence (running coolify init commands). It is not used for steady-state runtime control.

Persistence Model:

• Bootstrap State: Managed via idempotent coolify init runs.
• Rule Metadata: Stored in the central Coolify DB (audit logs, RBAC, etc.).
• Kernel Rules: Programmed by coold and mirrored to /etc/coolify/allow.rules for persistence across reboots via the coolify-mesh-allow.service.

The Coolify central database is the authoritative source of truth for the desired state of firewall rules. The coold service on each host is responsible for making the kernel's live state match that truth.

The Write Sequence:

1. Central DB Update: The central server writes the rule to its database first.
2. Command Dispatch: Central sends the rule (src, dst, proto, port) to coold via an established stream.
3. Kernel Application: coold applies the rule using iptables -A/-D.
4. Snapshot Generation: coold regenerates /etc/coolify/allow.rules via iptables-save.
5. Acknowledgment: coold returns success to Central.

Error Handling:

• If a crash occurs between kernel application and snapshot generation, the rule is lost on reboot. However, the Central Reconcile Loop periodically compares the Central DB against the live kernel (iptables -S COOLIFY-ALLOW) and re-pushes any missing rules to ensure convergence.