> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cubehosting.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Enviar novo código
> Troque o código de um projeto por um .zip novo, sem mudar a configuração.
Atualiza o código de um projeto que já existe, como faria um deploy no CI. A configuração do projeto não muda.
O `.zip` novo substitui a pasta inteira do projeto (só as dependências instaladas ficam). Arquivos que o seu app criou, como um banco SQLite, somem se não estiverem no `.zip`.
## Deploy a cada push (GitHub Actions)
Guarde uma chave de leitura e escrita como segredo `CUBE_API_KEY` e o ID do projeto como variável `CUBE_PROJECT_ID`:
```yaml .github/workflows/deploy.yml theme={"dark"}
name: Deploy na Cube
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Compactar
run: zip -r projeto.zip . -x "node_modules/*" ".git/*" ".github/*"
- name: Enviar
run: |
curl --fail-with-body \
https://app.cubehosting.com.br/api/projects/${{ vars.CUBE_PROJECT_ID }}/code \
-H "Authorization: Bearer ${{ secrets.CUBE_API_KEY }}" \
-F "file=@projeto.zip"
```
## OpenAPI
````yaml POST /projects/{id}/code
openapi: 3.1.0
info:
title: API da Cube Hosting
version: 1.0.0
description: >-
Hospede bots de Discord, sites e APIs em Node.js e Python: envie o .zip,
inicie, pare, reinicie, leia logs e métricas e cuide das variáveis de
ambiente.
contact:
name: Cube Hosting
url: https://discord.gg/pv6D9tUsDV
servers:
- url: https://app.cubehosting.com.br/api
security:
- bearerAuth: []
tags:
- name: Projetos
- name: Controle
- name: Logs e métricas
- name: Variáveis de ambiente
paths:
/projects/{id}/code:
post:
tags:
- Projetos
summary: Enviar novo código
description: >-
Troca o código do projeto por um `.zip` novo. A configuração (tipo,
linguagem, comando e memória) continua a mesma: um `cube.json` no `.zip`
novo é ignorado. As dependências só são instaladas de novo se o
`package.json`, o `package-lock.json` ou o `requirements.txt` mudou. Se
o projeto estava ligado, ele volta com o código novo.
O `.zip` novo substitui a pasta inteira do projeto (só as dependências
instaladas ficam). Se for recusado, os arquivos de antes continuam lá.
Um envio a cada 3 segundos por conta, somando com a criação de projetos.
operationId: uploadProjectCode
parameters:
- $ref: '#/components/parameters/ProjectId'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: >-
O `.zip` com o código novo. Até 5 MB no Free e 10 MB nos
planos pagos.
encoding:
file:
contentType: application/zip
responses:
'202':
description: >-
Código recebido. O projeto passa por `installing` e volta ao estado
que você deixou.
content:
application/json:
schema:
$ref: '#/components/schemas/InstallStarted'
example:
project:
id: 01J8Z3W6N0Q4Y7V2K5T9D1H3XA
name: Meu bot
description: Atende o servidor da loja
type: bot
language: node
version: '24'
entry: index.js
command: node index.js
memoryMb: 256
port: null
subdomain: null
url: null
status: installing
error: null
hasAutoRestart: true
consecutiveCrashes: 0
lastExit: null
usage: null
startedAt: null
createdAt: '2026-09-26T18:00:00.000Z'
updatedAt: '2026-09-26T18:01:10.000Z'
isReinstallingDependencies: false
'401':
description: Chave ausente, inválida ou revogada.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_api_key:
summary: invalid_api_key
value:
status: error
code: invalid_api_key
message: >-
Chave de API inválida ou revogada. Confira o cabeçalho
"Authorization: Bearer " ou crie outra em Chaves de
API no painel.
'403':
description: A chave é só de leitura.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
insufficient_permission:
summary: insufficient_permission
value:
status: error
code: insufficient_permission
message: >-
Esta chave é só de leitura. Para enviar, iniciar, parar,
reiniciar ou mexer nas variáveis, crie uma chave de
leitura e escrita no painel.
'404':
description: O projeto não existe ou não é da sua conta.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
not_found:
summary: not_found
value:
status: error
code: not_found
message: Projeto não encontrado.
'409':
description: O projeto está ocupado ou a conta não pode instalar agora.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
project_busy:
summary: project_busy
value:
status: error
code: project_busy
message: >-
O projeto está sendo preparado ou já tem outra ação em
andamento. Espere terminar.
account_suspended:
summary: account_suspended
value:
status: error
code: account_suspended
message: >-
Sua conta está suspensa porque o Pix da renovação não foi
pago, então os projetos ficam parados. Pague em Plano e
cobrança: a conta volta na hora, e o que estava no ar sobe
sozinho.
beta_ending:
summary: beta_ending
value:
status: error
code: beta_ending
message: >-
Seu beta terminou e a conta está voltando ao plano Free.
Espere alguns minutos e tente de novo.
'413':
description: O .zip passou do limite do plano (5 MB no Free, 10 MB nos pagos).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_zip:
summary: invalid_zip
value:
status: error
code: invalid_zip
message: >-
O zip passa do limite de 5 MB do plano Free. Tire as
dependências (elas são instaladas aqui) e arquivos que o
projeto não usa.
limitMb: 5
'422':
description: O .zip foi recusado. Nada mudou no projeto.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_zip:
summary: invalid_zip
value:
status: error
code: invalid_zip
message: >-
O arquivo não é um zip válido (corrompido, protegido por
senha ou vazio). Gere o zip de novo e envie.
unsafe_zip:
summary: unsafe_zip
value:
status: error
code: unsafe_zip
message: >-
Descompactado, o projeto passa do limite de 500 MB. Tire
os arquivos grandes que o bot não usa e envie de novo.
reason: size
'429':
description: Limite de pedidos. Traz o cabeçalho `Retry-After`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rate_limit_exceeded:
summary: rate_limit_exceeded
value:
status: error
code: rate_limit_exceeded
message: >-
A sua conta passou do limite da API do plano Free: 10
pedidos por minuto. Espere 42 s e tente de novo.
too_many_requests:
summary: too_many_requests
value:
status: error
code: too_many_requests
message: >-
Muitas requisições seguidas. Espere alguns segundos e
tente de novo.
too_many_attempts:
summary: too_many_attempts
value:
status: error
code: too_many_attempts
message: Muitas tentativas. Tente de novo em 15 minutos.
'503':
description: >-
O servidor dos projetos não respondeu, ou as variáveis de ambiente
não abriram (o projeto não sobe sem elas). Nada foi alterado.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
server_unavailable:
summary: server_unavailable
value:
status: error
code: server_unavailable
message: >-
O servidor dos projetos não respondeu. Tente de novo em
instantes.
variables_unavailable:
summary: variables_unavailable
value:
status: error
code: variables_unavailable
message: >-
As variáveis de ambiente do projeto não puderam ser
abertas agora. Tente de novo em instantes.
x-codeSamples:
- lang: bash
label: curl
source: |-
curl https://app.cubehosting.com.br/api/projects/$PROJECT_ID/code \
-H "Authorization: Bearer $CUBE_API_KEY" \
-F "file=@meu-bot.zip"
- lang: javascript
label: Node.js
source: >-
import { openAsBlob } from 'node:fs';
const API = 'https://app.cubehosting.com.br/api';
const headers = { Authorization: `Bearer
${process.env.CUBE_API_KEY}` };
const form = new FormData();
form.set('file', await openAsBlob('meu-bot.zip'), 'meu-bot.zip');
const res = await
fetch(`${API}/projects/${process.env.PROJECT_ID}/code`, {
method: 'POST',
headers,
body: form,
});
const { project, isReinstallingDependencies } = await res.json();
console.log(project.status, isReinstallingDependencies);
- lang: python
label: Python
source: |-
import os
import requests
API = "https://app.cubehosting.com.br/api"
headers = {"Authorization": f"Bearer {os.environ['CUBE_API_KEY']}"}
with open("meu-bot.zip", "rb") as zip:
r = requests.post(
f"{API}/projects/{os.environ['PROJECT_ID']}/code",
headers=headers,
files={"file": ("meu-bot.zip", zip, "application/zip")},
timeout=300,
)
r.raise_for_status()
print(r.json())
components:
parameters:
ProjectId:
name: id
in: path
required: true
description: >-
O ID do projeto (26 caracteres). Aparece no painel, no topo do projeto,
e em `GET /projects`.
schema:
type: string
pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
example: 01J8Z3W6N0Q4Y7V2K5T9D1H3XA
schemas:
InstallStarted:
type: object
required:
- project
- isReinstallingDependencies
properties:
project:
$ref: '#/components/schemas/Project'
isReinstallingDependencies:
type: boolean
description: >-
`true` quando as dependências vão ser instaladas de novo; `false`
quando só o build (se houver) roda.
Error:
type: object
required:
- status
- code
- message
properties:
status:
type: string
const: error
code:
type: string
description: Código fixo em inglês. Veja [Códigos de erro](/errors).
message:
type: string
description: Texto em português para mostrar a uma pessoa.
additionalProperties: true
Project:
type: object
description: 'Um projeto: um bot ou um site.'
required:
- id
- name
- description
- type
- language
- version
- entry
- command
- memoryMb
- port
- subdomain
- url
- status
- error
- hasAutoRestart
- consecutiveCrashes
- lastExit
- usage
- startedAt
- createdAt
- updatedAt
properties:
id:
type: string
description: ID do projeto, 26 caracteres.
name:
type: string
maxLength: 40
description: Nome do projeto.
description:
type: string
maxLength: 200
description: Descrição do painel. `""` quando não tem.
type:
type: string
enum:
- bot
- site
language:
type: string
enum:
- node
- python
version:
type: string
description: '`20`, `22` ou `24` (Node.js); `3.11` ou `3.12` (Python).'
entry:
type:
- string
- 'null'
description: >-
Arquivo principal: o arquivo que o comando roda, relativo à raiz do
projeto (como `index.js` ou `src/bot.py`). Vem do `command` quando
ele é só `node ` ou `python `, e muda em
Configurações › Geral. `null` com um comando próprio, como `npm
start`.
command:
type: string
description: >-
Comando de início, o que de fato roda. Quando é `node ` ou
`python `, o painel mostra o campo vazio (vazio = roda o
arquivo principal).
memoryMb:
type: integer
description: Memória reservada, em MB. É também o teto do processo.
port:
type:
- integer
- 'null'
description: >-
Só site: a porta em que o app escuta (também na variável `PORT`).
`null` em bot.
subdomain:
type:
- string
- 'null'
description: 'Só site: o nome em `nome.cubehost.dev`. `null` em bot.'
url:
type:
- string
- 'null'
format: uri
description: 'Só site: o endereço público com HTTPS. `null` em bot.'
status:
$ref: '#/components/schemas/ProjectStatus'
error:
oneOf:
- $ref: '#/components/schemas/ProjectError'
- type: 'null'
description: O motivo, quando `status` é `error` ou `crash_loop`.
hasAutoRestart:
type: boolean
description: '`true` nos planos pagos: o projeto volta sozinho se cair.'
consecutiveCrashes:
type: integer
description: >-
Quedas seguidas desde a última vez que rodou 60 segundos sem cair.
Com 5, o projeto vai para `crash_loop`.
lastExit:
oneOf:
- $ref: '#/components/schemas/LastExit'
- type: 'null'
description: A última vez que o processo terminou.
usage:
oneOf:
- $ref: '#/components/schemas/Usage'
- type: 'null'
description: O uso de agora. Só com `status` `running`.
startedAt:
type:
- string
- 'null'
format: date-time
description: >-
Quando o processo subiu (o "tempo no ar" do painel). Só com
`running`.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
ProjectStatus:
type: string
enum:
- creating
- installing
- running
- stopped
- restarting
- crash_loop
- error
description: >-
`creating` (Enviando), `installing` (Instalando), `running` (No ar),
`stopped` (Parado), `restarting` (Reiniciando), `crash_loop` (Em loop de
erro), `error` (Com erro).
ProjectError:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- install_failed
- install_timeout
- install_out_of_memory
- install_interrupted
- start_failed
- process_exited
- crash_loop
description: >-
Veja [Estados de erro do
projeto](/errors#estados-de-erro-do-projeto).
message:
type: string
description: Explicação em português.
LastExit:
type: object
required:
- code
- isOutOfMemory
- exitedAt
properties:
code:
type: integer
description: O código de saída do processo.
isOutOfMemory:
type: boolean
description: '`true` se o processo passou da memória do projeto.'
exitedAt:
type: string
format: date-time
Usage:
type: object
required:
- memoryMb
- cpuPercent
- networkInBps
- networkOutBps
properties:
memoryMb:
type: integer
description: Memória em uso, em MB.
cpuPercent:
type: number
description: Uso de processador. 100 = um núcleo inteiro.
networkInBps:
type: integer
description: Rede recebida, em bytes por segundo.
networkOutBps:
type: integer
description: Rede enviada, em bytes por segundo.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Chave de API da Cube (`cube_…`), criada no painel em **Chaves de API**.
Mande como `Authorization: Bearer cube_…`.
````