Execução de código no Cloud Run

Com os sandboxes do Cloud Run, é possível executar código não confiável em um ambiente isolado diretamente nas cargas de trabalho de contêiner. Esse recurso ajuda os agentes de IA a executar subagentes, tarefas computacionais ou navegadores automatizados com segurança sem arriscar o sistema host.

Veja as principais vantagens

Os sandboxes do Cloud Run oferecem as seguintes vantagens principais:

• Criação rápida: os sandboxes são interativos e estão prontos para executar comandos quase instantaneamente. Ao criar sandboxes em um recurso do Cloud Run em que o agente é executado, você reduz os tempos de criação em comparação com a criação de um novo recurso do Cloud Run para cada tarefa. Essa eficiência ajuda a garantir que o agente permaneça responsivo.

• Segurança: os sandboxes isolam a execução de processos. Por padrão, os sandboxes não têm acesso à carga de trabalho principal, às variáveis de ambiente, aos secrets ou ao servidor de metadados Cloud de Confiance by S3NS . Todas as sandbox são completamente isoladas umas das outras.

• Controle de acesso e ambiente: os processos são executados com privilégios sudo como um usuário raiz, permitindo que você instale ferramentas usando gerenciadores de pacotes como apt, pip ou npm durante a execução. Embora o ambiente de sandbox seja efêmero e excluído após a conclusão, é possível usar diretórios permanentes ou snapshots para salvar espaços de trabalho específicos ou mapear dados para um bucket do Cloud Storage.

Antes de começar

1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Go to project selector

2. Verify that billing is enabled for your Cloud de Confiance project.

3. Instale e inicialize a CLI gcloud.
4. Implante um recurso do Cloud Run, como um serviço, um job, um pool de trabalhadores ou uma instância de segunda geração.

• Serviços
• Jobs
• Pools de workers
• Instâncias (prévia)

Iniciar sandboxes

Depois de ativar os sandboxes, você pode iniciá-los no ambiente de execução do contêiner. O binário da sandbox está localizado em /usr/local/gcp/bin/sandbox.

Os exemplos neste guia usam o comando sandbox em vez do caminho absoluto /usr/local/gcp/bin/sandbox.

Para executar o binário, faça referência ao caminho absoluto dele no código-fonte. Por exemplo, para imprimir Hello na sua sandbox isolada, escolha uma das seguintes opções:

