Sandboxes autoalojados

Conecta tu propio entorno cuando quieras tener más control sobre el entorno del agente o usar recursos de cómputo en los que confíes. El entorno puede ser una laptop, un contenedor o un sandbox remoto. Para 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. Este ejecuta comandos de shell, lee y escribe archivos y usa servidores MCP locales a petición del arnés de ejecución.

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. El ejecutor vuelve a conectarse si se interrumpe la conexión.

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.

Crea el directorio de trabajo e instala Codex CLI dentro del entorno. Este ejemplo usa /workspace:

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

Acceso a la red

Permite conexiones salientes a estos hosts:

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

Autenticación

Usa OPENAI_API_KEY para las solicitudes de la aplicación. Asígnale 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. Debe pertenecer a la misma organización, al mismo proyecto y al mismo usuario o cuenta de servicio que la sesión. Establece todos los demás permisos en Ninguno.

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

El código generado por el agente puede leer la clave de entorno, pero esta solo permite conectar entornos. No puede autorizar ninguna otra acción de la API. No la incluyas en el código fuente, las imágenes de contenedores ni 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 de 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. Consulta Configuración de agentes para usar un agente guardado.

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 este comando dentro del entorno con la clave de entorno configurada como CODEX_API_KEY, según se indicó antes. Reemplaza los marcadores de posición por los valores del entorno devueltos por la API:

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

Deja el ejecutor en ejecución mientras el agente trabaja.

Envía trabajo y monitorea la conexión

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

El flujo informa estos 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: la conexión falló. Revisa el error del entorno y los registros del ejecutor.

Sigue el flujo para conocer el resultado del turno y obtener su 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 el aprovisionamiento gestionado mediante webhooks, implementa un manejador siguiendo Ciclo de vida del sandbox y usando el SDK o la API de tu proveedor. Define explícitamente quién es responsable del aprovisionamiento y cuáles son las políticas de limpieza.