> ## 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.

# Traga seu próprio agente

> Aponte seu próprio agente de codificação de IA, ou seus próprios scripts, para o ambiente de nuvem que contém o código do seu app

Traga seu próprio agente de codificação de IA, ou seus próprios scripts, para um app Base44 conectando-se ao seu sandbox. O sandbox é um ambiente de nuvem privado que contém o código para qualquer branch que esteja ativo no editor do app, e executa seu servidor de desenvolvimento. É o mesmo ambiente, e o mesmo código, que o editor do app Base44 edita, sem fork ou cópia para manter sincronizado. Quando você grava um arquivo por meio de um comando do sandbox, você está alterando seu app real diretamente, no seu branch ativo, da mesma forma que o editor do app faria.

Isso permite que você desenvolva um app com suas próprias ferramentas em vez do editor do app, sem checkout local e sem nada para instalar. Trabalhe em um app a partir de uma máquina que não tem cópia dele, ou faça um script de uma alteração em um app que você criou inteiramente no editor do app.

<Note>
  Editar pelo sandbox não é o mesmo que publicar. Sua edição se torna parte do código do app imediatamente e aparece no editor do app e em sua visualização ao vivo, mas alcançar o site público do app ainda exige a mesma etapa de publicação que exigiria para uma alteração feita no editor do app.
</Note>

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

O sandbox em si é um processo de computação ativo, não apenas armazenamento: ele desliga quando fica ocioso por um tempo e liga de volta no próximo comando. Seu código não é afetado de qualquer forma, pois ele vive no git em vez de nesse processo. Se o sandbox não está em execução no momento, o primeiro comando o inicia, e essa chamada leva mais tempo que as seguintes.

## Duas maneiras de conectar

O sandbox expõe o mesmo conjunto de operações por meio de duas superfícies, com a mesma implementação por trás. Use a que se adapta à sua configuração.

