Sandboxes auto-hospedados

Conecte seu próprio ambiente se quiser ter mais controle sobre o ambiente do agente ou usar recursos computacionais em que confia. Esse ambiente pode ser um notebook, um contêiner ou um sandbox remoto. Se preferir que a OpenAI provisione o ambiente, use um sandbox hospedado pela OpenAI.

Como funciona a conexão

A OpenAI executa o harness do agente. No seu ambiente, você executa codex exec-server, o executor. A pedido do harness, o executor roda comandos de shell, lê e grava arquivos e usa servidores MCP locais.

O executor se registra na API com um ID de ambiente e uma chave de API com permissões restritas. Em seguida, conecta-se via WebSocket para receber comandos e devolver resultados. Todas as conexões são de saída. Se a conexão cair, o executor se reconecta.

Prepare seu ambiente

Prepare os arquivos e as dependências de que o agente precisa. Isole os ambientes por usuário ou carga de trabalho. Agentes que compartilham um ambiente podem acessar os mesmos arquivos, credenciais e outros recursos.

Para habilitar a revisão automática com review: "auto_review", execute o executor padrão em um contêiner que ofereça suporte a ambientes isolados e permita que o Codex crie um sandbox. A revisão automática aplica um perfil de permissões que usa workspace-write como base e restringe o acesso à rede. Verifique os pré-requisitos da revisão automática antes de habilitá-la.

Crie o diretório de trabalho e instale a CLI do Codex no ambiente. Este exemplo usa /workspace:

mkdir -p /workspace
npm install -g @openai/codex@alpha

Acesso à rede

Permita conexões de saída para os seguintes hosts:

• https://api.openai.com para registrar o ambiente.
• wss://codex-cloud-environments.chatgpt.com para receber comandos e enviar resultados.

Autenticação

Use OPENAI_API_KEY nas requisições do aplicativo. Conceda a essa chave as permissões api.agents.read e api.agents.write para operações de sessão e api.responses.write para inferência do modelo. Adicione api.vaults.read e api.vaults.write se o aplicativo gerenciar cofres.

Crie uma chave de ambiente separada na aba Agentes do painel da plataforma. A chave deve pertencer à mesma organização e ao mesmo projeto da sessão, além de pertencer ao usuário ou à conta de serviço que detém a sessão. Defina todas as demais permissões como Nenhuma.

No aplicativo ou no serviço de provisionamento, atribua essa chave de ambiente a OPENAI_EXECUTOR_API_KEY. Passe o valor para o sandbox na variável CODEX_API_KEY, que o codex exec-server lê. Mantenha a OPENAI_API_KEY do aplicativo fora do sandbox.

O código gerado pelo agente pode ler a chave de ambiente, mas ela só permite conectar ambientes. A chave não autoriza nenhuma outra ação na API. Mantenha-a fora do código-fonte, das imagens de contêiner e dos logs. Substitua ou revogue a chave quando necessário.

Crie uma sessão

Execute este exemplo no aplicativo, fora do ambiente. Se você já tiver uma sessão auto-hospedada, reutilize-a.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import OpenAI from "openai";
const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "You are a helpful coding assistant. Write clean code and verify that it works.",
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
  },
});

console.log(session);

1
2
3
4
5
6
7
8
9
10
11
12from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "You are a helpful coding assistant. Write clean code and verify that it works.",
    },
    environment={"type": "self_hosted", "workspace_directory": "/workspace"},
)
print(session.to_json())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{
			Model:        openai.String("gpt-6-astra"),
			Instructions: openai.String("You are a helpful coding assistant. Write clean code and verify that it works."),
		},
		Environment: openai.EnvironmentParamUnion{
			OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace"},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions(
                            "You are a helpful coding assistant. Write clean code and verify"
                                + " that it works.")
                        .build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .build())
                .build());
System.out.println(result);

1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent: {
    model: "gpt-6-astra",
    instructions: "You are a helpful coding assistant. Write clean code and verify that it works."
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace"
  }
)
puts result

Armazene session.id junto com o estado da conversa no aplicativo. Passe session.environment.id e session.environment.remote_url para o executor. Use a URL remota sem alterações, inclusive ao se reconectar. Para usar um agente já armazenado, consulte Configuração de agentes.

Você pode reutilizar a imagem do ambiente, workspace_directory e capability_directories em várias sessões. Cada sessão tem seu próprio ID de ambiente e precisa de um executor próprio. Os modelos de ambiente da API se aplicam apenas a ambientes hospedados pela OpenAI.

Inicie o executor

Abra o fluxo de eventos da sessão no aplicativo para receber eventos de conexão. Em seguida, execute o comando abaixo dentro do ambiente, com a chave de ambiente configurada em CODEX_API_KEY conforme descrito acima. Substitua os marcadores pelos valores do ambiente retornados pela API:

123codex exec-server \
  --remote "<session.environment.remote_url>" \
  --environment-id "<session.environment.id>"

Mantenha o executor em execução enquanto o agente trabalha.

Envie tarefas e monitore a conexão

Envie dados de entrada pelo aplicativo enquanto o fluxo de eventos estiver aberto. Para começar a trabalhar, o agente precisa de um ambiente conectado e de dados de entrada do usuário.

O fluxo informa os seguintes estados de conexão:

• agent.session.environment.pending: a sessão aguarda a conexão do executor.
• agent.session.environment.connected: o ambiente está pronto.
• agent.session.environment.failed: a conexão falhou. Verifique o erro do ambiente e os logs do executor.

Continue acompanhando o fluxo para ver o resultado do turno e a saída gerada. Consulte Ciclo de vida do ambiente para gerenciar a inicialização, a reconexão e o encerramento pelo aplicativo ou via webhooks.

Provedores de sandbox

Escolha um provedor de sandbox para executar código e trabalhar com arquivos. Consulte Ciclo de vida do sandbox para comparar o provisionamento gerenciado pelo aplicativo com o gerenciado por webhooks.

Para gerenciar o provisionamento via webhooks, implemente uma função para tratar os eventos seguindo as instruções em Ciclo de vida do sandbox e usando o SDK ou a API do provedor. Defina explicitamente quem é responsável pelo provisionamento e quais políticas regem a limpeza dos recursos.