Boxes

Como uma box nasce, dorme, acorda e some. O agente cuida disso sozinho; aqui está o que acontece por baixo, e os comandos se você quiser mexer à mão

Na mão, pela CLI

Terminal

$ puxadinho create --name minha-box$ puxadinho exec minha-box -- npm test$ puxadinho suspend minha-box$ puxadinho resume minha-box$ puxadinho rm minha-box

Ainda não tem a CLI? Veja CLI. Onde um comando pede BOX, vale o nome ou o id (bx_…).

Ciclo de vida

No painel	Estado	O que quer dizer
Criando	`creating`	A box está subindo. O create espera ela ficar pronta.
Trabalhando	`running`	Ligada e cobrando por hora.
Dormindo	`suspended`	Pausada com a memória e os processos guardados. Não cobra processamento.
Desligada	`stopped`	Desligada de vez. Os arquivos ficam; volta do zero com start.
Ligando	`resuming · starting`	Voltando de uma pausa ou ligando de novo.
Terminou	`deleted`	Apagada, com todos os arquivos. Não tem volta.
Com erro	`error`	Algo falhou. A mensagem aparece no painel e no get.

Comando	O que faz
`puxadinho suspend BOX`	Pausa a box (só volta com resume)
`puxadinho resume BOX`	Retoma uma box pausada
`puxadinho wake BOX`	Acorda uma box pausada por ociosidade ou max-run
`puxadinho stop BOX`	Desliga a box (só volta com start)
`puxadinho start BOX`	Liga uma box desligada
`puxadinho restart BOX`	Reinicia a box
`puxadinho rm BOX`	Apaga uma box (sem volta)

Só uma mudança por box de cada vez. Se o agente pedir duas ao mesmo tempo, a segunda recebe 409 operation_conflict e tenta de novo depois.

Dormir sozinha

Sem uso, a box dorme e para de cobrar processamento. O padrão é 30 minutos parada. Um comando ou uma leitura de arquivo acorda ela de novo, com os processos de antes.

Terminal

$ puxadinho auto-suspend minha-box 10m$ puxadinho auto-suspend minha-box off

De 5 a 30 minutos, em minutos inteiros. off desliga a pausa automática (só nos planos pagos).
Enquanto um job roda (puxadinho jobs start ou start_job no MCP), a box não dorme por ociosidade.
Pausada por você com suspend, ela só volta com resume. Pausada por ociosidade ou por tempo máximo, use wake.

Tempo máximo e apagar sozinha

Terminal

$ puxadinho max-run minha-box 120$ puxadinho create --name teste --delete-after 2h

max-run: por quantos minutos seguidos a box pode rodar antes de pausar. unlimited tira o limite (só nos planos pagos); 0 pausa já.
--delete-after: a box se apaga sozinha depois do prazo, de 1 minuto a 24 horas. O puxadinho run já usa isso para nunca deixar box esquecida.

Tamanho

Núcleos de 2 a 32 (2, 4, 8, 16 ou 32), com 2 GB de memória por núcleo, e de 20 a 500 GB de disco em /data. O padrão é 4 núcleos, 8 GB e 20 GB. O que cada plano permite está em Planos e limites.

Terminal

$ puxadinho create --name grande --vcpus 8 --mem-mib 16384 --data-gib 100

puxadinho resize muda o tamanho de uma box que já existe; vale no próximo boot. O disco só cresce.

Arquivos

Terminal

$ puxadinho push minha-box ./projeto$ puxadinho pull minha-box saida/video.mp4 .

A pasta da box é /data/home. Caminho relativo parte de lá.
O push de uma pasta git leva só os arquivos rastreados e nunca leva node_modules, .git, dist, build, .next, target e __pycache__. Para ignorar mais, crie um .puxadinhoignore.
Arquivo grande vai e volta em partes. Caiu a conexão? Rode de novo e continua de onde parou.
Pelo MCP, o agente lê e grava até 1 MB direto. Para mais, ele pede uma URL assinada que vale 1 hora: até 5 GB para enviar, pastas inteiras para baixar.

Snapshots

Um snapshot guarda o disco da box. Serve para criar boxes iguais depois, já com tudo instalado.

Terminal

$ puxadinho snapshot save minha-box --name pronto-para-render$ puxadinho snapshot ls$ puxadinho create --name nova --snapshot snp_ID

Comando	O que faz
`puxadinho snapshot save BOX`	Salva um snapshot da box
`puxadinho snapshot ls`	Lista os snapshots
`puxadinho snapshot files SNAPSHOT`	Lista os arquivos de um snapshot
`puxadinho snapshot restore BOX SNAPSHOT`	Restaura um snapshot na box (substitui root e /data; a box reinicia)
`puxadinho snapshot rm SNAPSHOT`	Apaga um snapshot

snapshot restore troca o sistema e o /data da box pelos do snapshot e reinicia a box. O que não estava no snapshot se perde.

Cópias (fork)

Copia a box em até 5, com o mesmo disco e sem a memória: as cópias ligam do zero. Bom para testar três versões da mesma coisa ao mesmo tempo.

Terminal

$ puxadinho fork minha-box --count 3

Sem --name, as cópias se chamam minha-box-1, minha-box-2…

Portas e acesso

Subiu um site ou uma API na box? Publique a porta numa URL HTTPS:

Terminal

$ puxadinho port publish minha-box 3000

Por padrão a porta é privada: a resposta traz um token, que vai na URL como ?token=. Ele aparece uma vez só.
--public abre para qualquer um, sem token. --tcp publica TCP com TLS na porta 443 em vez de HTTPS.
puxadinho port ls lista as portas e puxadinho port rm despublica.
puxadinho port-forward minha-box 3000 traz a porta para o seu localhost por SSH, sem publicar nada.
puxadinho ssh minha-box entra na box com um certificado que vale 1 hora (dá para mudar com --ttl).