OpenAI Agents API - Upstash Documentation

Run the commands of the OpenAI Agents API in Upstash Box. The agent runs on OpenAI’s side, and each session gets its own box where its commands run. Every box includes the Codex CLI, so there is nothing to install.

1. Get your keys

A Box API key from the Upstash Console.
An OpenAI API key from API keys.
An environment key from Agents → Environments → Keys, in the same project. It’s the only OpenAI key that goes into the box.

.env

UPSTASH_BOX_API_KEY=box_xxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxx
OPENAI_EXECUTOR_KEY=sk-proj-xxxxxxxxxxxx

npm install @upstash/box openai tsx

2. Run a session

session.ts

import OpenAI from "openai";
import { Box } from "@upstash/box";

const openai = new OpenAI();

const session = await openai.beta.agents.sessions.create({
  agent: { model: "gpt-6-astra", instructions: "You work in /workspace/home." },
  environment: { type: "self_hosted", workspace_directory: "/workspace/home" },
});

if (session.environment.type !== "self_hosted") throw new Error("Expected a self-hosted environment");
const { id, remote_url } = session.environment;

const box = await Box.create({
  runtime: "node",
  name: session.id,
  env: { CODEX_API_KEY: process.env.OPENAI_EXECUTOR_KEY! },
});

const startExecutor =
  `setsid nohup flock -n /tmp/codex.lock codex exec-server --remote '${remote_url}' ` +
  `--environment-id '${id}' >> executor.log 2>&1 < /dev/null &`;

await box.exec.command(startExecutor);

const events = await openai.beta.agents.sessions.events.stream(session.id);

await openai.beta.agents.sessions.events.create(session.id, {
  events: [
    {
      type: "agent.session.input.message",
      input: [
        {
          role: "user",
          content: [{ type: "input_text", text: "Write a Node script that prints the first 20 primes and run it." }],
        },
      ],
    },
  ],
});

for await (const event of events) {
  if (event.type === "agent.session.environment.failed") throw new Error("Executor failed, see executor.log");
  if (event.type === "agent.session.turn.output_text.delta") process.stdout.write(event.delta);
  if (event.type === "agent.session.turn.completed" && !event.turn.subagent_id) break;
}

await box.pause();
console.log(`\nSESSION_ID=${session.id} BOX_ID=${box.id}`);

npx tsx --env-file=.env session.ts

The agent’s commands run in the box. When the turn is done, the box is paused and keeps its files.

3. Continue later

Pass the printed IDs to continue the same session in the same box:

resume.ts

import OpenAI from "openai";
import { Box } from "@upstash/box";

const [sessionId, boxId] = process.argv.slice(2);
const openai = new OpenAI();

const session = await openai.beta.agents.sessions.retrieve(sessionId);
if (session.environment.type !== "self_hosted") throw new Error("Expected a self-hosted environment");
const { id, remote_url } = session.environment;

// Resumes the box and starts the executor again. flock skips it if one is already running.
const box = await Box.get(boxId);
await box.exec.command(
  `setsid nohup flock -n /tmp/codex.lock codex exec-server --remote '${remote_url}' ` +
    `--environment-id '${id}' >> executor.log 2>&1 < /dev/null &`,
);

const events = await openai.beta.agents.sessions.events.stream(sessionId);

await openai.beta.agents.sessions.events.create(sessionId, {
  events: [
    {
      type: "agent.session.input.message",
      input: [{ role: "user", content: [{ type: "input_text", text: "Run the script you wrote again." }] }],
    },
  ],
});

for await (const event of events) {
  if (event.type === "agent.session.environment.failed") throw new Error("Executor failed, see executor.log");
  if (event.type === "agent.session.turn.output_text.delta") process.stdout.write(event.delta);
  if (event.type === "agent.session.turn.completed" && !event.turn.subagent_id) break;
}

await box.pause();

npx tsx --env-file=.env resume.ts <SESSION_ID> <BOX_ID>

When you are done, delete the session, then the box:

await openai.beta.agents.sessions.delete(sessionId);
await box.delete();

Customize the box

Pass any Box.create option when you create the box:

Box.create({
  runtime: "node",
  name: session.id,
  env: { CODEX_API_KEY: process.env.OPENAI_EXECUTOR_KEY! },
  // Added to matching requests by the network proxy, never visible inside the box
  attachHeaders: {
    "api.github.com": { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` },
  },
  // Only these domains are reachable
  networkPolicy: {
    mode: "custom",
    allowedDomains: ["api.openai.com", "codex-cloud-environments.chatgpt.com", "api.github.com"],
  },
});

CODEX_API_KEY is readable inside the box, which is why it must be the environment key. Open a server the agent started with box.getPublicURL(3000). To start every box with your own tools or repo, create it with Box.fromSnapshot instead.

Troubleshooting

Script waits and prints nothing: the executor didn’t connect. Check /workspace/home/executor.log in the box.
missing required scope api.agents.environments.connect: OPENAI_EXECUTOR_KEY must be an environment key, not a regular API key.

​1. Get your keys

​2. Run a session

​3. Continue later

​Customize the box

​Troubleshooting

1. Get your keys

2. Run a session

3. Continue later

Customize the box

Troubleshooting