Pular para o conteúdo principal
O 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.
string
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.
string
O nome que aparece no painel, de 1 a 40 caracteres. Sem ele, vale o nome do arquivo .zip.
"bot" | "site"
padrão:"bot"
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.
string
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.
integer
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.
integer
padrão:"8080"
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).
string
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.
string
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.
string
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.
string
padrão:"a pasta do index.html"
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".
string[]
padrão:"[]"
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.
Chave desconhecida é recusada com o erro invalid_config, dizendo qual chave. Assim um erro de digitação não passa calado. port e subdomain num bot também são recusados, e também command, version, build e installCommand no static e root fora do static e do site php sem command.

Exemplos

Os bots dos exemplos ficam sem memoryMb: entram com o mínimo do plano (256 MB nos pagos, 100 MB no Free), então o mesmo arquivo vale em qualquer plano.
cube.json

Pacotes do sistema

Alguns projetos precisam de um programa do sistema, além das dependências do package.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. O ffmpeg já vem em todas, sem pedir.
  • Onde: no cube.json do 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-utils leva uns 10 s; o build-essential, uns 45 s); depois, a mesma combinação sobe na hora, para qualquer projeto.
  • Na instalação também: o npm install, o pip install, o composer install e o bundle install já rodam com os pacotes, então o build-essential (com o python3, no Node.js) resolve a dependência nativa que não tem binário pronto, e o git a 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.
No código, chame o programa como no seu computador: execFileSync('pdftotext', ['arquivo.pdf', '-']) no Node.js ou subprocess.run(['pdftotext', 'arquivo.pdf', '-']) no Python.

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 language e command (ou language e entry, e o comando sai do arquivo principal; ou só language, no static, no go, no rust, no elixir e no php), o formulário vale e o cube.json é ignorado, menos o systemPackages: ele vale mesmo assim, a não ser que o formulário traga o campo systemPackages. Sem eles, vale o cube.json. Sem nenhum dos dois, a raiz do .zip decide quando não há dúvida: só HTML (o index.html na raiz e nenhum package.json, requirements.txt, pyproject.toml, go.mod, composer.json, Gemfile, mix.exs nem projeto do .NET) vira site estático; o go.mod sem outro manifesto vira Go; um único projeto do .NET na raiz (.csproj, .fsproj ou .vbproj) vira .NET com ele de arquivo principal (com só a solução .sln, a mensagem diz .NET e pede o comando); o mix.exs vira Elixir, com o mix run --no-halt; o composer.json sem outro manifesto vira um site PHP (o package.json junto dele, do Gemfile, do projeto do .NET ou do mix.exs é o dos assets, como o Vite do Laravel, e não conta); um único .jar na raiz, sem manifesto nenhum, vira Java com ele de arquivo principal. Qualquer outro é recusado com missing_config (com um manifesto de uma linguagem só, como o Gemfile, a mensagem diz a linguagem e pede o comando).
  • Pasta dentro do .zip: se o .zip tiver uma única pasta no topo e nenhum cube.json na raiz, essa pasta vira a raiz. Isso cobre o “Compactar” do Windows e do macOS.

Vindo de outra hospedagem

Sem cube.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 MAIN em .js, .mjs, .cjs, .ts, .mts ou .cts é Node.js (o .ts roda com o tsx), 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, .dll ou .cs é .NET, em .ex ou .exs é Elixir, em .rs é Rust e em .html é o site estático, com a pasta do MAIN como root. O MAIN=app.dll da 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 .dll pronto, que roda como veio (dotnet app.dll, sem build); o Elixir sem MAIN roda mix run --no-halt. O site PHP sem START é servido pela Cube, com a pasta do MAIN (public/index.php → public); o bot PHP roda php <MAIN>. RUNTIME/LANGUAGE golang também vira go, e csharp e c# viram dotnet.
  • VERSION com número vale quando a Cube tem essa versão (22.11.0 vira "22", 3.14.7 vira "3.14", 1.27.1 vira "1.27", 21.0.4 vira "21", 8.5.10 vira "8.5", 4.0.7 vira "4.0", 10.0.12 vira "10", 1.20.4 vira "1.20", 1.98.1 vira "1.98"); recommended, latest ou 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=256 entra 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.
Com um cube.json no .zip, ele vale e o arquivo da outra hospedagem é ignorado.
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.