@denieler/e2b-codex 0.1.0

package/README.md

@@ -0,0 +1,213 @@
+# @denieler/e2e-codex
+
+Use a shared E2B template with Codex preinstalled, then create fresh sandboxes from that template and talk to `codex app-server` over websocket.
+
+![e2b-codex banner](./assets/e2b-codex-banner.svg)
+
+This project covers two jobs:
+
+- runtime use: create a sandbox, connect to Codex, send prompts, continue conversations
+- template development: build and publish the shared E2B template
+
+## Runtime Use
+
+Install the package:
+
+```bash
+npm install @denieler/e2e-codex
+```
+
+### What you need
+
+- `E2B_API_KEY`
+- `OPENAI_API_KEY`
+- `E2B_TEMPLATE_ID`
+
+`E2B_TEMPLATE_ID` must point to a template that already has Codex installed.
+
+### Run one prompt
+
+If you just want to verify the full flow, run:
+
+```bash
+E2B_TEMPLATE_ID=<template-id> doppler run -- npm run example:prompt -- "Reply with exactly: test-ok"
+```
+
+What this does:
+
+1. Creates a new sandbox from `E2B_TEMPLATE_ID`
+2. Starts `codex app-server` inside the sandbox
+3. Opens an authenticated websocket connection
+4. Starts a Codex thread
+5. Sends one prompt
+6. Returns the final reply
+
+### Create a ready sandbox in code
+
+```ts
+import { createReadyCodexSandbox } from "@denieler/e2e-codex";
+
+const ready = await createReadyCodexSandbox({
+  e2bApiKey: process.env.E2B_API_KEY!,
+  templateId: process.env.E2B_TEMPLATE_ID!,
+  openAiApiKey: process.env.OPENAI_API_KEY!,
+  userId: "user-123",
+});
+```
+
+The returned object includes:
+
+- `sandboxId`
+- `websocketUrl`
+- `authToken`
+- `workspaceRoot`
+
+### Connect to Codex over websocket
+
+```ts
+import { connectCodexClient } from "@denieler/e2e-codex";
+
+const client = await connectCodexClient(ready);
+```
+
+### Start a conversation
+
+```ts
+const started = await client.request("thread/start", {
+  model: "gpt-5.3-codex",
+  cwd: ready.workspaceRoot,
+});
+
+const threadId = String((started.thread as { id?: string }).id);
+```
+
+### Send turns on the same thread
+
+```ts
+await client.request("turn/start", {
+  threadId,
+  input: [{ type: "text", text: "First message" }],
+  cwd: ready.workspaceRoot,
+  model: "gpt-5.3-codex",
+  effort: "medium",
+  approvalPolicy: "never",
+  sandboxPolicy: {
+    type: "workspaceWrite",
+    writableRoots: [ready.workspaceRoot],
+    networkAccess: true,
+  },
+  summary: "concise",
+});
+```
+
+To continue the same conversation:
+
+- keep the sandbox alive
+- reuse the same `threadId`
+- send another `turn/start`
+
+If your websocket connection drops, reconnect using the same `websocketUrl` and `authToken`, then continue using the same `threadId`.
+
+### One-call helper
+
+If you want one fresh sandbox and one prompt, use:
+
+```ts
+import { createReadyCodexSandbox, runPrompt } from "@denieler/e2e-codex";
+
+const sandbox = await createReadyCodexSandbox({
+  e2bApiKey: process.env.E2B_API_KEY!,
+  templateId: process.env.E2B_TEMPLATE_ID!,
+  openAiApiKey: process.env.OPENAI_API_KEY!,
+  userId: "user-123",
+});
+
+const result = await runPrompt({
+  sandbox,
+  prompt: "Summarize this workspace in one sentence.",
+});
+
+console.log(result.reply);
+```
+
+## Template Development
+
+Use this section if you are maintaining the template itself.
+
+### Install
+
+```bash
+npm install
+```
+
+### Build the template
+
+```bash
+doppler run -- npm run build:template
+```
+
+The build prints:
+
+- template name
+- template id
+- build id
+
+Use the printed template id as `E2B_TEMPLATE_ID` for runtime use.
+
+### What the build does
+
+The template build:
+
+- starts from E2B `base`
+- installs a small set of system packages
+- downloads the Codex Linux binary from OpenAI GitHub releases
+- installs it to `/usr/local/bin/codex`
+
+Codex is installed at template build time, not at sandbox startup.
+
+### Useful commands
+
+```bash
+npm install
+npm run typecheck
+doppler run -- npm run build:template
+E2B_TEMPLATE_ID=<template-id> doppler run -- npm run example:prompt -- "Hello"
+```
+
+## Runtime Design
+
+At sandbox startup, the runtime:
+
+- writes a websocket capability token into the sandbox
+- starts `codex app-server` as an E2B background process
+- waits for it to stay alive
+- opens the websocket connection
+
+`codex app-server` is started at runtime, not stored as a pre-running process in the template.
+
+## Notes
+
+- The template is shared. Sandboxes are ephemeral.
+- Secrets are injected when the sandbox is created.
+- The websocket token file is written to `/tmp/e2b-codex-ws-token`.
+- The example uses `approvalPolicy: "never"` and `workspaceWrite`.
+
+## Publish
+
+Build the package:
+
+```bash
+npm run build
+```
+
+Pack it locally:
+
+```bash
+npm pack
+```
+
+Publish when ready:
+
+```bash
+npm publish
+```

