> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox na nuvem

> O ambiente privado na nuvem que armazena o código do seu app e como trabalhar nele sem uma cópia local

Todo app Base44 tem um sandbox: um ambiente privado na nuvem que armazena o código do app e roda seu servidor de desenvolvimento. É o mesmo ambiente e o mesmo código que o editor do app usa, sem fork ou cópia para manter sincronizada. Conecte-se via CLI, um cliente MCP ou a API para ler, pesquisar, editar e executar comandos no seu app a partir de qualquer máquina, sem checkout local e sem nada para instalar.

Quando você escreve um arquivo pelo sandbox, está alterando seu app real diretamente, da mesma forma que o editor do app faria. O motivo mais comum para fazer isso é [trazer seu próprio coding agent](/pt-BR/developers/app-code/sandbox/bring-your-own-agent) para um app que você construiu no editor.

<Warning>
  Você precisa de um [**plano Builder**](/pt-BR/Account-and-billing/Billing-and-plans) ou superior para alcançar o sandbox de um app fora do editor do app. Sem ele, os comandos falham com `PREMIUM_REQUIRED`.
</Warning>

## Quando usar o sandbox

Você pode trabalhar no código de um app que construiu no editor das seguintes formas:

| Opção                                                                        | Use quando                                                                                  | Configuração necessária                                                                            |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [Aba Code](/pt-BR/developers/app-code/editor/code-tab)                       | Você quer uma edição rápida no navegador.                                                   | Nenhuma.                                                                                           |
| Sandbox na nuvem                                                             | Você quer seu próprio coding agent ou scripts alterando o app sem baixá-lo.                 | Faça login com a CLI ou conecte-se via MCP.                                                        |
| [Integração com GitHub](/pt-BR/developers/app-code/local-development/github) | Você quer o código no seu próprio repositório e uma configuração local completa no seu IDE. | Um proprietário do app conecta um repositório uma vez. Cada máquina então o clona e instala a CLI. |
| [Eject](/developers/references/cli/commands/eject)                           | Você quer uma cópia do código fora da Base44 que não sincroniza de volta.                   | Um comando.                                                                                        |

O sandbox e a integração com GitHub se sobrepõem mais, já que ambos permitem trabalhar com suas próprias ferramentas. A diferença é onde o código reside enquanto você trabalha. Com a integração com GitHub, você desenvolve em um clone local, e suas alterações chegam à Base44 quando são mescladas para `main`. Com o sandbox, você trabalha no código do app diretamente. Não há nada para baixar, um assistente baseado na web pode usá-lo, e cada alteração aparece na visualização ao vivo do editor do app assim que é feita.

## Formas de se conectar

Você pode alcançar o sandbox das seguintes maneiras:

* **[CLI](/developers/references/cli/get-started/overview):** Para um coding agent ou scripts rodando na sua própria máquina. Nenhum projeto local é necessário. Para configuração, veja [Conectar um agent local com a CLI](/pt-BR/developers/app-code/sandbox/bring-your-own-agent#connect-a-local-agent-with-the-cli).
* **[Servidor MCP](/pt-BR/developers/backend/overview/mcp-server):** Para um assistente de IA que se conecta via MCP, incluindo assistentes baseados na web que não podem rodar uma CLI. Para configuração, veja [Conectar um agent via MCP](/pt-BR/developers/app-code/sandbox/bring-your-own-agent#connect-an-agent-over-mcp).
* **[App Management API](/developers/references/apps-api/get-started/overview):** Para suas próprias integrações, usando os endpoints listados abaixo.

| Operação                       | Comando CLI                                                                    | Ferramenta MCP      | Endpoint da API                                                           |
| ------------------------------ | ------------------------------------------------------------------------------ | ------------------- | ------------------------------------------------------------------------- |
| Listar um diretório            | [`sandbox ls`](/developers/references/cli/commands/sandbox-ls)                 | `list_directory`    | [List app files](/api-reference/list-app-files)                           |
| Ler arquivos                   | [`sandbox read`](/developers/references/cli/commands/sandbox-read)             | `read_file`         | [Read app files](/api-reference/read-app-files)                           |
| Pesquisar conteúdo de arquivos | [`sandbox grep`](/developers/references/cli/commands/sandbox-grep)             | `grep`              | [Search app files](/api-reference/search-app-files)                       |
| Criar um arquivo               | [`sandbox write`](/developers/references/cli/commands/sandbox-write)           | `write_file`        | [Write an app file](/api-reference/write-an-app-file)                     |
| Alterar um arquivo existente   | [`sandbox edit`](/developers/references/cli/commands/sandbox-edit)             | `edit_file`         | [Edit an app file](/api-reference/edit-an-app-file)                       |
| Executar um comando de shell   | [`sandbox run`](/developers/references/cli/commands/sandbox-run)               | `run_command`       | [Run a sandbox command](/api-reference/run-a-sandbox-command)             |
| Salvar um ponto de restauração | [`sandbox checkpoint`](/developers/references/cli/commands/sandbox-checkpoint) | `create_checkpoint` | [Create a sandbox checkpoint](/api-reference/create-a-sandbox-checkpoint) |

Os conectores não passam pelo sistema de arquivos do sandbox, portanto não estão na tabela acima. Para configurar um conector em um app com o qual você está trabalhando dessa forma, use [`connectors initiate`](/developers/references/cli/commands/connectors-initiate). Ele mira no mesmo app id diretamente, sem sandbox nem projeto local.

## Branches

Os comandos do sandbox têm como alvo a branch `main` do app, a menos que você diga o contrário. Para trabalhar em outra [branch](/pt-BR/Building-your-app/working-with-branches), execute [`branches list`](/developers/references/cli/commands/branches-list) para encontrar seu nome exato e passe [`--branch <name>`](/developers/references/cli/commands/introduction#target-a-branch) em cada comando do sandbox. As leituras e edições se aplicam apenas a essa branch.

## As alterações são salvas automaticamente

Uma chamada [`sandbox write`](/developers/references/cli/commands/sandbox-write) ou [`sandbox edit`](/developers/references/cli/commands/sandbox-edit) faz o commit da alteração como parte da mesma requisição, antes de o comando retornar, portanto não há etapa separada de salvar, deploy ou push. Uma alteração de arquivo feita por [`sandbox run`](/developers/references/cli/commands/sandbox-run), como `rm` ou `mv`, é commitada alguns segundos depois, quando uma pequena janela de debounce fecha. Se você escrever ou editar novamente antes de um commit debounced anterior ter chegado, a nova chamada aguarda por ele e falha com `COMMIT_FLUSH_PENDING` se não puder confirmar que aquele commit terminou a tempo.

Recursos estruturados sincronizam da mesma forma. Em um projeto local, você executaria [`entities push`](/developers/references/cli/commands/entities-push) ou [`functions deploy`](/developers/references/cli/commands/functions-deploy) depois de adicionar um arquivo. No sandbox, criar `base44/functions/send-email/entry.ts` é tudo o que é preciso para adicionar essa função.

<Warning>
  **Duas regras ao editar em um sandbox:**

  * Não execute [`deploy`](/developers/references/cli/commands/deploy), [`functions deploy`](/developers/references/cli/commands/functions-deploy), [`entities push`](/developers/references/cli/commands/entities-push) ou os outros comandos de push em um app que você está editando no seu sandbox. Esses comandos sincronizam um projeto local com a Base44, e não há projeto local quando você trabalha com um sandbox.
  * Se sua última ação foi um comando de shell executado por `sandbox run`, em vez de uma chamada `write` ou `edit`, seu commit ainda está um momento atrás. Dê alguns segundos antes de desconectar.
</Warning>

## Editando e publicando

Editar pelo sandbox não é o mesmo que publicar. Sua edição passa a fazer parte do código do app imediatamente e aparece no editor do app e em sua visualização ao vivo. Alcançar o site público do app ainda requer a mesma etapa de publicação de uma alteração feita no editor do app.

## Checkpoints

Um checkpoint é um ponto de restauração no histórico de versões do app, ancorado a um commit específico. Crie um com [`sandbox checkpoint`](/developers/references/cli/commands/sandbox-checkpoint) para marcar um estado conhecido como bom e, se uma alteração posterior der errado, restaure-o pelo editor do app. Alterações pendentes são commitadas antes de o checkpoint ser feito, portanto ele sempre captura seu código mais recente.

## Trabalhando ao lado do editor do app

Seu coding agent e o editor do app da Base44 podem trabalhar no mesmo app ao mesmo tempo. Não há trava para adquirir e nenhuma sessão para liberar. Alterações de qualquer lado chegam ao mesmo lugar, portanto trate como trataria um colega editando o mesmo projeto.

<Warning>
  Não há etapa de merge. Se seu coding agent e o editor do app alterarem o mesmo arquivo ao mesmo tempo, o último write vence, e a alteração anterior desaparece. Evite que ambos os lados toquem no mesmo arquivo no mesmo trecho de trabalho.
</Warning>

## Iniciando e parando

O sandbox é um processo em execução, não apenas armazenamento. Ele para quando fica ocioso por um tempo e é iniciado novamente no próximo comando. Seu código não é afetado de nenhuma forma. Alterações commitadas vivem no git, e um sandbox reiniciado sempre começa pelo seu commit mais recente. Se o sandbox não estiver rodando, o primeiro comando o inicia, o que significa que essa chamada provavelmente levará mais tempo do que as seguintes.

## Permissões

Duas verificações separadas controlam o acesso ao sandbox. Uma é se você pode acessar o app em geral, e a outra é se sua sessão atual recebeu acesso de escrita a ele.

### Acesso ao app

Você precisa de acesso de admin ao próprio app, seja como admin do workspace ou como colaborador neste app específico. O acesso é verificado a cada chamada, então uma alteração na sua função no workspace tem efeito imediato.

Um viewer simples de workspace não pode alcançar o sandbox. A única exceção é um viewer que também possui uma função legada de editor por app anterior à migração do workspace para acesso baseado em função. Essa combinação ainda pode ler o sandbox, mas não alterar nada. Superagents não suportam os comandos do sandbox.

### Escopo da sessão

Além do acesso ao app, ler e alterar o sandbox exigem permissões diferentes na sua sessão:

| Comandos                                                             | Permissão necessária              |
| -------------------------------------------------------------------- | --------------------------------- |
| `sandbox ls`, `sandbox read`, `sandbox grep`                         | `apps:read`, concedida por padrão |
| `sandbox write`, `sandbox edit`, `sandbox run`, `sandbox checkpoint` | `sandbox:write`                   |

As permissões da sua sessão são fixadas quando ela é criada e não podem ser ampliadas depois. A CLI solicita `sandbox:write` durante `base44 login`, e via MCP você concede na etapa de consentimento do OAuth. Renovar uma sessão existente não a adiciona.

Portanto, se os comandos de leitura funcionam mas os de alteração falham com `NOT_AUTHORIZED`, você está em uma sessão que nunca teve `sandbox:write`. Execute [`base44 login`](/developers/references/cli/commands/login) novamente, ou reconecte o servidor MCP e aprove o acesso ao sandbox, para iniciar uma sessão que o tenha.

## Limites e proteções

Os comandos de arquivo ficam confinados à raiz do app. Caminhos absolutos e caminhos que sobem acima da raiz são rejeitados com `PATH_OUTSIDE_SANDBOX`. Os diretórios `.agents` e `.git` não são acessíveis pelos comandos de arquivo e falham com `PROTECTED_PATH`, porque contêm os segredos do seu app e as credenciais do repositório. A única exceção é `.agents/skills`, que você pode ler e escrever.

Em todo o recurso, você está limitado a 120 requisições de leitura, 60 requisições de alteração e 30 comandos run por minuto, por app. Ultrapassar qualquer um deles falha com `RATE_LIMITED`. A página de referência de cada comando cobre seus limites de tamanho e contagem, como quantos caminhos `sandbox read` aceita ou quão grande é o arquivo que `sandbox write` permite.

## Veja também

* [Traga seu próprio agent](/pt-BR/developers/app-code/sandbox/bring-your-own-agent): Conecte seu próprio coding agent de IA ao sandbox de um app
* [Visão geral da CLI](/developers/references/cli/get-started/overview): Instale e use a CLI da Base44
* [Servidor MCP da Base44](/pt-BR/developers/backend/overview/mcp-server): Conecte um assistente de IA à sua conta Base44
* [Integração com GitHub](/pt-BR/developers/app-code/local-development/github): Desenvolva localmente com sincronização bidirecional para seu repositório
* [Estrutura do projeto](/developers/backend/overview/project-structure): Como os arquivos do projeto Base44 são organizados

<Note>Esta página foi traduzida usando IA. Para as informações mais precisas e atualizadas, consulte a [versão em inglês](/). </Note>