Docs/ Assistente IA/ AI Sandbox

AI Sandbox

Um container Alpine Linux completo que dá ao assistente IA acesso prático ao ambiente da sua aplicação para depuração, teste e análise.

O que é o AI Sandbox

O AI Sandbox é um container Alpine Linux dedicado que roda ao lado da sua aplicação. Ele compartilha o namespace de rede do app, o que significa que pode alcançar seu app via localhost, e tem acesso aos volumes montados do app. Isso dá ao assistente IA um ambiente real para trabalhar — não uma simulação.

Dentro do sandbox, a IA pode instalar pacotes, clonar repositórios, construir e rodar aplicações, inspecionar arquivos, testar conectividade de rede e executar comandos arbitrários. É a diferença entre uma IA que lê logs e adivinha, e uma IA que pode realmente investigar seu serviço em execução.

Habilitando o Sandbox

O sandbox é desabilitado por padrão. Para habilitá-lo, vá à página Settings do seu app no dashboard e ative AI Sandbox. Alternativamente, use a API:

Terminal

curl -X PATCH https://your-server:9000/api/v1/apps/:id \
  -H "Authorization: Bearer $SH0_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sandbox_enabled": true}'

Tip

O sandbox é criado sob demanda quando a primeira ferramenta de sandbox é chamada. Se você ativar sandbox_enabled mas nunca usar uma ferramenta de sandbox, nenhum container é criado.

Especificações do Container

Cada container sandbox é provisionado com as seguintes especificações:

Propriedade	Valor
Image	Alpine 3.19
User	root
RAM	1 GB
CPU	2 cores
Network	Compartilhada com o app (modo de rede do container)
Volumes	Volumes do app montados (graváveis)
Command timeout	5 minutos
Output limit	100 KB
Pre-installed tools	`curl`, `wget`, `dig`, `nc`, `jq`, `git`, `node`, `npm`, `python3`, `pip`, `bash`

O que a IA Pode Fazer

Com acesso ao sandbox, o assistente IA pode realizar depuração e análise práticas:

Depurar endpoints da aplicação

Como o sandbox compartilha a rede do app, a IA pode chamar sua aplicação diretamente:

Sandbox

curl localhost:3000/health
curl -v localhost:8080/api/users | jq .

Analisar código-fonte e dependências

Clone o repositório, instale dependências e inspecione o projeto:

Sandbox

git clone https://github.com/user/app.git /tmp/app
cd /tmp/app && npm install
npm audit

Testar conectividade

Verifique que os serviços conseguem se comunicar:

Sandbox

nc -zv db 5432
dig redis.internal
curl -s http://api:8000/healthz

Inspecionar arquivos e logs

Leia arquivos de configuração, arquivos de ambiente e saída de log dos volumes montados:

Sandbox

cat /app/config/production.json
ls -la /app/logs/
tail -100 /app/logs/error.log

Executar código e testar correções

Execute scripts e valide correções antes de aplicá-las à aplicação real:

Sandbox

python3 -c "import json; print(json.loads(open('/app/config.json').read()))"
node -e "const db = require('./db'); db.ping().then(console.log)"

Ferramentas do Sandbox

A IA interage com o sandbox através de cinco ferramentas MCP dedicadas:

Ferramenta	Risco	Descrição	Exemplo
`sandbox_exec`	Medium	Executar um comando no container sandbox	`curl localhost:3000/health`
`sandbox_read_file`	Low	Ler um arquivo do sistema de arquivos do sandbox	`/app/config.json`
`sandbox_write_file`	High	Escrever um arquivo no sistema de arquivos do sandbox	`/tmp/test-script.sh`
`sandbox_status`	Low	Verificar se o sandbox está rodando e saudável	--
`sandbox_reset`	Medium	Destruir e recriar o container sandbox	--

Ciclo de Vida

O container sandbox segue o ciclo de vida da sua aplicação pai:

Criado: Sob demanda quando a primeira ferramenta de sandbox é invocada. A criação é não-bloqueante e acontece assincronamente após o deploy.
Iniciado: Automaticamente quando o app pai inicia. O sandbox continua rodando enquanto o app estiver rodando.
Parado: Quando o app pai é parado. O container sandbox é parado junto.
Destruído: Quando o app pai é excluído. O container sandbox e todos os seus dados são removidos permanentemente.

O sandbox não tem política de reinício. Se ele travar, permanece parado até que a próxima chamada de ferramenta de sandbox acione uma recriação.

Validação de Comandos

O sandbox aplica uma lista de bloqueio mínima para prevenir operações catastróficas. Os seguintes comandos são rejeitados:

rm -rf / — destruição do sistema de arquivos
mkfs — formatação de disco
shutdown / reboot — operações a nível de host
Fork bombs (ex.: padrões :())

Todo o resto é permitido. O sandbox é intencionalmente permissivo porque seu propósito é dar à IA as mesmas capacidades que um desenvolvedor humano teria ao depurar. O container em si é a fronteira de segurança, não o filtro de comandos.

Modelo de Segurança

O modelo de segurança do sandbox se baseia em isolamento de container em vez de filtragem de comandos:

Sistema de arquivos isolado: O sandbox tem seu próprio sistema de arquivos raiz. Apenas volumes explicitamente montados são compartilhados com o app.
Limites de recursos: Caps rígidos de RAM (1 GB) e CPU (2 cores) previnem exaustão de recursos no host.
Descartável: O container pode ser destruído e recriado a qualquer momento sem afetar a aplicação.
Sem política de reinício: Um sandbox que travou não reinicia automaticamente, prevenindo loops infinitos de crash.
Timeout de comando: Cada comando tem um timeout de 5 minutos para prevenir processos descontrolados.
Cap de saída: A saída de comandos é truncada em 100 KB para prevenir exaustão de memória no transporte MCP.

Warning

O sandbox tem acesso de escrita aos volumes do seu app. Embora isso seja necessário para que a IA depure e teste corretamente, esteja ciente de que a IA pode modificar arquivos nos volumes montados.

MCP Server

Tools Reference