* **[CLI](/developers/references/cli/get-started/overview):** adequado para qualquer coisa executada na sua própria máquina, incluindo um agente de codificação local e seus próprios scripts. Autentique uma vez com [`base44 login`](/developers/references/cli/commands/login), depois direcione o app com [`--app-id`](/developers/references/cli/commands/introduction#select-a-target-app) ou a variável de ambiente `BASE44_APP_ID`. Nenhum projeto local é necessário.
* **[MCP server](/developers/backend/overview/mcp-server):** adequado para um assistente de IA que se conecta por MCP, incluindo assistentes baseados em web que não podem executar uma CLI. Conecte-o uma vez e autorize com OAuth.

| Operação                       | Comando CLI                                                                    | Ferramenta MCP      |
| ------------------------------ | ------------------------------------------------------------------------------ | ------------------- |
| Listar um diretório            | [`sandbox ls`](/developers/references/cli/commands/sandbox-ls)                 | `list_directory`    |
| Ler arquivos                   | [`sandbox read`](/developers/references/cli/commands/sandbox-read)             | `read_file`         |
| Pesquisar conteúdo de arquivos | [`sandbox grep`](/developers/references/cli/commands/sandbox-grep)             | `grep`              |
| Criar um arquivo               | [`sandbox write`](/developers/references/cli/commands/sandbox-write)           | `write_file`        |
| Alterar um arquivo existente   | [`sandbox edit`](/developers/references/cli/commands/sandbox-edit)             | `edit_file`         |
| Executar um comando de shell   | [`sandbox run`](/developers/references/cli/commands/sandbox-run)               | `run_command`       |
| Salvar um ponto de restauração | [`sandbox checkpoint`](/developers/references/cli/commands/sandbox-checkpoint) | `create_checkpoint` |

Conectores não passam pelo sistema de arquivos do sandbox, então 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 direciona o mesmo app id diretamente, sem um sandbox ou um projeto local.

<Tip>
  A maneira mais rápida de começar com seu próprio agente de codificação é usar **Send to Coding Agent** no editor do app Base44. No desktop, abra **More actions** (os três pontos ao lado de **Publish**, no canto superior direito) e selecione **Send to Coding Agent**. Escolha um agente CLI local ou um chat web, e ele lhe entrega um prompt pronto para colar, para que você não precise configurar nada disso manualmente. Não é oferecido para apps mobile ou apps com código-fonte não gerenciado.
</Tip>

## As alterações salvam automaticamente

Uma chamada [`sandbox write`](/developers/references/cli/commands/sandbox-write) ou [`sandbox edit`](/developers/references/cli/commands/sandbox-edit) faz commit da alteração para você como parte da mesma requisição, antes do comando retornar, então 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`, faz commit alguns segundos depois, uma vez que uma pequena janela de debounce fecha. Se você gravar ou editar novamente antes que um commit debounced anterior tenha aterrissado, a nova chamada espera por ele e falha com `COMMIT_FLUSH_PENDING` se não conseguir confirmar que o commit terminou a tempo. Uma vez que um commit aterrissa:

* A alteração é visível no editor do app Base44.
* É seguro mesmo que o ambiente de computação do sandbox seja reciclado após ficar ocioso, pois um novo sempre começa a partir do seu commit mais recente em vez de um snapshot mais antigo.
* É incluída na próxima vez que você publicar o app.

Recursos estruturados sincronizam da mesma forma: diferente de um projeto local, onde você executaria [`entities push`](/developers/references/cli/commands/entities-push) ou [`functions deploy`](/developers/references/cli/commands/functions-deploy) após adicionar um arquivo, criar `base44/functions/send-email/entry.ts` no sandbox é tudo o que é necessário para adicionar essa função.

<Warning>
  * 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 push contra um app que você está editando no sandbox dele. Esses comandos sincronizam um projeto local com a Base44, e não há projeto local ao trabalhar 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`, o commit dele ainda está um momento atrás. Dê alguns segundos antes de desconectar.
</Warning>

## 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, depois restaure-o do editor do app se uma alteração posterior der errado. Alterações pendentes fazem commit antes do checkpoint ser feito, então ele sempre captura seu código mais recente.

## Trabalhando junto com o editor do app

Seu agente de codificação e o editor do app Base44 podem trabalhar no mesmo app ao mesmo tempo. Não há bloqueio para adquirir e nenhuma sessão para liberar. Alterações de qualquer lado aterrissam no mesmo lugar, então trate-o do jeito que você trataria um colega editando o mesmo projeto.

<Warning>
  Não há etapa de merge. Se seu agente de codificação e o editor do app alterarem o mesmo arquivo ao mesmo tempo, qualquer gravação que aterrissar por último vence, e a alteração anterior se vai. Evite ter os dois lados tocando no mesmo arquivo no mesmo trecho de trabalho.
</Warning>

## Permissões

Duas verificações separadas controlam o acesso ao sandbox: se você pode acessar este app e se sua sessão atual recebeu acesso de gravação 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 em cada chamada, então uma alteração no seu papel de workspace tem efeito imediatamente.

Um visualizador de workspace comum não consegue acessar o sandbox. A única exceção é um visualizador que também tem um papel legado de editor por app de antes do seu workspace mudar para acesso baseado em papel. Essa combinação ainda pode ler do 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 pede `sandbox:write` durante o `base44 login`, e pelo MCP você concede na etapa de consentimento OAuth. Renovar uma sessão existente não adiciona isso.

Então, 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 tenha.

## Limites e proteções

Comandos de arquivo são 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 e credenciais de repositório do seu app. A única exceção é `.agents/skills`, que você pode ler e gravar para que seu agente possa trabalhar com as [skills](/developers/backend/overview/skills) que o app instalou.

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

## Veja também

* [Base44 MCP server](/developers/backend/overview/mcp-server): conecte um assistente de IA à sua conta Base44
* [CLI Overview](/developers/references/cli/get-started/overview): instale e use a CLI da Base44
* [Project structure](/developers/backend/overview/project-structure): como os arquivos de projeto da Base44 são organizados
* [Local development](/developers/backend/overview/local-dev/local-development-overview): execute um projeto Base44 na sua própria máquina
* [Skills](/developers/backend/overview/skills): ensine agentes de codificação de IA a trabalhar com a Base44
* [`connectors initiate`](/developers/references/cli/commands/connectors-initiate): configure um conector em um app sem um sandbox ou projeto local

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