package/assets/e2b-codex-banner.svg

@@ -0,0 +1,100 @@
+<svg width="1200" height="420" viewBox="0 0 1200 420" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="bg" x1="120" y1="48" x2="1080" y2="372" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#0B1220"/>
+      <stop offset="1" stop-color="#111C2F"/>
+    </linearGradient>
+    <linearGradient id="panel" x1="226" y1="92" x2="978" y2="330" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#121B2D"/>
+      <stop offset="1" stop-color="#18253D"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="268" y1="124" x2="934" y2="296" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#38BDF8"/>
+      <stop offset="1" stop-color="#22C55E"/>
+    </linearGradient>
+    <linearGradient id="cubeFaceA" x1="0" y1="0" x2="1" y2="1">
+      <stop stop-color="#3DD5F3"/>
+      <stop offset="1" stop-color="#23B3D6"/>
+    </linearGradient>
+    <linearGradient id="cubeFaceB" x1="0" y1="0" x2="1" y2="1">
+      <stop stop-color="#1F8FB5"/>
+      <stop offset="1" stop-color="#176A8C"/>
+    </linearGradient>
+    <linearGradient id="cubeFaceC" x1="0" y1="0" x2="1" y2="1">
+      <stop stop-color="#6EE7B7"/>
+      <stop offset="1" stop-color="#22C55E"/>
+    </linearGradient>
+    <filter id="shadow" x="186" y="82" width="830" height="266" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+      <feFlood flood-opacity="0" result="BackgroundImageFix"/>
+      <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+      <feOffset dy="10"/>
+      <feGaussianBlur stdDeviation="20"/>
+      <feComposite in2="hardAlpha" operator="out"/>
+      <feColorMatrix type="matrix" values="0 0 0 0 0.0156863 0 0 0 0 0.0470588 0 0 0 0 0.121569 0 0 0 0.38 0"/>
+      <feBlend mode="normal" in2="BackgroundImageFix" result="effect1_dropShadow_0_1"/>
+      <feBlend mode="normal" in="SourceGraphic" in2="effect1_dropShadow_0_1" result="shape"/>
+    </filter>
+  </defs>
+
+  <rect width="1200" height="420" rx="28" fill="url(#bg)"/>
+
+  <g opacity="0.2">
+    <path d="M110 84H1090" stroke="url(#accent)" stroke-width="1"/>
+    <path d="M110 336H1090" stroke="url(#accent)" stroke-width="1"/>
+    <path d="M190 48V372" stroke="#2B3A56" stroke-width="1"/>
+    <path d="M1010 48V372" stroke="#2B3A56" stroke-width="1"/>
+  </g>
+
+  <g opacity="0.22" fill="#7DD3FC">
+    <circle cx="126" cy="96" r="2"/>
+    <circle cx="156" cy="126" r="2"/>
+    <circle cx="108" cy="154" r="2"/>
+    <circle cx="1074" cy="112" r="2"/>
+    <circle cx="1048" cy="146" r="2"/>
+    <circle cx="1090" cy="174" r="2"/>
+    <circle cx="101" cy="286" r="2"/>
+    <circle cx="142" cy="316" r="2"/>
+    <circle cx="1087" cy="288" r="2"/>
+    <circle cx="1058" cy="324" r="2"/>
+  </g>
+
+  <g filter="url(#shadow)">
+    <rect x="226" y="92" width="748" height="226" rx="24" fill="url(#panel)" stroke="#2A3C5F"/>
+  </g>
+
+  <rect x="256" y="122" width="204" height="166" rx="20" fill="#0E1727" stroke="#243551"/>
+  <rect x="276" y="142" width="164" height="18" rx="9" fill="#172338"/>
+  <circle cx="295" cy="151" r="4" fill="#38BDF8"/>
+  <circle cx="311" cy="151" r="4" fill="#22C55E"/>
+  <circle cx="327" cy="151" r="4" fill="#F59E0B"/>
+
+  <path d="M302 198L328 224L302 250" stroke="#7DD3FC" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
+  <rect x="346" y="244" width="48" height="10" rx="5" fill="#6EE7B7"/>
+  <rect x="346" y="208" width="62" height="10" rx="5" fill="#2A3C5F"/>
+  <rect x="346" y="190" width="42" height="10" rx="5" fill="#2A3C5F"/>
+
+  <g>
+    <path d="M584 138L632 164V217L584 243L536 217V164L584 138Z" fill="url(#cubeFaceA)"/>
+    <path d="M584 138L632 164L584 190L536 164L584 138Z" fill="#8BE9FC"/>
+    <path d="M632 164V217L584 243V190L632 164Z" fill="url(#cubeFaceB)"/>
+    <path d="M536 164V217L584 243V190L536 164Z" fill="url(#cubeFaceC)"/>
+    <path d="M584 156L614 173V205L584 222L554 205V173L584 156Z" stroke="#E0FBFF" stroke-width="4"/>
+  </g>
+
+  <path d="M664 192H730" stroke="url(#accent)" stroke-width="6" stroke-linecap="round"/>
+  <circle cx="748" cy="192" r="10" fill="#38BDF8"/>
+  <path d="M758 192H818" stroke="url(#accent)" stroke-width="6" stroke-linecap="round"/>
+  <circle cx="836" cy="192" r="10" fill="#22C55E"/>
+  <path d="M846 192H904" stroke="url(#accent)" stroke-width="6" stroke-linecap="round"/>
+
+  <g>
+    <rect x="858" y="142" width="78" height="100" rx="16" fill="#0E1727" stroke="#24405A"/>
+    <rect x="874" y="160" width="46" height="8" rx="4" fill="#38BDF8"/>
+    <rect x="874" y="178" width="34" height="8" rx="4" fill="#2A3C5F"/>
+    <rect x="874" y="212" width="28" height="8" rx="4" fill="#6EE7B7"/>
+    <path d="M884 201L897 188L910 201" stroke="#E0FBFF" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+  </g>
+
+  <text x="502" y="287" fill="#F7FAFC" font-family="ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="56" font-weight="700" letter-spacing="-0.03em">e2b-codex</text>
+  <text x="504" y="325" fill="#9FB4D0" font-family="ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="22" font-weight="500">Build once. Spin sandboxes fast. Talk to Codex over websocket.</text>
+</svg>

