Sandboxes autoalojados

Conecta tu propio entorno si quieres tener más control sobre el entorno del agente o usar recursos de cómputo de confianza. El entorno puede ser una computadora portátil, un contenedor o un sandbox remoto. Si prefieres que OpenAI aprovisione el entorno, usa un sandbox alojado por OpenAI.

Cómo funciona la conexión

OpenAI ejecuta el arnés de ejecución del agente. Tú ejecutas codex exec-server, el ejecutor, dentro de tu entorno. A petición del arnés de ejecución, el ejecutor ejecuta comandos de shell, lee y escribe archivos y usa servidores MCP locales.

El ejecutor se registra en la API con un ID de entorno y una clave de API restringida. Luego se conecta mediante WebSocket para recibir comandos y devolver resultados. Todas las conexiones son salientes. Si se interrumpe la conexión, el ejecutor vuelve a conectarse.

Prepara tu entorno

Prepara los archivos y las dependencias que necesita tu agente. Aísla los entornos por usuario o carga de trabajo. Los agentes que comparten un entorno pueden acceder a los mismos archivos, credenciales y otros recursos.

Para habilitar la revisión automática con review: "auto_review", inicia el ejecutor estándar en un contenedor que admita la ejecución en entornos aislados y permita que Codex cree un sandbox. La revisión automática aplica un perfil de permisos que usa workspace-write como base y restringe el acceso a la red. Consulta los requisitos previos de la revisión automática antes de habilitarla.

Crea el directorio de trabajo e instala la CLI de Codex dentro del entorno. En este ejemplo se usa /workspace:

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

Acceso a la red

Permite conexiones salientes a los siguientes hosts:

• https://api.openai.com para registrar el entorno.
• wss://codex-cloud-environments.chatgpt.com para intercambiar comandos y resultados.

Autenticación

Usa OPENAI_API_KEY para las solicitudes de tu aplicación. Concédele los permisos api.agents.read y api.agents.write para las operaciones de sesión, además de api.responses.write para la inferencia del modelo. Agrega api.vaults.read y api.vaults.write si tu aplicación administra bóvedas.

Crea una clave de entorno independiente en la pestaña Agentes del panel de la plataforma. La clave debe pertenecer a la misma organización y al mismo proyecto que la sesión, así como al usuario o a la cuenta de servicio titular de esa sesión. Configura todos los demás permisos como Ninguno.

Asigna esta clave de entorno a OPENAI_EXECUTOR_API_KEY en tu aplicación o servicio de aprovisionamiento. Pasa su valor al sandbox mediante CODEX_API_KEY, la variable que lee codex exec-server. Mantén la clave OPENAI_API_KEY de tu aplicación fuera del sandbox.

El código generado por el agente puede leer la clave de entorno, pero la clave solo permite conectar entornos. No puede autorizar ninguna otra acción de la API. Evita incluirla en el código fuente, las imágenes de contenedores y los registros. Rótala o revócala cuando sea necesario.

Crea una sesión

Ejecuta este ejemplo en tu aplicación, fuera del entorno. Si ya tienes una sesión autoalojada, reutilízala.

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

Guarda session.id junto con el estado de la conversación en tu aplicación. Pasa session.environment.id y session.environment.remote_url al ejecutor. Usa la URL remota sin modificarla, incluso al volver a conectarte. Para usar un agente guardado, consulta Configuración de agentes.

Puedes reutilizar la imagen de tu entorno, workspace_directory y capability_directories en distintas sesiones. Cada sesión tiene su propio ID de entorno y necesita su propio ejecutor. Las plantillas de entorno de la API solo se aplican a los entornos alojados por OpenAI.

Inicia el ejecutor

Abre el flujo de eventos de la sesión desde tu aplicación para recibir eventos de conexión. Luego ejecuta el siguiente comando dentro del entorno con la clave de entorno configurada en CODEX_API_KEY como se indicó antes. Reemplaza los marcadores de posición por los valores del entorno que devuelve la API:

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

Mantén el ejecutor en funcionamiento mientras el agente trabaja.

Envía tareas y monitorea la conexión

Envía datos de entrada desde tu aplicación mientras mantienes abierto el flujo de eventos. Para empezar a trabajar, el agente necesita tanto un entorno conectado como datos de entrada del usuario.

El flujo informa los siguientes estados de conexión:

• agent.session.environment.pending: la sesión está esperando a que se conecte el ejecutor.
• agent.session.environment.connected: el entorno está listo.
• agent.session.environment.failed: falló la conexión. Revisa el error del entorno y los registros del ejecutor.

Sigue monitoreando el flujo para conocer el resultado del turno y recibir los datos de salida. Consulta Ciclo de vida del entorno para gestionar el inicio, la reconexión y el apagado desde tu aplicación o mediante webhooks.

Proveedores de sandboxes

Elige un proveedor de sandboxes para ejecutar código y trabajar con archivos. Consulta Ciclo de vida del sandbox para comparar el aprovisionamiento gestionado por la aplicación con el gestionado mediante webhooks.

Para gestionar el aprovisionamiento mediante webhooks, implementa un manejador con ayuda de la guía Ciclo de vida del sandbox y del SDK o la API de tu proveedor. Define explícitamente quién se encarga del aprovisionamiento y qué políticas rigen la limpieza de recursos.