# Coolify e Claude Code: implemente um projeto no seu próprio VPS
> Instalação do Coolify, ligação ao GitHub, implementação de Next.js, domínio e HTTPS, MCP, requisitos de VPS e resolução de problemas. Preços técnicos denominados em dólares e limitações originais.
Source: https://ailoot.ai/blog/pt-pt/coolify-claude-code-deploy/
Canonical: https://ailoot.ai/blog/pt-pt/coolify-claude-code-deploy/
Language: pt-PT
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-087
Revision: sha256-308a729398eb6d3cfe6ee74fca47835b67b8c1a38cd3d348f237284f00d769f7
[Documentação Ailoot](https://ailoot.ai/docs/) — materiais de referência para trabalhar com o serviço.
## Limitações da plataforma e condições de pagamento em 2026
Principal conclusão
Os planos gratuitos funcionam até ultrapassar um limite pela primeira vez; depois disso, é necessário um cartão internacional. A Heroku encerrou o seu plano gratuito para todos em 2022 e entrou em modo de manutenção em fevereiro de 2026. Com o Coolify alojado por si, o servidor é seu; não existe faturação por utilizador nem dependência do fornecedor.
Um cenário típico de vibe coder em 2026: cria um MVP no Cursor ou Claude Code numa noite, passa-o para um repositório GitHub, abre vercel.com → liga o repositório → chega ao ecrã de subscrição → introduz o cartão → recebe `Transaction declined`.
Isto não é um erro nem uma interrupção temporária.
Railway, Render, Heroku — a história é a mesma. A Heroku encerrou mesmo o seu plano gratuito para todos em 2022 e, em fevereiro de 2026, o projeto entrou em modo de manutenção — sem novas funcionalidades nem novos contratos Enterprise. Para um utilizador com um cartão não suportado, isto significa: «a porta está fechada; contorne-a através de um intermediário que cobra uma comissão de 20%».
Pode pagar através de cartões Visa virtuais no Cazaquistão ou de serviços de pagamento empresariais. Mas isso significa +20% ao preço, +30 minutos em cada transação e o risco de a sua conta ser bloqueada quando o processador de pagamentos detetar uma incompatibilidade entre países.
O exemplo original incluía três tentativas — na Vercel Pro, na Railway e na Render.
## O que é o Coolify e como funciona uma plataforma alojada por si?
Principal conclusão
O Coolify é uma PaaS de código aberto que pode alojar por si e uma alternativa direta à Heroku, Vercel e Netlify. Instala-se com um único comando curl em qualquer VPS com Ubuntu. Nos bastidores, utiliza Docker + Traefik para encaminhamento por proxy inverso e Let's Encrypt para HTTPS. Suporta integração com o GitHub, webhooks para implementações automáticas, cópias de segurança S3 e mais de 280 serviços instaláveis com um clique (PostgreSQL, Redis, MinIO). A versão alojada por si é gratuita para sempre e sem limites. Tem 55 800 estrelas no GitHub e uma licença Apache-2.0.
O Coolify é um projeto de código aberto criado com Laravel + Docker que transforma qualquer VPS vazio numa plataforma de implementação de aplicações. Instale o Coolify uma vez e, depois, faça tudo o resto através da interface Web: ligue o GitHub, escolha um repositório e clique em Deploy.
A documentação oficial resume-o de forma breve e precisa:
O Coolify é uma alternativa de código aberto à Heroku / Netlify / Vercel, etc., que pode alojar por si.
— README do GitHub do Coolify, https://github.com/coollabsio/coolify
Nos bastidores, o Coolify é composto por quatro partes:
1. **Interface Web criada com Laravel 12 + Livewire 3 + Tailwind v4** — um painel para gerir as suas aplicações.
2. **Docker + Docker Compose** — cada aplicação é executada num contentor, isolada das restantes.
3. **Proxy inverso (Traefik ou Caddy)** — recebe tráfego HTTP/HTTPS e encaminha-o para os contentores.
4. **Integração com Let's Encrypt** — emite e renova automaticamente certificados SSL para todos os domínios.
Funcionalidades principais que tornam o Coolify funcionalmente comparável à Vercel:
| Funcionalidade | Vercel | Coolify |
|----|----|----|
| Implementação automática ao fazer git push | ✅ | ✅ (através de webhook do GitHub) |
| HTTPS gratuito | ✅ | ✅ (Let's Encrypt) |
| Implementações de pré-visualização de PR | ✅ | ✅ (através da GitHub App) |
| Interface para variáveis de ambiente | ✅ | ✅ |
| Cópias de segurança de bases de dados | ❌ (não inclui bases de dados próprias) | ✅ (para armazenamento compatível com S3) |
| PostgreSQL / Redis / MongoDB | \$20+/mês cada | ✅ Instalação com um clique, gratuita |
| Tarefas agendadas (cron) | ❌ | ✅ (sintaxe cron) |
| Faturação por utilizador | \$20/utilizador/mês | Nenhuma |
| Dependência do fornecedor | Elevada (Edge Functions, ISR) | Zero (o seu Docker) |
| CDN global | ✅ | ❌ (apenas o seu VPS) |
Uma CDN global é a única coisa que o Coolify não inclui de origem. Essa é a resposta honesta. Se o seu projeto tiver um público global e precisar de reduzir a latência para utilizadores nos EUA e na Europa, coloque a Cloudflare à frente; é gratuita para conteúdo estático.
Preço: **a versão alojada por si é gratuita para sempre**, sem limites quanto ao número de aplicações, servidores ou implementações. O Coolify Cloud está disponível por \$5/mês para 2 servidores + \$3 por cada servidor adicional — mas os próprios servidores continuam a ser seus; o Coolify Cloud limita-se a alojar o painel.
A versão mais recente é a **v4.1.0, de 18 de maio de 2026**. As novas funcionalidades incluem o build pack Railpack em beta, registos de auditoria, diferenças de configuração entre implementações e um endpoint MCP nativo (só de leitura). Fonte: [versões no GitHub](https://github.com/coollabsio/coolify/releases).
## Que VPS deve escolher para o Coolify em 2026?
Principal conclusão
O Coolify requer, no mínimo, 2 vCPU, 2 GB de RAM, 30 GB SSD e Ubuntu LTS (20.04, 22.04 ou 24.04). Um VPS com estas características consegue executar confortavelmente 3–5 projetos criados com vibe coding em simultâneo.
Os requisitos mínimos do Coolify vêm diretamente da [documentação oficial](https://coolify.io/docs/get-started/installation):
| Parâmetro | Mínimo | Recomendado |
|-------------|----------------------------------|---------------------------|
| CPU | 2 núcleos | 2–4 núcleos |
| RAM | 2 GB | 4 GB (com margem para compilações) |
| Armazenamento | 30 GB | 50–80 GB (para imagens + bases de dados) |
| Arquitetura | AMD64 ou ARM64 (64 bits) | AMD64 |
| SO | Ubuntu LTS 20.04 / 22.04 / 24.04 | 22.04 LTS |
| Root | Obrigatório | Através de chave SSH, não de palavra-passe |
O mínimo — 2 GB de RAM — é um **limite inferior rígido**. Com 1 GB, o instalador chega ao Docker, fica sem memória (OOM) e bloqueia. Não poupe na RAM.
Fontes de preços: [Timeweb Cloud](https://timeweb.cloud/services/vds-vps), [FirstVDS](https://firstvds.ru/products/vds_vps_hosting) e [Selectel](https://selectel.ru/services/cloud/vps-vds/).
Se precisar de mais potência (uma base de dados de 100 GB, várias instâncias Postgres), escolha Aeza Dedicated.
O que NÃO deve escolher:
- **VPS partilhado com 512 MB–1 GB de RAM** — não chega nem para o Coolify. É indicado para sites estáticos em nginx, não para uma PaaS.
Quer não só configurar a implementação, mas também criar uma **configuração que torne o Claude fiável**? O Coolify é uma ferramenta de execução, mas sem contexto estruturado ([`CLAUDE.md`](https://ailoot.ai/blog/pt-pt/claude-md-template/), um [segundo cérebro](https://ailoot.ai/blog/pt-pt/claude-code-second-brain/) e [engenharia de contexto](https://ailoot.ai/blog/pt-pt/context-engineering/)), o Claude continuará a alucinar em tarefas longas. A configuração completa inclui os três elementos: **clone de IA + segundo cérebro + engenharia de contexto** — esta combinação transforma o Claude de «um assistente que alucina» numa ferramenta fiável.
## Como instalar o Coolify em 5 minutos
Principal conclusão
A instalação é feita com um único comando curl da documentação. Quando arranca, aparece uma interface Web na porta 8000. Aí, cria o primeiro utilizador administrador e vê um painel vazio. O tempo real entre uma instalação Ubuntu vazia e o Coolify em funcionamento é de 5–7 minutos, dos quais 3–4 minutos são gastos em `apt-get install docker`. O script obtém as dependências necessárias e configura o Docker; só precisa de esperar que termine.
**Passo 1. Ligue-se ao VPS por SSH.**
Depois de criar um VPS junto do fornecedor, o endereço IP do servidor e a palavra-passe root aparecerão num e-mail ou no painel de controlo. Ligue-se a partir do seu computador local:
```bash
ssh root@1.2.3.4
```
Se o fornecedor lhe tiver dado uma chave SSH em vez de uma palavra-passe, ligue-se com `-i path/to/key`. A partir daqui, parto do princípio de que está perante uma instalação limpa do Ubuntu 22.04 ou 24.04 LTS.
**Passo 2. Execute o comando de instalação do Coolify.**
Um comando da [documentação oficial](https://coolify.io/docs/get-started/installation):
```bash
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash
```
O script faz três coisas:
1. Verifica o sistema (Ubuntu LTS? root? AMD64?)
2. Instala o Docker e o Docker Compose, se ainda não estiverem instalados
3. Transfere as imagens do Coolify (`coolify/coolify`, `coolify/realtime`, `traefik`) e executa-as em segundo plano através de docker-compose
Isto demora 3–5 minutos. Verá os registos de `apt-get` a passar, seguidos de `docker pull`. Quando aparecer `Coolify v4.1.0 is now running`, avance para o passo 3.
**Passo 3. Abra a interface Web.**
Abra isto no seu browser:
```
http://1.2.3.4:8000
```
O Coolify apresentará um assistente de configuração — um formulário para criar o primeiro utilizador. Introduza um e-mail e uma palavra-passe e guarde-os. Este utilizador torna-se automaticamente administrador; ainda não precisa de outros utilizadores.
Depois de guardar, chegará a um painel vazio: uma barra lateral à esquerda com Resources / Projects / Servers / Sources / Notifications / Settings e, ao centro, uma mensagem para «Add your first resource».
**Passo 4. Abra portas na firewall do fornecedor (não no UFW).**
O Coolify já está em execução, mas, do exterior, só a porta 8000 (o painel) está acessível. Para permitir que os utilizadores acedam às suas aplicações, tem de abrir as portas 80 (HTTP) e 443 (HTTPS):
| Porta | Finalidade |
|----|----|
| 22 | Acesso SSH ao servidor |
| 80 | Recebe tráfego HTTP, necessário para a validação do Let's Encrypt |
| 443 | Recebe tráfego HTTPS dos utilizadores |
| 8000 | Painel do Coolify (vamos fechar esta porta depois de configurar um domínio personalizado para o painel) |
Uma armadilha importante indicada na documentação oficial:
O Docker utiliza regras iptables baseadas em NAT que podem contornar firewalls Linux tradicionais, como o UFW.
— Documentação do Coolify (firewall), https://coolify.io/docs/knowledge-base/server/firewall
Isto significa que, mesmo que ative o UFW e feche todas as portas, o Docker continuará a expor os seus contentores através do iptables. O UFW não serve de nada neste caso. A solução é **abrir e fechar portas no painel de controlo do fornecedor**, não através do UFW. Na Timeweb / Selectel / Aeza, faz-se isto na secção «Network → Firewall» da consola Web.
**Passo 5 (opcional). Associe o painel ao seu domínio.**
Para visitar `https://coolify.example.com` em vez de `http://1.2.3.4:8000`, crie um registo DNS A `coolify.example.com → 1.2.3.4`, aceda a **Settings → Instance Settings → Instance Domain** no Coolify, introduza o seu subdomínio e guarde. O Coolify solicitará um certificado Let's Encrypt e, um minuto depois, recarregará o painel através de HTTPS.
Depois disso, pode fechar a porta 8000 na firewall — o painel ficará disponível por HTTPS na porta padrão 443.
## Como ligar o GitHub: App ou PAT?
Principal conclusão
O Coolify suporta duas formas de ligar ao GitHub: **GitHub App** (recomendada) e **Personal Access Token (PAT)**. Use a GitHub App: a configuração demora 5 minutos com o assistente, as pré-visualizações de PR funcionam e as permissões podem ser limitadas com precisão ao nível do repositório. PAT é uma opção desatualizada para casos antigos; não permite implementações de pré-visualização e implica o risco de acesso global a todos os seus repositórios. A documentação oficial afirma diretamente: «para 95% dos utilizadores, a GitHub App é a escolha certa».
No Coolify, aceda a **Sources → + Add → GitHub App**. O Coolify apresentará um assistente com três ecrãs:
1. **Name & description** — dê um nome à origem (introduza `github-main`) e, opcionalmente, adicione uma descrição.
2. **Configure on GitHub** — um botão que o leva ao GitHub.com e abre automaticamente um formulário de criação de GitHub App com as permissões corretas.
3. **Confirm** — depois de regressar do GitHub, clique em «Save».
No segundo passo, o GitHub pedir-lhe-á que confirme as permissões solicitadas pelo Coolify:
| Permissão | Nível | Finalidade |
|-----------------|------------|----------------------------------------------|
| Contents | Só de leitura | Clonar o repositório |
| Pull Requests | Leitura e escrita | Criar implementações de pré-visualização e comentar PRs |
| Email addresses | Só de leitura | Identificar commits |
| Metadata | Só de leitura | Listar repositórios |
Estas são **permissões mínimas** — a GitHub App não consegue ver as suas chaves privadas, não consegue escrever em `main` e não pode aceder a repositórios que não tenha ligado explicitamente.
Da documentação oficial:
Personal Access Token (PAT) é o método antigo; **recomendo que não o utilize**. Desvantagens:
- PAT concede acesso global a todos os seus repositórios (incluindo os privados)
- As pré-visualizações de PR não funcionam — essa funcionalidade é exclusiva da GitHub App
- O token dura muito tempo (90 dias, um ano ou indefinidamente) — se for exposto, é um problema
Utilize PAT apenas se trabalhar com um repositório de uma organização cuja política de segurança proíba GitHub Apps e não houver forma de contornar essa restrição.
Depois de guardar a origem no Coolify, verá a GitHub App no painel, com uma lista dos repositórios ligados. Quando criar uma nova aplicação, poderá selecionar qualquer um deles com um clique.
## Como implementar um projeto Next.js do Claude Code em 6 passos
Principal conclusão
O percurso completo, desde uma configuração vazia do Claude Code até um site em funcionamento: 1) execute `claude` numa pasta vazia, descreva o projeto e o Claude gera o código; 2) execute `git init && git remote add` (o Claude pode fazê-lo por si através de um comando slash); 3) envie as alterações para o GitHub; 4) no Coolify, escolha «+ New Resource → Application» e selecione o repositório; 5) adicione variáveis de ambiente; 6) clique em Deploy. O Coolify detetará que é Next.js, escolherá o build pack Nixpacks, criará uma imagem Docker em 3–5 minutos e fornecerá um domínio temporário no formato `YOUR_TEMPORARY_DOMAIN` com HTTPS incluído de origem.
**Passo 1. Descreva o projeto ao Claude Code numa pasta vazia.**
```bash
mkdir my-vibe-app
cd my-vibe-app
git init
claude
```
Na sessão:
```
Cria um projeto Next.js 14 app router:
- uma página inicial com uma lista de utilizadores
- o endpoint /api/users devolve um array da base de dados
- Postgres através de Prisma
- Tailwind para os estilos
- .env.example com DATABASE_URL
- README.md com instruções para executar o projeto
```
O Claude irá gerar a estrutura de ficheiros, package.json, prisma/schema.prisma e .env.example. Peça também:
```
Cria um Dockerfile para compilações de produção e um .dockerignore.
```
Isto é opcional — o Coolify compila com Nixpacks mesmo sem um Dockerfile. Mas um Dockerfile dá-lhe controlo sobre o processo e é mais rápido para projetos maiores.
**Passo 2. Crie um repositório GitHub e envie-lhe o projeto.**
Pode fazê-lo manualmente através da interface do GitHub + `git remote add origin ...`, mas o Claude Code pode fazê-lo por si:
```
/commit-push-pr Initial Next.js app generated with Claude Code
```
Ou diga simplesmente: «Commit everything and push it to a new repository `my-vibe-app` under my account.» O Claude utilizará o CLI `gh` para criar um repositório privado (ou público) e fazer o primeiro push. Fonte: [comando oficial do Claude Code](https://github.com/anthropics/claude-code/blob/main/.claude/commands/commit-push-pr.md).
**Passo 3. Crie uma aplicação no Coolify.**
No painel do Coolify, clique em **+ New → Application**. Abrir-se-á um formulário:
1. **Source** — selecione `github-main` (a GitHub App que ligou na secção H2 anterior)
2. **Repository** — selecione `my-vibe-app` na lista
3. **Branch** — `main`
4. **Build Pack** — o Coolify detetá-lo-á automaticamente. Se existir um Dockerfile, usará `dockerfile`. Caso contrário, usará `nixpacks`. Pode substituir esta opção manualmente.
5. **Domain** — deixe o valor sugerido (`YOUR_TEMPORARY_DOMAIN`) por agora; é temporário e irá substituí-lo pelo seu mais tarde
6. **Port** — `3000` por predefinição para Next.js
Guarde.
**Passo 4. Adicione variáveis de ambiente.**
Na aplicação criada, abra o separador **Environment Variables**. Adicione as variáveis uma a uma:
```
DATABASE_URL=postgresql://user:pass@db-host:5432/mydb
NODE_ENV=production
ANTHROPIC_API_KEY=sk-ant-...
```
Se não tiver uma base de dados, crie uma diretamente no Coolify: **+ New → Database → PostgreSQL**. O Coolify iniciará um contentor Postgres em 30 segundos e fornecerá uma DATABASE_URL interna no formato `postgresql://postgres:pass@postgres-xyz:5432/postgres` — introduza-a na aplicação.
Todas as variáveis são encriptadas na base de dados do Coolify e não são apresentadas nos registos de compilação.
**Passo 5. Clique em Deploy.**
No canto superior direito, há um botão azul Deploy. Os registos em tempo real aparecerão no separador Logs:
```
[stage: clone] Cloning ''
[stage: build] Detected Next.js, using Nixpacks
[stage: build] Installing Node 20, npm 10
[stage: build] npm install (245s)
[stage: build] npm run build (87s)
[stage: deploy] Creating container my-vibe-app-xyz
[stage: deploy] Container started, health check passed
[stage: proxy] Traefik routing configured for YOUR_TEMPORARY_DOMAIN
[stage: ssl] Let's Encrypt cert issued for YOUR_TEMPORARY_DOMAIN
```
A primeira compilação demora 3–5 minutos (transfere a imagem base do Node e instala as dependências). As compilações seguintes demoram 60–90 segundos graças à cache de camadas do Docker.
Quando o estado mudar para **Running**, copie o URL da aplicação no campo **Domains** do Coolify e abra esse endereço exato no navegador. Use-o como `` abaixo; o texto entre sinais de maior e menor é um marcador, não um endereço real.
**Passo 6. Verifique se tudo funciona.**
Abra o URL da aplicação do passo anterior com `/api/users` acrescentado, por exemplo `/api/users`, sem duplicar a barra. É o endpoint JSON criado no passo 1; o URL raiz é a página inicial. Se ocorrer um erro 500, verá o stack trace no separador Logs. O problema mais comum numa primeira implementação é a DATABASE_URL apontar para uma base de dados inexistente. Resolva-o criando uma instância PostgreSQL no Coolify (consulte o passo 4 acima) e substituindo a DATABASE_URL.
15 minutos, a contar do momento em que encomenda o VPS. No exemplo original, este fluxo demorou 12–18 minutos num servidor acabado de instalar.
## Como configurar um domínio personalizado e HTTPS
Principal conclusão
Um domínio personalizado liga-se em 3 passos: crie um registo DNS A que aponte para o IP do servidor, introduza o seu domínio na configuração do Coolify em vez do domínio temporário, ative Automatic HTTPS e clique em Redeploy. O Let's Encrypt emitirá automaticamente um certificado SSL 2–3 minutos após a propagação do DNS (normalmente 5–30 minutos). O requisito principal é que o DNS já resolva quando clicar em Redeploy; caso contrário, a validação do Let's Encrypt falhará e terá de esperar 12 minutos antes de tentar novamente.
**Passo 1. Crie um registo DNS A no painel de controlo do seu registador.**
Os exemplos originais utilizam domínios alojados na Reg.ru, Beget ou Timeweb. O processo é o mesmo:
| Tipo de registo | Nome | Valor |
|------------|---------------------------|------------------------|
| A | `app` (ou `@` para a raiz) | `1.2.3.4` (IP do servidor) |
Guarde-o, abra uma consola e verifique:
```bash
dig app.example.com +short
# Deveria devolver 1.2.3.4
```
Se não devolver nada ou devolver um IP diferente, o DNS ainda não se propagou. Aguarde 5–30 minutos.
**Passo 2. Introduza o seu domínio no Coolify.**
Na aplicação, abra o separador **Configuration → General**. No campo **Domains**, substitua o URL temporário da aplicação copiado do Coolify por `https://app.example.com` (usando o seu domínio configurado). Ative **Automatic HTTPS** (normalmente já está ativo por predefinição).
Guarde e clique em **Redeploy**.
**Passo 3. Aguarde pelo certificado Let's Encrypt.**
Os registos de compilação mostrarão:
```
[stage: ssl] Requesting Let's Encrypt cert for app.example.com
[stage: ssl] HTTP challenge sent to /.well-known/acme-challenge/xxx
[stage: ssl] Validation passed, cert issued
[stage: ssl] Cert installed, HTTPS enabled
```
Em 2–3 minutos, o seu site estará disponível em `https://app.example.com` com um cadeado verde na barra de endereço.
O que pode correr mal com o Let's Encrypt (os 3 problemas mais comuns indicados no [guia oficial de resolução de problemas](https://coolify.io/docs/troubleshoot/dns-and-domains/lets-encrypt-not-working)):
1. **A porta 80 está fechada na firewall.** O Let's Encrypt valida através de um HTTP challenge — envia um pedido para `http://app.example.com/.well-known/acme-challenge/xxx`. Sem a porta 80, a validação não será aprovada. Abra-a na firewall do fornecedor.
2. **O proxy da Cloudflare está ativado (nuvem laranja).** Interceta o pedido do Let's Encrypt e devolve a sua própria página de marcador — a validação falha. A solução é mudar para «DNS only» (nuvem cinzenta) ou configurar um challenge DNS-01 através da API da Cloudflare.
3. **O DNS ainda não se propagou.** Se criou um registo A há 30 segundos e clicou imediatamente em Redeploy, o Let's Encrypt não encontrará o seu domínio. Aguarde 5–30 minutos para que o DNS se propague pelos servidores.
Limite de frequência do Let's Encrypt: **5 tentativas falhadas por hora para um domínio**, com recuperação à taxa de 1 a cada 12 minutos. Se atingir o limite, não clique em Redeploy 10 vezes seguidas; verifique os registos, resolva o problema e tente novamente dentro de 12 minutos.
## Como usar um agente de inteligência artificial no Claude Code para gerir o Coolify? {#como-gere-o-claude-code-o-coolify-através-de-mcp}
Principal conclusão
Através do Model Context Protocol, o Claude Code obtém acesso direto à API do Coolify — pode dizer «implemente esta aplicação» para iniciar uma compilação, verificar o estado, ler registos ou atualizar variáveis de ambiente. Há três opções: forsonny/Coolify-MCP-Server (básica, 7 categorias de operações), dazeb/coolify-mcp-enhanced (mais de 15 ferramentas adicionais, incluindo implementação de bases de dados com um clique) e ajmcclary/Coolify-Manager (uma Claude Skill criada em torno do CLI oficial). A partir da v4.1.0 (18 de maio de 2026), o Coolify disponibiliza um endpoint MCP nativo sem servidores de terceiros — mas, por enquanto, é só de leitura.
O Model Context Protocol (MCP) é uma norma da Anthropic que permite ao Claude Code comunicar com sistemas externos (consulte o [guia sobre servidores MCP](https://ailoot.ai/blog/pt-pt/mcp-servers-claude-code/) para saber mais). Ligue um servidor MCP e o Claude recebe um conjunto de ferramentas que pode invocar. Existem três servidores prontos a usar para o Coolify, além de uma opção nativa.
**Opção 1. forsonny/Coolify-MCP-Server-for-Claude-Code — básica.**
O que pode fazer:
- **Aplicações:** criar, iniciar, parar, reiniciar
- **Serviços:** listar, criar, iniciar/parar/reiniciar
- **Implementações:** ver as em execução, obter por UUID
- **Equipas e membros:** listar, obter informações
- **Chaves SSH:** listar, criar
- **Variáveis de ambiente:** CRUD completo para aplicações e serviços
- **Informações do servidor:** domínios por servidor, estado de saúde, versão
Instalação:
```bash
git clone ''
cd Coolify-MCP-Server-for-Claude-Code
npm install
npm run build
# Em .env:
# COOLIFY_BASE_URL=https://coolify.example.com
# COOLIFY_API_TOKEN=[do Coolify Settings → API Tokens]
npm run setup # configura automaticamente o Claude Code
```
Depois, pode escrever isto no Claude Code:
```
Mostra o estado da aplicação my-vibe-app no Coolify e as 3 implementações mais recentes.
```
O Claude devolverá uma tabela.
**Opção 2. dazeb/coolify-mcp-enhanced — melhorada (recomendada).**
O que acrescenta ao conjunto básico:
- **Implementação de PostgreSQL / Redis / MinIO com um clique** através de IA — peça «configura o Postgres por mim» e cria um contentor e devolve a DATABASE_URL
- **Monitorização em tempo real + utilização de recursos** — CPU/RAM de cada aplicação em tempo real
- **Atualizações em lote da configuração env** — atualize 20 variáveis com um comando
- **Suporte para Docker Compose** — implementar aplicações com vários serviços
Configuração para Claude Code (`.mcp.json` na raiz do projeto):
```json
{
"mcpServers": {
"coolify-enhanced": {
"command": "node",
"args": ["/path/to/coolify-mcp-enhanced/dist/index.js"],
"env": {
"COOLIFY_ACCESS_TOKEN": "your-token-here",
"COOLIFY_BASE_URL": "https://coolify.example.com"
}
}
}
}
```
**Opção 3. ajmcclary/Coolify-Manager — uma Claude Skill criada em torno do CLI.**
Não é um servidor MCP, mas sim uma Claude Code Skill que envolve o CLI oficial do Coolify. Inclui:
- Diagnóstico de estado de serviços e contentores
- Diagnóstico de certificados SSL
- Suporte para várias instâncias (se tiver vários servidores Coolify)
- Receitas para resolução de problemas
Instalação: transfira a skill e coloque-a em `~/.claude/skills/coolify-manager/`. O Claude Code irá detetá-la e sugeri-la para tarefas relevantes.
**Opção 4 (nova em maio de 2026). MCP nativo no Coolify v4.1.0.**
O registo de alterações da v4.1.0, datado de 18 de maio de 2026, diz:
> Foi adicionado suporte MCP ao nível da instância, com ferramentas só de leitura para recursos do Coolify e para a API/UI.
O Coolify disponibiliza agora o seu próprio endpoint MCP — pode ligar o Claude Code diretamente, sem servidores de terceiros. Por enquanto, é **só de leitura** (listas de aplicações, estados, configurações), sem operações de alteração. Mas isso é suficiente para a maioria das tarefas, como «diz-me o que há na infraestrutura».
Ligue-o através de `.mcp.json`:
```json
{
"mcpServers": {
"coolify-native": {
"url": "https://coolify.example.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}
```
Aguarde pelo acesso completo de escrita no MCP nativo na v4.2 ou v4.3 — a equipa do Coolify prometeu disponibilizá-lo até ao final de 2026.
## 5 armadilhas na primeira implementação — e como evitá-las
Principal conclusão
Os erros mais comuns numa primeira implementação são RAM insuficiente, porta 80 fechada, proxy da Cloudflare a impedir o Let's Encrypt, UFW sem conseguir proteger o Docker e escolha de PAT em vez de GitHub App. Todos estão documentados nos guias oficiais, mas é fácil deparar-se com eles sem experiência prática. Segue-se uma lista de verificação em 5 pontos, baseada na experiência original da primeira instalação do Coolify.
**Armadilha 1: Menos de 2 GB de RAM — a instalação falha com OOM.**
Sintoma: `curl install.sh` chega a `docker pull coolify/coolify`, bloqueia nos 70% e, depois, o processo é terminado com `Killed (signal 9)`. Os registos de `dmesg | tail` mostram `Out of memory: Killed process`.
Solução:
```bash
# Crie um ficheiro de swap de 4 GB para resolver temporariamente o problema
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
```
A longo prazo, atualize para 4 GB de RAM. O Coolify funciona com swap, mas as compilações de projetos Next.js grandes podem falhar.
**Armadilha 2: O UFW está ativado, mas o Docker continua a abrir portas.**
Sintoma: ativou o UFW e fechou todas as portas, exceto a 22, mas a sua aplicação continua acessível pela Internet numa porta aleatória (como a 3000).
O motivo, segundo a [documentação oficial](https://coolify.io/docs/knowledge-base/server/firewall):
O Coolify é executado no Docker, que utiliza regras iptables baseadas em NAT e pode contornar firewalls Linux tradicionais, como o UFW.
— Documentação do Coolify (firewall), https://coolify.io/docs/knowledge-base/server/firewall
Solução: utilize a **firewall do painel de controlo do fornecedor**, não o UFW. A Timeweb / Selectel / Aeza têm uma secção «Firewall» ou «Network → Firewall», onde configura regras ao nível da rede virtual — estas são aplicadas antes de os pacotes chegarem ao Docker.
Uma alternativa é o ufw-docker, um script que corrige o UFW para ser compatível com o Docker. Mas isso é mais complicado do que clicar no painel de controlo.
**Armadilha 3: O proxy da Cloudflare (nuvem laranja) impede o Let's Encrypt.**
Sintoma: depois de clicar em Redeploy, os registos mostram `Let's Encrypt validation failed - challenge returned 403`.
Motivo: a Cloudflare encaminha o pedido HTTP do Let's Encrypt e devolve a sua própria página em vez do ficheiro de validação.
Solução — escolha uma de duas opções:
1. **Mude para «DNS only»** (a nuvem cinzenta na Cloudflare). Desvantagem: perde a CDN e a proteção da Cloudflare.
2. **Configure um challenge DNS-01 através da API da Cloudflare.** No Coolify, aceda a Settings → SSL Configuration, selecione o fornecedor Cloudflare e introduza um token API com permissões Zone:Read e DNS:Edit. O Let's Encrypt validará através de um registo TXT em vez de HTTP.
A segunda opção é mais complicada de configurar, mas mantém o proxy da Cloudflare.
**Armadilha 4: PAT em vez de GitHub App — as pré-visualizações de PR não funcionam.**
Sintoma: ligou o GitHub através de um Personal Access Token; tudo funciona, mas não são criadas implementações de pré-visualização para PRs. Abriu um PR no GitHub, mas não apareceu nada no Coolify.
Motivo: as pré-visualizações de PR são uma funcionalidade exclusiva da GitHub App. PAT não recebe eventos `pull_request` através de um webhook.
Solução: volte a ligar o GitHub através da App. Sources → Add → GitHub App → conclua o assistente. Pode eliminar a origem PAT antiga.
**Armadilha 5: «Coolify == Vercel» não é totalmente verdade.**
O que o Coolify **não faz** de origem:
| Vercel | Coolify | O que fazer |
|----|----|----|
| CDN global | Não | Coloque a Cloudflare à frente (gratuita para conteúdo estático) |
| Incremental Static Regeneration | Não | `revalidatePath` funciona apenas no seu servidor |
| Otimização de imagens | Não | Utilize `next/image` com um loader local ou Cloudflare Images |
| Escalabilidade automática nos picos | Não | Aumente a escala manualmente; atualize o seu VPS |
| Edge Functions | Não | Utilize rotas API normais |
Se o seu projeto for um SaaS de tráfego elevado, com público global e requisitos de latência de \< 100 ms em todo o mundo, o Coolify não é adequado; escolha Vercel Enterprise. Se é um vibe coder com um MVP que está a testar com 100–1 000 utilizadores por dia, o Coolify cobre tudo.
De uma análise honesta de alojamento próprio:
Os 15 minutos do título deste guia referem-se ao percurso sem imprevistos da primeira implementação de um projeto. A configuração completa da infraestrutura, com monitorização, cópias de segurança e alertas, demora uma ou duas noites. Seja honesto consigo próprio.
## Quanto poupará num ano em comparação com a Vercel?
Os valores Vercel seguintes são estimativas dos cenários do artigo em maio de 2026, não cotações atuais. São apenas um lado da comparação. O Coolify alojado por si não tem licença paga, mas VPS, cópias de segurança, armazenamento, tráfego e operação custam dinheiro. Obtenha uma cotação que cumpra os requisitos acima; os cenários não fornecem um preço numérico de VPS, pelo que não sustentam uma poupança fixa.
Seja **C** a fatura mensal total de infraestrutura do VPS escolhido, armazenamento de cópias, tráfego adicional, monitorização e eventual painel pago. Conte cada despesa uma única vez. Seja **r** o custo horário de operação, usando sempre a mesma moeda. A estimativa de tempo do artigo é de 5–10 horas iniciais mais 1–2 horas mensais: **17–34 horas no primeiro ano** e **12–24 horas nos anos seguintes**.
| Cenário | Estimativa Vercel/mês | Vercel/ano | Infraestrutura Coolify/mês | TCO Coolify no primeiro ano, com trabalho | Poupança no primeiro ano face à Vercel |
|----|----|----|----|----|----|
| Um protótipo, 100 000 visitas/mês | $20 base + ~$5 tráfego = $25 | $300 | C | 12C + (17–34)r | $300 − 12C − (17–34)r |
| Cinco projetos num VPS | $20 base + $30 tráfego/funções = $50 | $600 | C | 12C + (17–34)r | $600 − 12C − (17–34)r |
| Três programadores, cinco projetos | $60 lugares + $30 tráfego = $90 | $1,080 | C | 12C + (17–34)r | $1,080 − 12C − (17–34)r |
Use um C diferente em cada cenário se as cargas precisarem de servidores diferentes. Para comparação mensal, distribua a configuração inicial por 12 meses: o equivalente mensal do primeiro ano é **C + (17–34)r/12**. O TCO dos anos seguintes é **12C + (12–24)r**. As fórmulas comparam a estimativa Vercel declarada com as despesas de alojamento próprio; inclua também custos de operação comparáveis no lado Vercel. Poupança negativa significa maior custo de alojamento próprio com os valores introduzidos. Não volte a contar o salário integral do mesmo engenheiro se r já o incluir.
Antes de mudar, preencha C com uma cotação real e um plano de cópias, escolha r e compare a utilização efetiva durante um mês. Sem esses valores, o artigo fornece um modelo de custos, não uma poupança em dólares.
O principal benefício não é o dinheiro. Ao mudar para o Coolify, **desaparece a categoria «dependência da política de pagamentos de terceiros»**.
O Coolify não é uma Vercel mais barata. É uma categoria de produto diferente: é proprietário da infraestrutura, assume a responsabilidade por ela e poupa dinheiro aceitando a sua complexidade.
Se implementar um protótipo for a sua primeira tarefa depois de o gerar no Claude Code, a gestão do ambiente (env, segredos, tarefas agendadas, cópias de segurança) faz parte da [**engenharia de contexto**](https://ailoot.ai/blog/pt-pt/context-engineering/). Sem uma estrutura que indique «onde está tudo», o Claude perde-se e perde tempo em cada alteração. A configuração completa inclui: **clone de IA** ([Skills](https://ailoot.ai/blog/pt-pt/claude-code-skills-library/) e [Subagents](https://ailoot.ai/blog/pt-pt/claude-code-subagents/) adaptados à sua metodologia) + [**segundo cérebro**](https://ailoot.ai/blog/pt-pt/claude-code-second-brain/) (a base de conhecimento do projeto) + **engenharia de contexto** ([Plan Mode](https://ailoot.ai/blog/pt-pt/claude-code-plan-mode/), `/compact`, ambiente de execução). Estes são os **3 pilares** sem os quais a IA alucina.
### Fontes
- [Documentação oficial do Coolify: Introdução](https://coolify.io/docs/get-started/introduction)
- [Guia de instalação do Coolify](https://coolify.io/docs/get-started/installation)
- [Visão geral dos build packs do Coolify](https://coolify.io/docs/applications/build-packs/overview)
- [Base de conhecimento do Coolify sobre firewalls](https://coolify.io/docs/knowledge-base/server/firewall)
- [Resolução de problemas com Let's Encrypt no Coolify](https://coolify.io/docs/troubleshoot/dns-and-domains/lets-encrypt-not-working)
- [Preços do Coolify](https://coolify.io/pricing)
- [GitHub do Coolify: versões v4.1.0](https://github.com/coollabsio/coolify/releases)
- [Visão geral do Claude Code](https://code.claude.com/docs/en/overview)
- [VPS Timeweb Cloud](https://timeweb.cloud/services/vds-vps)
- [VPS FirstVDS](https://firstvds.ru/products/vds_vps_hosting)
- [VPS/VDS Selectel](https://selectel.ru/services/cloud/vps-vds/)
- [Preços da Vercel](https://vercel.com/pricing)
O fluxo completo de contexto: **clone de IA + segundo cérebro + engenharia de contexto**.
Há mais materiais disponíveis em [Ailoot](https://ailoot.ai/).
## Perguntas frequentes
### Que URL deve devolver JSON depois da implementação?
Copie o URL da aplicação apresentado no campo Domains do Coolify e abra o caminho /api/users. O URL raiz é a página inicial; /api/users é o endpoint JSON especificado no projeto de exemplo.
### Como calculo se o alojamento próprio poupa dinheiro?
Some em C os custos mensais de VPS, cópias, armazenamento, tráfego, monitorização e painel opcional. O TCO do primeiro ano é 12C mais 17–34 horas ao seu custo horário; compare com a estimativa anual Vercel do cenário e inclua custos de operação comparáveis em ambos os lados.
## Ailoot · A empresa e a sua carteira de projetos
A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.
A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.
A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.