package/dist/codex-app-server.d.ts

@@ -0,0 +1,32 @@
+type JsonRpcError = {
+    code: number;
+    message: string;
+};
+type JsonRpcMessage = {
+    id?: number;
+    method?: string;
+    params?: Record<string, unknown>;
+    result?: Record<string, unknown>;
+    error?: JsonRpcError;
+};
+type NotificationHandler = (message: Required<Pick<JsonRpcMessage, "method">> & JsonRpcMessage) => void;
+export declare class CodexAppServerClient {
+    private readonly socket;
+    private readonly pending;
+    private readonly notificationHandlers;
+    private nextId;
+    private constructor();
+    static connect(url: string, authToken?: string): Promise<CodexAppServerClient>;
+    onNotification(handler: NotificationHandler): () => boolean;
+    initialize(clientInfo?: {
+        name?: string;
+        title?: string;
+        version?: string;
+    }): Promise<void>;
+    request(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    notify(method: string, params: Record<string, unknown>): void;
+    close(): void;
+    private handleIncomingMessage;
+    private rejectAllPending;
+}
+export {};

package/dist/codex-app-server.js

@@ -0,0 +1,93 @@
+export class CodexAppServerClient {
+    socket;
+    pending = new Map();
+    notificationHandlers = new Set();
+    nextId = 0;
+    constructor(socket) {
+        this.socket = socket;
+        this.socket.addEventListener("message", (event) => {
+            this.handleIncomingMessage(typeof event.data === "string" ? event.data : "");
+        });
+        this.socket.addEventListener("error", (event) => {
+            const error = event instanceof ErrorEvent ? event.error : new Error("Codex websocket error");
+            this.rejectAllPending(error);
+        });
+        this.socket.addEventListener("close", () => {
+            this.rejectAllPending(new Error("Codex websocket connection closed."));
+        });
+    }
+    static async connect(url, authToken) {
+        const WebSocketConstructor = WebSocket;
+        const socket = new WebSocketConstructor(url, {
+            headers: authToken
+                ? {
+                    Authorization: `Bearer ${authToken}`,
+                }
+                : undefined,
+        });
+        await new Promise((resolve, reject) => {
+            socket.addEventListener("open", () => resolve(), { once: true });
+            socket.addEventListener("error", () => reject(new Error("Unable to open Codex websocket.")), { once: true });
+        });
+        return new CodexAppServerClient(socket);
+    }
+    onNotification(handler) {
+        this.notificationHandlers.add(handler);
+        return () => this.notificationHandlers.delete(handler);
+    }
+    async initialize(clientInfo) {
+        await this.request("initialize", {
+            clientInfo: {
+                name: clientInfo?.name ?? "e2b_codex",
+                title: clientInfo?.title ?? "E2B Codex",
+                version: clientInfo?.version ?? "0.1.0",
+            },
+        });
+        this.notify("initialized", {});
+    }
+    async request(method, params) {
+        const id = this.nextId++;
+        const payload = { id, method, params };
+        const resultPromise = new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+        });
+        this.socket.send(JSON.stringify(payload));
+        return resultPromise;
+    }
+    notify(method, params) {
+        this.socket.send(JSON.stringify({ method, params }));
+    }
+    close() {
+        this.socket.close();
+    }
+    handleIncomingMessage(raw) {
+        if (!raw) {
+            return;
+        }
+        const message = JSON.parse(raw);
+        if (typeof message.id === "number") {
+            const pending = this.pending.get(message.id);
+            if (!pending) {
+                return;
+            }
+            this.pending.delete(message.id);
+            if (message.error) {
+                pending.reject(new Error(message.error.message));
+                return;
+            }
+            pending.resolve(message.result ?? {});
+            return;
+        }
+        if (message.method) {
+            for (const handler of this.notificationHandlers) {
+                handler(message);
+            }
+        }
+    }
+    rejectAllPending(error) {
+        for (const pending of this.pending.values()) {
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+}

package/dist/env.d.ts

@@ -0,0 +1,2 @@
+export declare function loadLocalEnvFile(): void;
+export declare function requireEnvVar(name: string): string;

package/dist/env.js

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import path from "node:path";
+function parseEnvFile(content) {
+    const entries = new Map();
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#")) {
+            continue;
+        }
+        const separatorIndex = line.indexOf("=");
+        if (separatorIndex <= 0) {
+            continue;
+        }
+        const key = line.slice(0, separatorIndex).trim();
+        let value = line.slice(separatorIndex + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        entries.set(key, value);
+    }
+    return entries;
+}
+export function loadLocalEnvFile() {
+    const envPath = path.join(process.cwd(), ".env.local");
+    if (!fs.existsSync(envPath)) {
+        return;
+    }
+    const parsed = parseEnvFile(fs.readFileSync(envPath, "utf8"));
+    for (const [key, value] of parsed.entries()) {
+        if (!process.env[key]) {
+            process.env[key] = value;
+        }
+    }
+}
+export function requireEnvVar(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { CodexAppServerClient } from "./codex-app-server.js";
+export { loadLocalEnvFile, requireEnvVar } from "./env.js";
+export { template } from "./template.js";
+export { connectCodexClient, createReadyCodexSandbox, runPrompt, } from "./sandbox.js";
+export type { CreateCodexSandboxOptions, ReadyCodexSandbox } from "./sandbox.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { CodexAppServerClient } from "./codex-app-server.js";
+export { loadLocalEnvFile, requireEnvVar } from "./env.js";
+export { template } from "./template.js";
+export { connectCodexClient, createReadyCodexSandbox, runPrompt, } from "./sandbox.js";

package/dist/sandbox.d.ts

@@ -0,0 +1,34 @@
+import { Sandbox } from "e2b";
+import { CodexAppServerClient } from "./codex-app-server.js";
+export type CreateCodexSandboxOptions = {
+    e2bApiKey: string;
+    templateId: string;
+    openAiApiKey: string;
+    userId: string;
+    timeoutMs?: number;
+    allowInternetAccess?: boolean;
+    port?: number;
+    workspaceRoot?: string;
+    metadata?: Record<string, string>;
+};
+export type ReadyCodexSandbox = {
+    sandbox: Sandbox;
+    sandboxId: string;
+    websocketUrl: string;
+    authToken: string;
+    port: number;
+    workspaceRoot: string;
+};
+export declare function createReadyCodexSandbox(options: CreateCodexSandboxOptions): Promise<ReadyCodexSandbox>;
+export declare function connectCodexClient(readySandbox: Pick<ReadyCodexSandbox, "websocketUrl" | "authToken">): Promise<CodexAppServerClient>;
+export declare function runPrompt(options: {
+    sandbox: ReadyCodexSandbox;
+    prompt: string;
+    cwd?: string;
+    model?: string;
+    effort?: "low" | "medium" | "high" | "xhigh";
+    summary?: "auto" | "concise" | "detailed";
+}): Promise<{
+    threadId: string;
+    reply: string;
+}>;

package/dist/sandbox.js

@@ -0,0 +1,178 @@
+import { createHash } from "node:crypto";
+import { Sandbox } from "e2b";
+import { CodexAppServerClient } from "./codex-app-server.js";
+function createAppServerToken(userId) {
+    return createHash("sha256")
+        .update("e2b-codex")
+        .update(":")
+        .update(userId)
+        .digest("hex");
+}
+function getTokenFilePath() {
+    return "/tmp/e2b-codex-ws-token";
+}
+async function ensureAppServerRunning(sandbox, options) {
+    const port = options.port ?? 4571;
+    const workspaceRoot = options.workspaceRoot ?? "/workspace";
+    const tokenFile = getTokenFilePath();
+    const token = createAppServerToken(options.userId);
+    const processPattern = `[c]odex app-server --listen ws://0.0.0.0:${port}`;
+    await sandbox.files.write(tokenFile, token);
+    await sandbox.commands.run(`mkdir -p ${workspaceRoot}`, {
+        timeoutMs: 10_000,
+    });
+    const existing = await sandbox.commands.run(`bash -lc 'ps -ef | grep "${processPattern}" || true'`, {
+        timeoutMs: 10_000,
+    });
+    if (existing.stdout.trim()) {
+        return;
+    }
+    await sandbox.commands.run(`codex app-server --listen ws://0.0.0.0:${port} --ws-auth capability-token --ws-token-file ${tokenFile}`, {
+        background: true,
+        envs: {
+            OPENAI_API_KEY: options.openAiApiKey,
+        },
+        timeoutMs: 15_000,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 3_000));
+    const started = await sandbox.commands.run(`bash -lc 'ps -ef | grep "${processPattern}" || true'`, {
+        timeoutMs: 10_000,
+    });
+    if (!started.stdout.trim()) {
+        throw new Error("codex app-server did not remain running after startup.");
+    }
+}
+export async function createReadyCodexSandbox(options) {
+    const port = options.port ?? 4571;
+    const workspaceRoot = options.workspaceRoot ?? "/workspace";
+    const sandbox = await Sandbox.create(options.templateId, {
+        apiKey: options.e2bApiKey,
+        timeoutMs: options.timeoutMs ?? 300_000,
+        allowInternetAccess: options.allowInternetAccess ?? true,
+        envs: {
+            OPENAI_API_KEY: options.openAiApiKey,
+        },
+        metadata: {
+            product: "e2b-codex",
+            userId: options.userId,
+            ...(options.metadata ?? {}),
+        },
+    });
+    await ensureAppServerRunning(sandbox, {
+        openAiApiKey: options.openAiApiKey,
+        port,
+        workspaceRoot,
+        userId: options.userId,
+    });
+    return {
+        sandbox,
+        sandboxId: sandbox.sandboxId,
+        websocketUrl: `wss://${sandbox.getHost(port)}`,
+        authToken: createAppServerToken(options.userId),
+        port,
+        workspaceRoot,
+    };
+}
+export async function connectCodexClient(readySandbox) {
+    let lastError = null;
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+        try {
+            const client = await CodexAppServerClient.connect(readySandbox.websocketUrl, readySandbox.authToken);
+            await client.initialize();
+            return client;
+        }
+        catch (error) {
+            lastError = error;
+            await new Promise((resolve) => setTimeout(resolve, 500));
+        }
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error("Unable to open Codex websocket.");
+}
+export async function runPrompt(options) {
+    const client = await connectCodexClient(options.sandbox);
+    const cwd = options.cwd ?? options.sandbox.workspaceRoot;
+    const model = options.model ?? "gpt-5.3-codex";
+    const effort = options.effort ?? "medium";
+    const summary = options.summary ?? "concise";
+    try {
+        const started = await client.request("thread/start", {
+            model,
+            cwd,
+        });
+        const threadId = String(started.thread?.id ?? "");
+        if (!threadId) {
+            throw new Error("Codex did not return a thread id.");
+        }
+        const replyParts = [];
+        await new Promise((resolve, reject) => {
+            const unsubscribe = client.onNotification((message) => {
+                const params = (message.params ?? {});
+                if (message.method === "item/agentMessage/delta" && typeof params.delta === "string") {
+                    replyParts.push(params.delta);
+                    return;
+                }
+                if (message.method === "item/completed") {
+                    const item = (params.item ?? {});
+                    const content = Array.isArray(item.content) ? item.content : [];
+                    const completedText = content
+                        .map((part) => typeof part === "object" && part && typeof part.text === "string"
+                        ? String(part.text)
+                        : "")
+                        .join("")
+                        .trim();
+                    if (item.type === "agentMessage" && completedText && replyParts.length === 0) {
+                        replyParts.push(completedText);
+                    }
+                    return;
+                }
+                if (message.method === "error") {
+                    const error = (params.error ?? {});
+                    const errorMessage = String(error.message ?? "Codex turn failed.");
+                    const willRetry = Boolean(params.willRetry);
+                    if (willRetry) {
+                        return;
+                    }
+                    unsubscribe();
+                    reject(new Error(errorMessage));
+                    return;
+                }
+                if (message.method === "turn/completed") {
+                    unsubscribe();
+                    const turn = (params.turn ?? {});
+                    if (String(turn.status ?? "") === "failed") {
+                        reject(new Error(String(turn.error?.message ??
+                            "Codex turn failed.")));
+                        return;
+                    }
+                    resolve();
+                }
+            });
+            client.request("turn/start", {
+                threadId,
+                input: [{ type: "text", text: options.prompt }],
+                cwd,
+                model,
+                effort,
+                approvalPolicy: "never",
+                sandboxPolicy: {
+                    type: "workspaceWrite",
+                    writableRoots: [cwd],
+                    networkAccess: true,
+                },
+                summary,
+            }).catch((error) => {
+                unsubscribe();
+                reject(error);
+            });
+        });
+        return {
+            threadId,
+            reply: replyParts.join("").trim(),
+        };
+    }
+    finally {
+        client.close();
+    }
+}

package/dist/template.d.ts

@@ -0,0 +1 @@
+export declare const template: import("e2b").TemplateBuilder;

package/dist/template.js

@@ -0,0 +1,45 @@
+import { Template } from "e2b";
+const codexInstallScript = `
+set -eux
+ARCH="$(uname -m)"
+case "$ARCH" in
+  x86_64) TARGET="x86_64-unknown-linux-musl" ;;
+  aarch64|arm64) TARGET="aarch64-unknown-linux-musl" ;;
+  *)
+    echo "Unsupported architecture: $ARCH" >&2
+    exit 1
+    ;;
+esac
+
+VERSION="\${CODEX_VERSION:-latest}"
+ASSET="codex-$TARGET.tar.gz"
+BASE_URL="https://github.com/openai/codex/releases"
+
+if [ "$VERSION" = "latest" ]; then
+  DOWNLOAD_URL="$BASE_URL/latest/download/$ASSET"
+else
+  DOWNLOAD_URL="$BASE_URL/download/$VERSION/$ASSET"
+fi
+
+curl -fsSL "$DOWNLOAD_URL" -o /tmp/codex.tar.gz
+mkdir -p /tmp/codex-extract
+tar -xzf /tmp/codex.tar.gz -C /tmp/codex-extract
+
+BIN_PATH="/tmp/codex-extract/codex-$TARGET"
+if [ ! -f "$BIN_PATH" ]; then
+  echo "Codex binary not found after extraction." >&2
+  exit 1
+fi
+
+install -m 0755 "$BIN_PATH" /usr/local/bin/codex
+codex --version
+`;
+export const template = Template()
+    .fromTemplate("base")
+    .setUser("root")
+    .aptInstall(["ca-certificates", "curl", "git", "tar", "unzip"], {
+    noInstallRecommends: true,
+})
+    .makeDir("/workspace", { mode: 0o755 })
+    .runCmd(codexInstallScript)
+    .runCmd("sh -lc 'command -v codex && codex --version'");

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@denieler/e2b-codex",
+  "version": "0.1.0",
+  "description": "Build and use E2B sandboxes with Codex preinstalled and codex app-server ready over websocket.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "assets"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:template": "tsx scripts/build-template.ts",
+    "clean": "rm -rf dist",
+    "example:prompt": "tsx examples/run-prompt.ts",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "e2b": "^2.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.8.2"
+  }
+}