
Um sandbox local para seus agentes de IA
O CodeRunner ajuda a colocar seus agentes de IA e suas ações em um sandbox.
Caso de uso principal: Executar código de agentes de IA em um sandbox com montagens de host e acesso à rede escolhidos explicitamente. O isolamento reduz o risco; ele não impede toda perda ou exfiltração de dados.
Para VMs gerenciadas na nuvem para agentes, lançamos - InstaVM - Computadores instantâneos para agentes de IA
Pré-requisitos: Mac com macOS e Apple Silicon (M1/M2/M3/M4), Python 3.10+
O instalador gera o token do sandbox em ~/.coderunner/api-token (ou salva
o CODERUNNER_API_TOKEN que você exportou). Os clientes o enviam como
Authorization: Bearer <token>; cat ~/.coderunner/api-token o exibe. Apenas
GET /health é público, e um token ausente ou fraco falha de forma segura. O proxy do Claude
Desktop e os exemplos leem o token desse arquivo quando a variável
não está definida. Consulte autenticação e limites de rede.
git clone https://github.com/instavm/coderunner.git
cd coderunner
chmod +x install.sh
./install.sh
Pare o sandbox quando terminar:
container stop coderunner
Retome o mesmo sandbox mais tarde, preservando seu sistema de arquivos. O estado do kernel Python é volátil e não sobrevive a uma reinicialização da VM ou do servidor:
container start coderunner
Para começar de novo com um sandbox limpo, exclua o contêiner e execute o instalador novamente:
container delete coderunner && ./install.sh
Os limites de CPU e memória podem ser definidos com opções do instalador ou com as variáveis de ambiente CODERUNNER_CPUS e CODERUNNER_MEMORY:
./install.sh --cpus 4 --memory 8g
Diretórios adicionais do host devem ser montados em /workspace. Eles são somente leitura por padrão; adicione :rw apenas quando o sandbox precisar gravar no host:
./install.sh \
--mount "$HOME/projects/api:/workspace/api" \
--mount "$HOME/projects/output:/workspace/output:rw"
Montagens extras são, por padrão, nenhuma. As configurações de recursos e montagens são fixas quando o contêiner é criado; exclua o contêiner antes de alterá-las.
Por padrão, o código em execução no sandbox tem acesso irrestrito à rede. Para executá-lo em uma rede somente de host, sem acesso à internet:
CODERUNNER_NETWORK=none ./install.sh
Neste modo, o servidor MCP está disponível em http://127.0.0.1:8222/mcp. A configuração é fixada quando o contêiner é criado; o instalador recusa-se a retomar um contêiner com um modo de rede diferente.
O Claude Code executa comandos na sua máquina, como você, tendo os prompts de permissão como única fronteira. Apontá-lo para as ferramentas do CodeRunner, em vez disso, executa o código que ele escreve na VM: ele só pode tocar nas pastas que você montou em /workspace, na rede que você permitiu e no próprio sistema de arquivos do sandbox, independentemente do que lhe foi ordenado fazer. Use o sandbox para código que lida com entrada não confiável ou que você não executaria manualmente, e para vários agentes que não devem compartilhar estado (sessões nomeadas). Ele não protege nada que você monta como leitura-escrita.
./install.sh (se ainda não o fez)
container exec -it coderunner /bin/bash
root@coderunner:/app# npm install -g @anthropic-ai/claude-code
O servidor MCP estará disponível em: http://coderunner.local:8222/mcp
O instalador cria ~/.coderunner/venv para o proxy do Claude Desktop. Para os outros exemplos em Python, instale suas dependências no seu próprio virtualenv:
pip install -r examples/requirements.txt



Copie a configuração de exemplo:
cd examples
cp claude_desktop/claude_desktop_config.example.json claude_desktop/claude_desktop_config.json
Edite o arquivo de configuração e substitua os caminhos de placeholder:
/path/to/your/python por $HOME/.coderunner/venv/bin/python usando o caminho completo para o seu diretório home/path/to/coderunner pelo caminho real para o seu repositório clonadoExemplo após a edição:
{
"mcpServers": {
"coderunner": {
"command": "/Users/yourname/.coderunner/venv/bin/python",
"args": ["/Users/yourname/coderunner/examples/claude_desktop/mcpproxy.py"]
}
}
}
Atualize a configuração do Claude Desktop:
Comece a usar o CodeRunner no Claude: O código que o Claude escreve agora é executado no sandbox.
Se a ferramenta aparecer como "Disabled" no menu de ferramentas do chat, embora o servidor esteja listado como em execução: encerre o Claude
Desktop completamente (Cmd-Q) e abra-o novamente, certifique-se de que command seja o python do venv que o instalador exibiu (ele
tem fastmcp), e leia ~/Library/Logs/Claude/mcp-server-coderunner.log para ver o erro do proxy. O proxy
precisa do sandbox em execução (container list) e do arquivo de token ~/.coderunner/api-token.
Início Rápido:
# 1. Install and start CodeRunner (one-time setup; run as yourself, it asks for sudo when it needs it)
git clone https://github.com/instavm/coderunner.git
cd coderunner
./install.sh
# 2. Add the sandbox with its token (the installer prints this command)
claude mcp add --transport http coderunner http://coderunner.local:8222/mcp \
--header "Authorization: Bearer $(cat ~/.coderunner/api-token)"
# 3. Reconnect to MCP servers
/mcp
O plugin do Claude Code (claude plugin marketplace add https://github.com/instavm/coderunner-plugin) é anterior
ao token e recebe 401 até enviar o mesmo cabeçalho; use o comando acima até que o plugin seja atualizado.
Etapas de instalação:
Navegue até o Marketplace de Plugins:

Adicione o repositório InstaVM:

Execute código Python com o Claude Code: