cube.json fica na raiz do .zip e diz à Cube como rodar o seu projeto. Ele é opcional no painel (que detecta sozinho e mostra para você conferir), mas deixa o envio pela API automático.
cube.json
Chaves
"node" | "python" | "java" | "go" | "php" | "ruby" | "dotnet" | "elixir" | "rust" | "static"
obrigatório
A linguagem do projeto.
java roda um .jar pronto (Hospedar Java), go compila o projeto a cada envio (Hospedar Go), php instala o composer.json e serve o site sem comando (Hospedar PHP) ruby instala o Gemfile (Hospedar Ruby), dotnet publica o projeto C#, F# ou Visual Basic a cada envio (Hospedar .NET) elixir baixa e compila o projeto do mix.exs a cada envio (Hospedar Elixir) e rust compila o projeto do Cargo.toml em release a cada envio (Hospedar Rust). static é o site só de HTML: a Cube serve os arquivos, sem comando, versão nem build. Veja Hospedar um site HTML.Obrigatório em
node, python, java, ruby, dotnet e no bot php (o static não tem; no go, no rust, no elixir e no site php é opcional). O comando que inicia o projeto, como node index.js, tsx src/index.ts, npm start, python main.py, java -jar bot.jar, php bot.php, ruby bot.rb, dotnet /dados/publish/Bot.dll ou mix run --no-halt. De 1 a 500 caracteres, numa linha só. Ele roda dentro da pasta do projeto. No go e no rust, sem ele roda o programa que o build gera, /dados/bin/app (com ele, passe opções: /dados/bin/app -config prod.yml; no Rust com vários programas, /dados/bin/<nome> escolhe o de src/bin/). No elixir, sem ele roda mix run --no-halt, que sobe o projeto do mix.exs. No site php, sem ele a Cube serve o site (veja root). No dotnet, o comando roda o .dll que o build publica, com o nome do projeto: dotnet /dados/publish/<projeto>.dll; um .dll pronto roda como veio, sem build (dotnet app.dll).Quando o comando é só node <arquivo>, tsx <arquivo>, python <arquivo>, java -jar <arquivo>, php <arquivo>, ruby <arquivo> ou mix run --no-halt <arquivo>.exs, esse arquivo vira o arquivo principal do projeto (entry na API). Depois, em Configurações › Geral, o comando de início é opcional: vazio, roda o arquivo principal (o .ts, .mts ou .cts com o tsx, o TypeScript direto).Bun e Deno rodam pelo npm, com npx bun index.ts ou npx deno run -A main.ts. Veja Bun e Deno.bot é um processo sem endereço na internet (bots de Discord, workers, tarefas). site é um site ou API que recebe visitas por HTTPS. Veja Sites e APIs. Com "language": "static", o padrão é site (e bot é recusado); no php sem command, também site.A versão da linguagem. Node.js:
"20", "22", "24" ou "26". Python: "3.11", "3.12", "3.13" ou "3.14". Java: "21" ou "25". Go: "1.26" ou "1.27". PHP: "8.4" ou "8.5". Ruby: "3.4" ou "4.0". .NET: "10". Elixir: "1.20". Rust: "1.98". Sem ela, vale o Node.js 24 (a LTS), o Python 3.12, o Java 21, o Go 1.27, o PHP 8.4, o Ruby 3.4, o .NET 10, o Elixir 1.20 ou o Rust 1.98: a Recomendada do Novo projeto, que também oferece a Mais recente (a maior da lista). Com a version, o Novo projeto mostra a versão exata dela. O Node.js 20 ainda sobe, mas está fora de suporte desde 30/04/2026: não recebe mais correções de segurança.A memória do projeto, em MB. O mínimo depende do plano: bot 256 nos planos pagos e 100 no Free; site 512 em todo plano. Um projeto Java pede pelo menos 256 em qualquer plano, então não cabe no Free (
language_not_in_plan). Sem a chave, vale o mínimo do seu plano; no Java, 512 MB (ou o que sobra no plano, nunca menos de 256). Abaixo do mínimo, o envio é recusado com invalid_config (com field: "memoryMb" e o minMemoryMb do plano). A soma da memória de todos os seus projetos não pode passar a do plano: no Free, a conta tem 100 MB no total, e um bot que pede mais é recusado com insufficient_memory. Veja Planos e memória.Só para
site: a porta em que o seu app escuta, de 1024 a 65535. O app recebe o mesmo número na variável PORT. O Novo projeto não pede a porta (o app lê a PORT); para trocar depois, use Configurações › Rede (vale no próximo início).Só para
site: o nome em nome.cubehost.dev. De 3 a 32 caracteres, com letras minúsculas, números e hífen. Sem ele, a Cube gera um a partir do nome do projeto. Veja Endereço e domínios.Um comando que roda depois de instalar as dependências, como
npm run build. Sem a chave, o build é automático: se o package.json tem um script build, ele roda, no go a Cube compila a pasta do arquivo principal a cada envio, no dotnet publica o projeto (dotnet publish), no elixir roda o mix compile e no rust, o cargo build --release (até 15 minutos em qualquer plano). Use "" para não rodar nenhum build. O static não tem build, e o java não compila nada (o .jar já vem pronto). No php e no ruby, o build roda depois do composer install ou do bundle install (no Rails, o assets:precompile). No elixir, o build roda no lugar do mix compile, depois do mix deps.get (no Phoenix com assets, mix do compile + assets.deploy); no dotnet, no lugar do dotnet publish, e o command roda o .dll que ele gera (o site serve a pasta desse .dll). Com o build automático, as pastas que ele gera de novo (a .next, o bin e o obj, o target) saem do envio; com "" ou um build seu, elas ficam como vieram (veja Envie o código-fonte). O projeto mostra o build no campo build da API.O comando que instala as dependências, no lugar da instalação automática da linguagem, como
npm install --omit=dev, pip install -r requirements-prod.txt ou bundle install --without development. Sem a chave, vale a automática: npm ci (com o package-lock.json) ou npm install, pip install -r requirements.txt (sem ele, as dependências de [project].dependencies do pyproject.toml), composer install --no-dev, bundle install, go mod download ou mix deps.get --only prod. Use "" para não instalar nada. Ele roda no build do projeto, nas mesmas horas da automática (o primeiro envio, quando o arquivo das dependências muda e no Reinstalar dependências), também sem o arquivo das dependências na raiz, e o log de instalação mostra o comando (> npm install --omit=dev). De até 500 caracteres, numa linha só, sem caractere de controle (nem tabulação); fora disso, invalid_config com field: "installCommand". O static não tem. No painel, é o Comando de instalação, atrás do switch Comando personalizado (no Novo projeto e em Configurações › Geral); trocar em Configurações reinstala as dependências do zero no próximo início.No site
php sem command: a pasta que a Cube serve, como "public" ou "web"; sem ela, a public quando existe, senão a raiz. O .env, o que começa com ponto, o cube.json, os composer.* e a pasta vendor nunca são servidos (Hospedar PHP).No static: a pasta servida, a partir da raiz do .zip, como "dist" ou "site/public"; "" é a raiz. Sem ela, a pasta do index.html mais raso do .zip: a raiz quando ele está lá, ou dist quando só existe dist/index.html. Precisa ser uma pasta dentro do projeto, sem .. e sem pasta que começa com ponto; fora disso, invalid_config com field: "root".Programas do sistema que o projeto usa, de uma lista fechada, como
["poppler-utils"] para ler PDF. Veja Pacotes do sistema. Nome fora da lista é recusado com unsupported_system_package, e o static não tem pacotes.Exemplos
Os bots dos exemplos ficam semmemoryMb: entram com o mínimo do plano (256 MB nos pagos, 100 MB no Free), então o mesmo arquivo vale em qualquer plano.
- Bot Node.js
- Bot TypeScript
- Bot Python
- Site Node.js
- API Python
- Java (.jar)
- API em Go
- Site PHP (Laravel)
- Site Ruby (Sinatra)
- API em ASP.NET
- Site em Phoenix
- Site em Rust
- Bot que lê PDF
- Site HTML (build do Vite)
cube.json
Pacotes do sistema
Alguns projetos precisam de um programa do sistema, além das dependências dopackage.json ou do requirements.txt: ler PDF, converter imagem, reconhecer texto, compilar uma dependência nativa. Peça em systemPackages, com nomes desta lista:
cube.json
- Todas as linguagens com runtime (Node.js, Python, Java, Go, PHP, Ruby, .NET, Elixir e Rust) aceitam; o site estático (
static) não tem. Offmpegjá vem em todas, sem pedir. - Onde: no
cube.jsondo primeiro envio ou em Configurações › Geral › Pacotes do sistema no painel. Mudou depois? Vale no próximo início (o painel pede para reiniciar). - Quanto demora: a primeira vez com uma combinação nova de linguagem, versão e pacotes, o projeto fica em Instalando de alguns segundos a uns 2 minutos (o
poppler-utilsleva uns 10 s; obuild-essential, uns 45 s); depois, a mesma combinação sobe na hora, para qualquer projeto. - Na instalação também: o
npm install, opip install, ocomposer installe obundle installjá rodam com os pacotes, então obuild-essential(com opython3, no Node.js) resolve a dependência nativa que não tem binário pronto, e ogita que vem de um repositório. - Fora da lista não entra: o envio é recusado com
unsupported_system_package, e a mensagem traz a lista. Precisa de outro? Peça no Discord.
Onde o cube.json vale
- No painel: ele preenche a tela Configure o projeto. O que você confirma na tela é o que fica valendo.
- Na API: se o formulário do envio trouxer
languageecommand(oulanguageeentry, e o comando sai do arquivo principal; ou sólanguage, nostatic, nogo, norust, noelixire nophp), o formulário vale e ocube.jsoné ignorado, menos osystemPackages: ele vale mesmo assim, a não ser que o formulário traga o camposystemPackages. Sem eles, vale ocube.json. Sem nenhum dos dois, a raiz do .zip decide quando não há dúvida: só HTML (oindex.htmlna raiz e nenhumpackage.json,requirements.txt,pyproject.toml,go.mod,composer.json,Gemfile,mix.exsnem projeto do .NET) vira site estático; ogo.modsem outro manifesto vira Go; um único projeto do .NET na raiz (.csproj,.fsprojou.vbproj) vira .NET com ele de arquivo principal (com só a solução.sln, a mensagem diz .NET e pede o comando); omix.exsvira Elixir, com omix run --no-halt; ocomposer.jsonsem outro manifesto vira um site PHP (opackage.jsonjunto dele, doGemfile, do projeto do .NET ou domix.exsé o dos assets, como o Vite do Laravel, e não conta); um único.jarna raiz, sem manifesto nenhum, vira Java com ele de arquivo principal. Qualquer outro é recusado commissing_config(com um manifesto de uma linguagem só, como oGemfile, a mensagem diz a linguagem e pede o comando). - Pasta dentro do .zip: se o
.ziptiver uma única pasta no topo e nenhumcube.jsonna raiz, essa pasta vira a raiz. Isso cobre o “Compactar” do Windows e do macOS.
Vindo de outra hospedagem
Semcube.json, a Cube lê o arquivo de configuração de outra hospedagem que estiver na raiz do .zip e traduz para as chaves do cube.json. Assim o projeto sobe sem você reescrever nada. Vale no painel (a tela Configure o projeto diz de qual arquivo a configuração veio), na API e na CLI (0.2.5 ou mais nova).
Os arquivos lidos, nesta ordem: squarecloud.app, squarecloud.config, discloud.config e .shardcloud. O formato é CHAVE=valor, uma por linha, com # para comentário.
- O
MAINem.js,.mjs,.cjs,.ts,.mtsou.ctsé Node.js (o.tsroda com otsx), em.pyé Python, em.jaré Java (java -jar), em.goé Go (a pasta dele é a que o build compila), em.phpé PHP, em.rbé Ruby, em.csproj,.fsproj,.vbproj,.sln,.dllou.csé .NET, em.exou.exsé Elixir, em.rsé Rust e em.htmlé o site estático, com a pasta doMAINcomoroot. OMAIN=app.dllda Square Cloud, com o projeto ou a solução na raiz, roda o publicado,dotnet /dados/publish/app.dll, e o build publica o projeto da raiz; sem eles, é um.dllpronto, que roda como veio (dotnet app.dll, sem build); o Elixir semMAINrodamix run --no-halt. O site PHP semSTARTé servido pela Cube, com a pasta doMAIN(public/index.php→public); o bot PHP rodaphp <MAIN>.RUNTIME/LANGUAGEgolangtambém virago, ecsharpec#viramdotnet. VERSIONcom número vale quando a Cube tem essa versão (22.11.0vira"22",3.14.7vira"3.14",1.27.1vira"1.27",21.0.4vira"21",8.5.10vira"8.5",4.0.7vira"4.0",10.0.12vira"10",1.20.4vira"1.20",1.98.1vira"1.98");recommended,latestou uma versão que não existe aqui deixam a padrão.- A memória de lá é sugestão: abaixo do mínimo daqui, sobe ao mínimo do seu plano; acima do que sobra no plano, desce ao que sobra (o
MEMORY=256entra com 100 MB no Free). Um subdomínio que não vale ou já está em uso aqui dá lugar a um gerado. O resto (AUTORESTART,DESCRIPTION,AVATAR,APT) é ignorado. - Linguagem que a Cube ainda não tem (Kotlin…) é recusada com
unsupported_language. - O site precisa ouvir na porta da variável
PORT(8080 por padrão), nunca numa porta fixa como a 80.
A configuração fica guardada no projeto depois do primeiro envio. Um
cube.json diferente num novo .zip do mesmo projeto é ignorado. Para mudar nome, linguagem, arquivo principal, comando, comando de instalação, versão, pasta servida, memória, a Publicação na web, subdomínio, porta ou pacotes do sistema, use Configurações no projeto. A porta nova vale no próximo início: até reiniciar, o site segue na porta de antes.