exec(`sandbox do -- /bin/echo "Hello"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

import subprocess
result = subprocess.run(
    ["sandbox", "do", "--", "/bin/echo", "Hello"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

cmd := exec.Command("sandbox", "do", "--", "/bin/echo", "Hello")
out, err := cmd.CombinedOutput()

sandbox do -- /bin/echo "Hello"

Para conferir a lista completa de comandos disponíveis, execute o comando sandbox -h.

Usar os recursos da linha de comando do sandbox

A ferramenta de linha de comando sandbox contém comandos para executar, configurar e gerenciar sandboxes.

Executar um comando no sandbox

É possível executar uma instrução em um novo sandbox efêmero usando o comando sandbox do. O comando sandbox do executa as seguintes tarefas:

1. Cria um ambiente de sandbox (sandbox run).
2. Executa o comando especificado (sandbox exec).
3. Exclui a sandbox após a execução (sandbox delete).

Por exemplo, para fazer um cálculo matemático na sandbox, execute os snippets de código a seguir no seu idioma preferido. Verifique se todos os comandos ou ferramentas que você executa, como python3, estão instalados na imagem do contêiner:

exec(`sandbox do -- /usr/bin/python3 -c "print(1+2)"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

import subprocess
result = subprocess.run(
    ["sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

cmd := exec.Command("sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)")
out, err := cmd.CombinedOutput()

sandbox do -- /usr/bin/python3 -c "print(1+2)"

Se você executar um comando por nome sem o caminho absoluto, como python3 em vez de /usr/bin/python3, configure explicitamente a variável de ambiente PATH na sandbox usando a flag --env.

Manter dados em diferentes execuções

As sandbox são efêmeras por padrão. Para persistir dados em diferentes execuções de sandbox na mesma instância do Cloud Run, importe e exporte o estado do sistema de arquivos do espaço de trabalho usando arquivos de arquivo tar padrão. Como alternativa, é possível configurar bind mounts para compartilhar diretórios diretamente entre o contêiner host e os ambientes de sandbox.

Use as seguintes flags ao executar o comando sandbox do:

• --export-tar: captura arquivos de sobreposição modificados em um arquivo tar ao concluir.
• --import-tar: extrai arquivos de um arquivo tar para a sandbox antes da execução.
• --sync-tar: realiza uma sincronização bidirecional importando antes da execução e exportando após a conclusão.

Por exemplo, para transmitir dados entre duas chamadas de sandbox usando arquivos compactados, execute os seguintes comandos:

1. Gravar dados em uma sandbox e exportar o estado para um arquivo de arquivamento:

   sandbox do --write --export-tar=/tmp/work.tar \
     -- /usr/bin/bash -c "mkdir -p /tmp/work && echo 'task-complete' > /tmp/work/status.txt"
   

2. Importe o arquivo de arquivamento em uma chamada subsequente para recuperar os dados:

   sandbox do --write --import-tar=/tmp/work.tar \
     -- /usr/bin/bash -c "cat /tmp/work/status.txt"
   

Como alternativa, para importar automaticamente o estado do arquivo atual e exportar novas mudanças em um único comando, use --sync-tar=/tmp/work.tar. Quando um processo de sandbox é encerrado, o Cloud Run exclui permanentemente arquivos de sobreposição efêmeros que não foram exportados para um arquivo de arquivamento.

Executar um comando em segundo plano

Para executar processos de longa duração, navegadores headless ou servidores em segundo plano, como um loop de agente em segundo plano que ouve continuamente as solicitações recebidas, use a flag --detach.

Por exemplo, execute o comando a seguir para iniciar uma sandbox independente com um programa ocioso ou em segundo plano:

sandbox run my-web-server --detach -- /usr/bin/long_running_or_idle_program

Você pode usar a flag detach para reutilizar o mesmo sandbox em vários testes. Para interagir ou executar outros comandos em um sandbox independente em execução, use o comando sandbox exec e direcione o sandbox pelo nome.

Por exemplo, para executar um comando de teste na sua sandbox em segundo plano my-web-server, execute o seguinte comando:

sandbox exec my-web-server -- /usr/bin/python3 -c "print('test-complete')"

Configure as variáveis de ambiente

Configure variáveis de ambiente em sandboxes como faria com qualquer outro contêiner. As caixas de areia não herdam variáveis de ambiente do contêiner host. É necessário fornecê-los explicitamente usando a flag --env ao executar o comando sandbox.

Por exemplo, para transmitir uma variável de configuração para uma sandbox, execute o seguinte comando:

sandbox do --env AGENT_MODE="test" -- /usr/bin/bash -c "echo \$AGENT_MODE"

Evite transmitir secrets usando a flag env, porque eles podem ficar visíveis para os processos da sandbox.

Criar snapshots do sistema de arquivos

Implante um sandbox nomeado em segundo plano para lidar com tarefas contínuas, como servidores da Web ou Agentic Workflows de longa duração, execute comandos no sandbox de forma dinâmica e capture o estado modificado do sistema de arquivos em um arquivo de arquivo tar.

Por exemplo, para implantar uma sandbox em segundo plano, gravar um arquivo na sobreposição dela e criar um snapshot do estado para verificar se os dados foram capturados, execute os seguintes comandos:

1. Implante um sandbox nomeado em segundo plano com acesso de gravação ativado, criando um arquivo no espaço de trabalho dele:

   sandbox run --write my-sandbox --detach -- /usr/bin/bash -c "echo 'hi' > /tmp/hello.txt && sleep 1h"
   

2. Crie um snapshot do sistema de arquivos modificado da sandbox em execução usando o comando sandbox tar:

   sandbox tar my-sandbox --file=/tmp/foo.tar
   

3. Extraia e verifique se o arquivo de snapshot contém os dados gravados na caixa de areia:

   tar -xvf /tmp/foo.tar
   

   Você deve ver os seguintes resultados:

   ./
   ./tmp/
   ./tmp/hello.txt
   

Configurar rede

Por padrão, todo o tráfego de saída da sandbox é bloqueado. Para permitir o acesso à rede de saída, use a flag --allow-egress:

Por exemplo, para buscar dados de um endpoint externo, execute o seguinte comando:

sandbox do --allow-egress -- /usr/bin/python3 -c 'import urllib.request; print(urllib.request.urlopen("https://google.com").getcode())'

Esse comando retorna o código de status HTTP padrão 200, indicando uma conexão bem-sucedida.

Acessar o sistema de arquivos

Por padrão, os processos executados na sandbox têm acesso somente leitura ao sistema de arquivos raiz do contêiner host. Use a flag --write para ativar a gravação em uma sobreposição de sistema de arquivos temporário (tmpfs). No entanto, as gravações serão perdidas quando o sandbox for excluído. Para ativar a gravação permanente no contêiner host, configure montagens de vinculação.

Acesso padrão somente leitura

Dentro da sandbox, os processos podem ler arquivos do contêiner host, mas não podem gravar no sistema de arquivos raiz.

Os exemplos a seguir pressupõem que você está executando comandos no diretório raiz (/) do contêiner host.

Para verificar o acesso padrão somente leitura, execute os seguintes comandos:

1. Crie um script Python no contêiner host:

   mkdir -p /tmp/my-scripts
   echo "print('hi')" > /tmp/my-scripts/task.py
   

2. Verifique se o arquivo existe localmente:

   cat /tmp/my-scripts/task.py
   

3. Execute o arquivo na sua sandbox:

   sandbox do -- /usr/bin/python3 /tmp/my-scripts/task.py
   

   Esse comando retorna hi, confirmando que a sandbox tem acesso de leitura.

   Se você tentar gravar dados diretamente no sistema de arquivos raiz da sandbox sem configuração adicional, a execução vai falhar. Por exemplo, tentar gravar em /tmp dentro da sandbox padrão retorna um erro de sistema de arquivos somente leitura:

   Execute o comando a seguir para gravar no sistema de arquivos raiz:

   sandbox do -- /usr/bin/bash -c "echo 'hi' > /tmp/testfile.txt"
   

   O comando falha com o seguinte erro:

   /usr/bin/bash: line 1: /tmp/testfile.txt: Read-only file system
   Error: failed to exec in container: cmd.Wait(exec) failed: exit status 1
   

Compartilhar dados usando vinculações de montagem

Para permitir que processos dentro do sandbox gravem dados persistentes, anexe um volume compartilhado usando a flag --mount:

1. Crie um diretório de volume compartilhado no contêiner host e adicione um arquivo inicial:

   mkdir -p /tmp/my-volume
   echo 'read' > /tmp/my-volume/readwrite.txt
   

2. Execute o sandbox para ler o arquivo do caminho de vinculação de montagem:

   sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "cat /mnt/my-mount/readwrite.txt"
   

   Esse comando retorna read.

3. Execute o sandbox para gravar novos dados de volta no host de dentro da montagem:

   sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "echo 'write' > /mnt/my-mount/readwrite.txt"
   

4. Verifique no contêiner host se o sandbox modificou o arquivo:

   cat /tmp/my-volume/readwrite.txt
   

   Esse comando retorna write.

Configurar montagens somente leitura

Para conceder ao sandbox acesso a um diretório de host e impedir explicitamente que ele modifique arquivos, adicione o atributo readonly à especificação de montagem.

Por exemplo, execute o seguinte comando para testar restrições de gravação em uma ativação de vinculação somente leitura:

sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount,readonly -- /usr/bin/bash -c "echo 'fails' > /mnt/my-mount/hello.txt"

A tentativa de gravação falha com o seguinte erro:

/usr/bin/bash: line 1: /mnt/my-mount/hello.txt: Read-only file system
Error: failed to exec in container: cmd.Wait(exec) failed: exit status 1

Como visualizar registros

O Cloud Run captura automaticamente eventos de ciclo de vida da sandbox, como início e saída da execução, no Cloud Logging.

A CLI sandbox grava a saída padrão (stdout) e o erro padrão (stderr) de comandos em sandbox diretamente nos streams padrão do processo de invocação. Para ver esses registros no Cloud Logging, direcione os streams para a saída padrão e o erro padrão do contêiner:

const { exec } = require('child_process');
const child = exec('sandbox do -- /usr/bin/python3 -c "print(1+2)"');
child.stdout.pipe(process.stdout);
child.stderr.pipe(process.stderr);

subprocess.run(
    ["sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)"],
    stdout=sys.stdout,
    stderr=sys.stderr,
)

cmd := exec.Command("sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)")
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
cmd.Run()

A seguir

• Saiba mais sobre a hospedagem de agentes de IA no Cloud Run.
• Conheça a automação de navegador e SO no Cloud Run.
• Leia o contrato de ambiente de execução do contêiner.