Codex

Image updates

Ready-made agent images are updated every morning to include the current CLI version. To use a fixed image version, pin a template version.

Codex is an OpenAI agent that works with files, runs commands, and uses tools to complete tasks. AgentBox runs it in a separate sandbox: your application supplies instructions and data, receives events, and retrieves the result. The ready-made codex template already includes the agent CLI.

Connect

Install the AgentBox SDK and set AGENTBOX_API_KEY in your application's environment. Codex needs a separate OPENAI_API_KEY with access to the example model, gpt-5.6-luna. When creating the sandbox, the example maps this key to CODEX_API_KEY, which codex exec reads. You can select another model available to your OpenAI project.

The examples use the AgentBox proxy at socks5h://sandbox-proxy.agentbox.ru:65180 through ALL_PROXY inside the sandbox. This is a process-wide setting, rather than a proxy restricted to model requests. Do not put the OpenAI key in a template or input file.

Prepare a sales report

This example uploads three orders and asks the agent to write report.md. Paid revenue is RUB 120,000 online plus RUB 80,000 in retail. RUB 45,000 in cancelled orders must be reported separately. Replace these rows with a CRM export while keeping the column names and calculation rules.

mjs

import { Sandbox } from "@abox-dev/sdk";

const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) throw new Error("OPENAI_API_KEY is required");
const proxy =
  process.env.SANDBOX_PROXY_URL ?? "socks5h://sandbox-proxy.agentbox.ru:65180";

const sandbox = await Sandbox.create("codex", {
  timeoutMs: 600_000,
  envs: {
    CODEX_API_KEY: apiKey,
    ALL_PROXY: proxy,
    NO_PROXY: "localhost,127.0.0.1",
  },
});
try {
  await sandbox.files.makeDir("/home/user/work");
  await sandbox.files.write(
    "/home/user/work/sales.csv",
    "channel,status,amount_rub\nOnline,paid,120000\nRetail,paid,80000\nOnline,cancelled,45000\n",
  );
  await sandbox.commands.run(
    "codex exec --ephemeral --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --model gpt-5.6-luna 'Read sales.csv. Calculate paid revenue by channel and total; exclude cancelled orders. Write report.md: a short sales briefing with a table, the cancelled amount separately, and one next action.'",
    {
      cwd: "/home/user/work",
      timeoutMs: 300_000,
      onStderr: (chunk) => process.stderr.write(chunk),
    },
  );
  console.log(
    "report.md\n" + (await sandbox.files.read("/home/user/work/report.md")),
  );
} finally {
  await sandbox.kill();
}

import os
import sys
from agentbox import Sandbox

api_key = os.environ["OPENAI_API_KEY"]
proxy = os.getenv("SANDBOX_PROXY_URL", "socks5h://sandbox-proxy.agentbox.ru:65180")
sandbox = Sandbox.create(
    "codex",
    timeout=600,
    envs={
        "CODEX_API_KEY": api_key,
        "ALL_PROXY": proxy,
        "NO_PROXY": "localhost,127.0.0.1",
    },
)
try:
    sandbox.files.make_dir("/home/user/work")
    sandbox.files.write(
        "/home/user/work/sales.csv",
        "channel,status,amount_rub\nOnline,paid,120000\nRetail,paid,80000\nOnline,cancelled,45000\n",
    )
    sandbox.commands.run(
        "codex exec --ephemeral --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --model gpt-5.6-luna 'Read sales.csv. Calculate paid revenue by channel and total; exclude cancelled orders. Write report.md: a short sales briefing with a table, the cancelled amount separately, and one next action.'",
        cwd="/home/user/work",
        timeout=300,
        on_stderr=lambda chunk: print(chunk, end="", file=sys.stderr),
    )
    print("report.md\n" + sandbox.files.read("/home/user/work/report.md"))
finally:
    sandbox.kill()

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/abox-dev/sdk/packages/go-sdk"
)

func run() (err error) {
	apiKey := os.Getenv("OPENAI_API_KEY")
	proxy := os.Getenv("SANDBOX_PROXY_URL")
	if proxy == "" {
		proxy = "socks5h://sandbox-proxy.agentbox.ru:65180"
	}
	if apiKey == "" {
		return fmt.Errorf("OPENAI_API_KEY is required")
	}
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
	defer cancel()
	client, err := agentbox.NewClient()
	if err != nil {
		return err
	}
	sandbox, err := client.Sandboxes.Create(ctx, &agentbox.CreateSandboxOptions{
		Template: "codex", Timeout: 10 * time.Minute,
		Env: map[string]string{"CODEX_API_KEY": apiKey,
			"ALL_PROXY": proxy,
			"NO_PROXY":  "localhost,127.0.0.1"},
	})
	if err != nil {
		return err
	}
	defer func() {
		cleanupCtx, stop := context.WithTimeout(context.Background(), 30*time.Second)
		defer stop()
		_, cleanupErr := sandbox.Kill(cleanupCtx)
		err = errors.Join(err, cleanupErr)
	}()
	if _, err := sandbox.Files.MakeDir(ctx, "/home/user/work"); err != nil {
		return err
	}
	if _, err := sandbox.Files.WriteText(ctx, "/home/user/work/sales.csv", "channel,status,amount_rub\nOnline,paid,120000\nRetail,paid,80000\nOnline,cancelled,45000\n", nil); err != nil {
		return err
	}
	if _, err := sandbox.Commands.Run(ctx, "sh", &agentbox.CommandOptions{
		Args: []string{"-lc", "codex exec --ephemeral --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --model gpt-5.6-luna 'Read sales.csv. Calculate paid revenue by channel and total; exclude cancelled orders. Write report.md: a short sales briefing with a table, the cancelled amount separately, and one next action.'"}, Cwd: "/home/user/work",
		OnStderr: func(chunk []byte) { fmt.Fprint(os.Stderr, string(chunk)) },
	}); err != nil {
		return err
	}
	report, err := sandbox.Files.ReadText(ctx, "/home/user/work/report.md", "")
	if err != nil {
		return err
	}
	fmt.Println("report.md\n" + report)
	return nil
}

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

codex exec handles a task without a terminal interface. --skip-git-repo-check allows processing exports outside a Git repository. --ephemeral suits a one-off report because it does not persist conversation history. Read the output through the SDK before deleting the sandbox.

The example allows commands without approval (--dangerously-bypass-approvals-and-sandbox). The AgentBox sandbox provides the isolation boundary. The agent can change sandbox files and access the network. Supply only the data and credentials needed for this task.

Return structured data to your application

Use JSON Schema when the result feeds a report card or another process step. This example returns currency, paid revenue, cancelled amount, and a suggested action. --output-last-message saves the final answer separately from CLI progress output.

mjs

import { Sandbox } from "@abox-dev/sdk";

const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) throw new Error("OPENAI_API_KEY is required");
const proxy =
  process.env.SANDBOX_PROXY_URL ?? "socks5h://sandbox-proxy.agentbox.ru:65180";

const sandbox = await Sandbox.create("codex", {
  timeoutMs: 600_000,
  envs: {
    CODEX_API_KEY: apiKey,
    ALL_PROXY: proxy,
    NO_PROXY: "localhost,127.0.0.1",
  },
});
try {
  await sandbox.files.makeDir("/home/user/work");
  await sandbox.files.write(
    "/home/user/work/sales.csv",
    "channel,status,amount_rub\nOnline,paid,120000\nRetail,paid,80000\nOnline,cancelled,45000\n",
  );
  await sandbox.files.write(
    "/home/user/work/schema.json",
    '{"type": "object", "properties": {"currency": {"type": "string", "enum": ["RUB"]}, "paid_revenue": {"type": "integer"}, "cancelled_amount": {"type": "integer"}, "recommendation": {"type": "string"}}, "required": ["currency", "paid_revenue", "cancelled_amount", "recommendation"], "additionalProperties": false}',
  );
  await sandbox.commands.run(
    "codex exec --ephemeral --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --model gpt-5.6-luna --output-schema schema.json --output-last-message summary.json 'Read sales.csv. Calculate paid revenue and cancelled amount separately. Return a sales summary matching the schema, with one concise recommendation.'",
    { cwd: "/home/user/work", timeoutMs: 300_000 },
  );
  const summary = JSON.parse(
    await sandbox.files.read("/home/user/work/summary.json"),
  );
  console.log(JSON.stringify(summary));
} finally {
  await sandbox.kill();
}

import json
import os
from agentbox import Sandbox

api_key = os.environ["OPENAI_API_KEY"]
proxy = os.getenv("SANDBOX_PROXY_URL", "socks5h://sandbox-proxy.agentbox.ru:65180")
sandbox = Sandbox.create(
    "codex",
    timeout=600,
    envs={
        "CODEX_API_KEY": api_key,
        "ALL_PROXY": proxy,
        "NO_PROXY": "localhost,127.0.0.1",
    },
)
try:
    sandbox.files.make_dir("/home/user/work")
    sandbox.files.write(
        "/home/user/work/sales.csv",
        "channel,status,amount_rub\nOnline,paid,120000\nRetail,paid,80000\nOnline,cancelled,45000\n",
    )
    sandbox.files.write(
        "/home/user/work/schema.json",
        '{"type": "object", "properties": {"currency": {"type": "string", "enum": ["RUB"]}, "paid_revenue": {"type": "integer"}, "cancelled_amount": {"type": "integer"}, "recommendation": {"type": "string"}}, "required": ["currency", "paid_revenue", "cancelled_amount", "recommendation"], "additionalProperties": false}',
    )
    sandbox.commands.run(
        "codex exec --ephemeral --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --model gpt-5.6-luna --output-schema schema.json --output-last-message summary.json 'Read sales.csv. Calculate paid revenue and cancelled amount separately. Return a sales summary matching the schema, with one concise recommendation.'",
        cwd="/home/user/work",
        timeout=300,
    )
    summary = json.loads(sandbox.files.read("/home/user/work/summary.json"))
    print(json.dumps(summary))
finally:
    sandbox.kill()

package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/abox-dev/sdk/packages/go-sdk"
)

func run() (err error) {
	apiKey := os.Getenv("OPENAI_API_KEY")
	proxy := os.Getenv("SANDBOX_PROXY_URL")
	if proxy == "" {
		proxy = "socks5h://sandbox-proxy.agentbox.ru:65180"
	}
	if apiKey == "" {
		return fmt.Errorf("OPENAI_API_KEY is required")
	}
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
	defer cancel()
	client, err := agentbox.NewClient()
	if err != nil {
		return err
	}
	sandbox, err := client.Sandboxes.Create(ctx, &agentbox.CreateSandboxOptions{
		Template: "codex", Timeout: 10 * time.Minute,
		Env: map[string]string{"CODEX_API_KEY": apiKey,
			"ALL_PROXY": proxy,
			"NO_PROXY":  "localhost,127.0.0.1"},
	})
	if err != nil {
		return err
	}
	defer func() {
		cleanupCtx, stop := context.WithTimeout(context.Background(), 30*time.Second)
		defer stop()
		_, cleanupErr := sandbox.Kill(cleanupCtx)
		err = errors.Join(err, cleanupErr)
	}()
	if _, err := sandbox.Files.MakeDir(ctx, "/home/user/work"); err != nil {
		return err
	}
	if _, err := sandbox.Files.WriteText(ctx, "/home/user/work/sales.csv", "channel,status,amount_rub\nOnline,paid,120000\nRetail,paid,80000\nOnline,cancelled,45000\n", nil); err != nil {
		return err
	}
	if _, err := sandbox.Files.WriteText(ctx, "/home/user/work/schema.json", "{\"type\": \"object\", \"properties\": {\"currency\": {\"type\": \"string\", \"enum\": [\"RUB\"]}, \"paid_revenue\": {\"type\": \"integer\"}, \"cancelled_amount\": {\"type\": \"integer\"}, \"recommendation\": {\"type\": \"string\"}}, \"required\": [\"currency\", \"paid_revenue\", \"cancelled_amount\", \"recommendation\"], \"additionalProperties\": false}", nil); err != nil {
		return err
	}
	if _, err := sandbox.Commands.Run(ctx, "sh", &agentbox.CommandOptions{Args: []string{"-lc", "codex exec --ephemeral --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --model gpt-5.6-luna --output-schema schema.json --output-last-message summary.json 'Read sales.csv. Calculate paid revenue and cancelled amount separately. Return a sales summary matching the schema, with one concise recommendation.'"}, Cwd: "/home/user/work"}); err != nil {
		return err
	}
	data, err := sandbox.Files.ReadBytes(ctx, "/home/user/work/summary.json", "")
	if err != nil {
		return err
	}
	var summary struct {
		Currency        string `json:"currency"`
		PaidRevenue     int    `json:"paid_revenue"`
		CancelledAmount int    `json:"cancelled_amount"`
		Recommendation  string `json:"recommendation"`
	}
	if err := json.Unmarshal(data, &summary); err != nil {
		return err
	}
	fmt.Printf("%s: paid_revenue=%d, cancelled_amount=%d\n%s\n", summary.Currency, summary.PaidRevenue, summary.CancelledAmount, summary.Recommendation)
	return nil
}

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

These inputs should produce paid_revenue: 200000 and cancelled_amount: 45000. The JSON schema defines the result's fields and data types.

Stream events and ask a follow-up

Show progress while the report is being prepared. --json emits JSONL events. The handler below buffers unfinished lines between callbacks: a network chunk may contain part of an event or several events at once.

Event	Application action
`thread.started`	Save `thread_id` for follow-up tasks
`item.started` with `command_execution`	Indicate that a command is running
`item.completed` with `agent_message`	Show the completed message
`turn.completed`	Mark the task complete and store token usage
`turn.failed` or `error`	Show the failure. Do not present a partial report as finished

The example prepares a report, then asks for two next actions for the sales manager in the same sandbox and conversation. It uses codex exec resume with the saved ID, without --ephemeral.

mjs

import { Sandbox } from "@abox-dev/sdk";

const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) throw new Error("OPENAI_API_KEY is required");
const proxy =
  process.env.SANDBOX_PROXY_URL ?? "socks5h://sandbox-proxy.agentbox.ru:65180";

const sandbox = await Sandbox.create("codex", {
  timeoutMs: 600_000,
  envs: {
    CODEX_API_KEY: apiKey,
    ALL_PROXY: proxy,
    NO_PROXY: "localhost,127.0.0.1",
  },
});
try {
  await sandbox.files.makeDir("/home/user/work");
  await sandbox.files.write(
    "/home/user/work/sales.csv",
    "channel,status,amount_rub\nOnline,paid,120000\nRetail,paid,80000\nOnline,cancelled,45000\n",
  );
  let pending = "";
  let threadId;
  let failure;
  let completed = false;
  function event(message) {
    if (message.type === "thread.started") threadId = message.thread_id;
    if (
      message.type === "item.completed" &&
      message.item.type === "agent_message"
    ) {
      console.log(message.item.text);
    }
    if (
      message.type === "item.started" &&
      message.item.type === "command_execution"
    ) {
      console.log("Command:", message.item.command);
    }
    if (message.type === "turn.completed") {
      completed = true;
      console.log("Usage:", message.usage);
    }
    if (message.type === "turn.failed" || message.type === "error") {
      failure = new Error(
        message.error?.message ?? message.message ?? "Codex failed",
      );
    }
  }
  function onStdout(chunk) {
    pending += chunk;
    let newline;
    while ((newline = pending.indexOf("\n")) !== -1) {
      const line = pending.slice(0, newline);
      pending = pending.slice(newline + 1);
      if (line.trim()) event(JSON.parse(line));
    }
  }
  async function execute(command) {
    completed = false;
    await sandbox.commands.run(command, {
      cwd: "/home/user/work",
      timeoutMs: 300_000,
      onStdout,
      onStderr: (chunk) => process.stderr.write(chunk),
    });
    if (pending.trim()) event(JSON.parse(pending));
    pending = "";
    if (failure) throw failure;
    if (!completed) throw new Error("Codex ended without turn.completed");
  }
  await execute(
    "codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --model gpt-5.6-luna --json 'Read sales.csv. Write report.md with paid revenue by channel, total, and cancelled amount separately.'",
  );
  if (!threadId) throw new Error("Codex did not return a thread ID");
  await execute(
    "codex exec resume --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --json " +
      "'" +
      threadId.replaceAll("'", "'\"'\"'") +
      "' " +
      "'Add two concrete next actions for the sales manager to report.md. Keep the original figures.'",
  );
  console.log(
    "report.md\n" + (await sandbox.files.read("/home/user/work/report.md")),
  );
} finally {
  await sandbox.kill();
}

import json
import shlex
import os
import sys
from agentbox import Sandbox

api_key = os.environ["OPENAI_API_KEY"]
proxy = os.getenv("SANDBOX_PROXY_URL", "socks5h://sandbox-proxy.agentbox.ru:65180")
sandbox = Sandbox.create(
    "codex",
    timeout=600,
    envs={
        "CODEX_API_KEY": api_key,
        "ALL_PROXY": proxy,
        "NO_PROXY": "localhost,127.0.0.1",
    },
)
try:
    sandbox.files.make_dir("/home/user/work")
    sandbox.files.write(
        "/home/user/work/sales.csv",
        "channel,status,amount_rub\nOnline,paid,120000\nRetail,paid,80000\nOnline,cancelled,45000\n",
    )
    pending = ""
    thread_id = None
    failure = None
    completed = False

    def event(message):
        global thread_id, failure, completed
        kind = message["type"]
        if kind == "thread.started":
            thread_id = message["thread_id"]
        elif kind == "item.completed" and message["item"]["type"] == "agent_message":
            print(message["item"]["text"])
        elif kind == "item.started" and message["item"]["type"] == "command_execution":
            print("Command:", message["item"]["command"])
        elif kind == "turn.completed":
            completed = True
            print("Usage:", message["usage"])
        elif kind in ("turn.failed", "error"):
            failure = RuntimeError(
                message.get("error", {}).get("message")
                or message.get("message", "Codex failed")
            )

    def on_stdout(chunk):
        global pending
        pending += chunk
        while "\n" in pending:
            line, pending = pending.split("\n", 1)
            if line.strip():
                event(json.loads(line))

    def execute(command):
        global pending, completed
        completed = False
        sandbox.commands.run(
            command,
            cwd="/home/user/work",
            timeout=300,
            on_stdout=on_stdout,
            on_stderr=lambda chunk: print(chunk, end="", file=sys.stderr),
        )
        if pending.strip():
            event(json.loads(pending))
        pending = ""
        if failure:
            raise failure
        if not completed:
            raise RuntimeError("Codex ended without turn.completed")

    execute(
        "codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --model gpt-5.6-luna --json 'Read sales.csv. Write report.md with paid revenue by channel, total, and cancelled amount separately.'"
    )
    if not thread_id:
        raise RuntimeError("Codex did not return a thread ID")
    execute(
        "codex exec resume --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --json "
        + shlex.quote(thread_id)
        + " "
        + shlex.quote(
            "Add two concrete next actions for the sales manager to report.md. Keep the original figures."
        )
    )
    print("report.md\n" + sandbox.files.read("/home/user/work/report.md"))
finally:
    sandbox.kill()

package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"log"
	"os"
	"strings"
	"time"

	"github.com/abox-dev/sdk/packages/go-sdk"
)

func run() (err error) {
	apiKey := os.Getenv("OPENAI_API_KEY")
	proxy := os.Getenv("SANDBOX_PROXY_URL")
	if proxy == "" {
		proxy = "socks5h://sandbox-proxy.agentbox.ru:65180"
	}
	if apiKey == "" {
		return fmt.Errorf("OPENAI_API_KEY is required")
	}
	ctx, cancel := context.WithTimeout(context.Background(), 8*time.Minute)
	defer cancel()
	client, err := agentbox.NewClient()
	if err != nil {
		return err
	}
	sandbox, err := client.Sandboxes.Create(ctx, &agentbox.CreateSandboxOptions{
		Template: "codex", Timeout: 10 * time.Minute,
		Env: map[string]string{"CODEX_API_KEY": apiKey,
			"ALL_PROXY": proxy,
			"NO_PROXY":  "localhost,127.0.0.1"},
	})
	if err != nil {
		return err
	}
	defer func() {
		cleanupCtx, stop := context.WithTimeout(context.Background(), 30*time.Second)
		defer stop()
		_, cleanupErr := sandbox.Kill(cleanupCtx)
		err = errors.Join(err, cleanupErr)
	}()
	if _, err := sandbox.Files.MakeDir(ctx, "/home/user/work"); err != nil {
		return err
	}
	if _, err := sandbox.Files.WriteText(ctx, "/home/user/work/sales.csv", "channel,status,amount_rub\nOnline,paid,120000\nRetail,paid,80000\nOnline,cancelled,45000\n", nil); err != nil {
		return err
	}
	var pending, threadID string
	var streamErr error
	completed := false
	event := func(line string) {
		if strings.TrimSpace(line) == "" || streamErr != nil {
			return
		}
		var message struct {
			Type     string `json:"type"`
			ThreadID string `json:"thread_id"`
			Item     struct {
				Type    string `json:"type"`
				Text    string `json:"text"`
				Command string `json:"command"`
			} `json:"item"`
			Usage json.RawMessage `json:"usage"`
			Error struct {
				Message string `json:"message"`
			} `json:"error"`
			Message string `json:"message"`
		}
		if err := json.Unmarshal([]byte(line), &message); err != nil {
			streamErr = err
			return
		}
		switch message.Type {
		case "thread.started":
			threadID = message.ThreadID
		case "item.completed":
			if message.Item.Type == "agent_message" {
				fmt.Println(message.Item.Text)
			}
		case "item.started":
			if message.Item.Type == "command_execution" {
				fmt.Println("Command:", message.Item.Command)
			}
		case "turn.completed":
			completed = true
			fmt.Println("Usage:", string(message.Usage))
		case "turn.failed", "error":
			streamErr = fmt.Errorf("Codex failed: %s %s", message.Error.Message, message.Message)
		}
	}
	execute := func(args []string) error {
		completed = false
		_, err := sandbox.Commands.Run(ctx, "codex", &agentbox.CommandOptions{
			Args: args, Cwd: "/home/user/work",
			OnStdout: func(chunk []byte) {
				pending += string(chunk)
				for {
					line, rest, found := strings.Cut(pending, "\n")
					if !found {
						break
					}
					pending = rest
					event(line)
				}
			},
			OnStderr: func(chunk []byte) { fmt.Fprint(os.Stderr, string(chunk)) },
		})
		if err != nil {
			return err
		}
		event(pending)
		pending = ""
		if streamErr != nil {
			return streamErr
		}
		if !completed {
			return fmt.Errorf("Codex ended without turn.completed")
		}
		return nil
	}
	if err := execute([]string{"exec", "--dangerously-bypass-approvals-and-sandbox", "--skip-git-repo-check", "--model", "gpt-5.6-luna", "--json", "Read sales.csv. Write report.md with paid revenue by channel, total, and cancelled amount separately."}); err != nil {
		return err
	}
	if threadID == "" {
		return fmt.Errorf("Codex did not return a thread ID")
	}
	if err := execute([]string{"exec", "resume", "--dangerously-bypass-approvals-and-sandbox", "--skip-git-repo-check", "--json", threadID, "Add two concrete next actions for the sales manager to report.md. Keep the original figures."}); err != nil {
		return err
	}

	report, err := sandbox.Files.ReadText(ctx, "/home/user/work/report.md", "")
	if err != nil {
		return err
	}
	fmt.Println("report.md\n" + report)
	return nil
}

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

Check command completion independently of events. Output on stdout or a successful process start does not establish success: wait for turn.completed, handle nonzero exit codes, then return the file.

Build a conversation with App Server

codex app-server accepts application commands on stdin and sends responses and events on stdout. This example starts the server in a ready-made sandbox, uploads a sales CSV, and displays the response as it is generated.

mjs

import { Readable } from "node:stream";
import { Sandbox } from "@abox-dev/sdk";

const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) throw new Error("OPENAI_API_KEY is required");
const sandbox = await Sandbox.create("codex", {
  timeoutMs: 600_000,
  envs: {
    ALL_PROXY:
      process.env.SANDBOX_PROXY_URL ??
      "socks5h://sandbox-proxy.agentbox.ru:65180",
    NO_PROXY: "localhost,127.0.0.1",
  },
});
try {
  await sandbox.files.write(
    "/home/user/sales.csv",
    "channel,paid_revenue_rub\nOnline,120000\nRetail,80000\n",
  );
  const messages = new Readable({ objectMode: true, read() {} });
  let buffer = "";
  const server = await sandbox.commands.run("codex app-server", {
    background: true,
    stdin: true,
    timeoutMs: 300_000,
    onStdout(chunk) {
      buffer += chunk;
      let end;
      while ((end = buffer.indexOf("\n")) !== -1) {
        const line = buffer.slice(0, end);
        buffer = buffer.slice(end + 1);
        try {
          if (line.trim()) messages.push(JSON.parse(line));
        } catch (error) {
          messages.destroy(error);
        }
      }
    },
    onStderr: (chunk) => process.stderr.write(chunk),
  });
  server.wait().then(
    () => messages.push(null),
    (error) => messages.destroy(error),
  );
  const incoming = messages[Symbol.asyncIterator]();
  let status;
  async function receive() {
    const { value: message, done } = await incoming.next();
    if (done) throw new Error("App Server closed before completing the task");
    if (message.error) throw new Error(message.error.message);
    if (message.method === "item/agentMessage/delta")
      process.stdout.write(message.params.delta);
    if (message.method === "turn/completed") {
      status = message.params.turn.status;
      if (status !== "completed")
        throw new Error(message.params.turn.error?.message ?? status);
    }
    return message;
  }
  let nextId = 0;
  async function call(method, params) {
    const id = ++nextId;
    await server.sendStdin(JSON.stringify({ id, method, params }) + "\n");
    while (true) {
      const message = await receive();
      if (message.id === id) return message.result;
    }
  }
  await call("initialize", {
    clientInfo: { name: "sales-app", version: "1.0.0" },
  });
  await server.sendStdin(JSON.stringify({ method: "initialized" }) + "\n");
  await call("account/login/start", { type: "apiKey", apiKey });
  const { thread } = await call("thread/start", {
    model: "gpt-5.6-luna",
    cwd: "/home/user",
    approvalPolicy: "never",
    sandbox: "danger-full-access",
  });
  await call("turn/start", {
    threadId: thread.id,
    input: [
      {
        type: "text",
        text: "Read sales.csv. Give a short sales briefing with revenue by channel and the total in RUB.",
      },
    ],
  });
  while (!status) await receive();
  console.log("\nStatus:", status);
} finally {
  await sandbox.kill();
}

import json
import os
import sys
from queue import Queue
from threading import Thread
from agentbox import Sandbox

api_key = os.environ["OPENAI_API_KEY"]
sandbox = Sandbox.create(
    "codex",
    timeout=600,
    envs={
        "ALL_PROXY": os.environ.get(
            "SANDBOX_PROXY_URL", "socks5h://sandbox-proxy.agentbox.ru:65180"
        ),
        "NO_PROXY": "localhost,127.0.0.1",
    },
)
try:
    sandbox.files.write(
        "/home/user/sales.csv",
        "channel,paid_revenue_rub\nOnline,120000\nRetail,80000\n",
    )
    messages = Queue()
    buffer = ""

    def on_stdout(chunk):
        global buffer
        buffer += chunk
        while "\n" in buffer:
            line, buffer = buffer.split("\n", 1)
            if line.strip():
                messages.put(json.loads(line))

    server = sandbox.commands.run(
        "codex app-server", background=True, stdin=True, timeout=300
    )

    def read_messages():
        try:
            server.wait(
                on_stdout=on_stdout,
                on_stderr=lambda chunk: print(chunk, end="", file=sys.stderr),
            )
            messages.put(RuntimeError("App Server closed before completing the task"))
        except Exception as error:
            messages.put(error)

    reader = Thread(target=read_messages, daemon=True)
    reader.start()
    status = None

    def receive():
        global status
        message = messages.get(timeout=300)
        if isinstance(message, Exception):
            raise message
        if "error" in message:
            raise RuntimeError(message["error"]["message"])
        if message.get("method") == "item/agentMessage/delta":
            print(message["params"]["delta"], end="", flush=True)
        if message.get("method") == "turn/completed":
            turn = message["params"]["turn"]
            status = turn["status"]
            if status != "completed":
                raise RuntimeError((turn.get("error") or {}).get("message", status))
        return message

    next_id = 0

    def call(method, params):
        global next_id
        next_id += 1
        server.send_stdin(
            json.dumps({"id": next_id, "method": method, "params": params}) + "\n"
        )
        while True:
            message = receive()
            if message.get("id") == next_id:
                return message["result"]

    call("initialize", {"clientInfo": {"name": "sales-app", "version": "1.0.0"}})
    server.send_stdin(json.dumps({"method": "initialized"}) + "\n")
    call("account/login/start", {"type": "apiKey", "apiKey": api_key})
    thread = call(
        "thread/start",
        {
            "model": "gpt-5.6-luna",
            "cwd": "/home/user",
            "approvalPolicy": "never",
            "sandbox": "danger-full-access",
        },
    )["thread"]
    call(
        "turn/start",
        {
            "threadId": thread["id"],
            "input": [
                {
                    "type": "text",
                    "text": "Read sales.csv. Give a short sales briefing with revenue by channel and the total in RUB.",
                }
            ],
        },
    )
    while status is None:
        receive()
    print("\nStatus:", status)
finally:
    sandbox.kill()

package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"log"
	"os"
	"strings"
	"time"

	"github.com/abox-dev/sdk/packages/go-sdk"
)

type message struct {
	ID     *int            `json:"id"`
	Method string          `json:"method"`
	Result json.RawMessage `json:"result"`
	Error  *struct {
		Message string `json:"message"`
	} `json:"error"`
	Params struct {
		Delta string `json:"delta"`
		Turn  struct {
			Status string `json:"status"`
			Error  *struct {
				Message string `json:"message"`
			} `json:"error"`
		} `json:"turn"`
	} `json:"params"`
}

func run() (err error) {
	apiKey := os.Getenv("OPENAI_API_KEY")
	if apiKey == "" {
		return errors.New("OPENAI_API_KEY is required")
	}
	proxy := os.Getenv("SANDBOX_PROXY_URL")
	if proxy == "" {
		proxy = "socks5h://sandbox-proxy.agentbox.ru:65180"
	}
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
	defer cancel()
	client, err := agentbox.NewClient()
	if err != nil {
		return err
	}
	sandbox, err := client.Sandboxes.Create(ctx, &agentbox.CreateSandboxOptions{
		Template: "codex", Timeout: 10 * time.Minute,
		Env: map[string]string{"ALL_PROXY": proxy, "NO_PROXY": "localhost,127.0.0.1"},
	})
	if err != nil {
		return err
	}
	defer func() {
		cleanupCtx, stop := context.WithTimeout(context.Background(), 30*time.Second)
		defer stop()
		_, cleanupErr := sandbox.Kill(cleanupCtx)
		err = errors.Join(err, cleanupErr)
	}()
	if _, err := sandbox.Files.WriteText(ctx, "/home/user/sales.csv", "channel,paid_revenue_rub\nOnline,120000\nRetail,80000\n", nil); err != nil {
		return err
	}
	messages := make(chan message, 64)
	parseErrors := make(chan error, 1)
	var buffer string
	server, err := sandbox.Commands.Start(ctx, "codex", &agentbox.CommandOptions{
		Args: []string{"app-server"}, Stdin: true,
		OnStdout: func(chunk []byte) {
			buffer += string(chunk)
			for {
				line, rest, found := strings.Cut(buffer, "\n")
				if !found {
					return
				}
				buffer = rest
				if strings.TrimSpace(line) == "" {
					continue
				}
				var msg message
				if err := json.Unmarshal([]byte(line), &msg); err != nil {
					select {
					case parseErrors <- err:
					default:
					}
					return
				}
				select {
				case messages <- msg:
				case <-ctx.Done():
					return
				}
			}
		},
		OnStderr: func(chunk []byte) { fmt.Fprint(os.Stderr, string(chunk)) },
	})
	if err != nil {
		return err
	}
	status := ""
	receive := func() (message, error) {
		select {
		case msg := <-messages:
			if msg.Error != nil {
				return msg, errors.New(msg.Error.Message)
			}
			if msg.Method == "item/agentMessage/delta" {
				fmt.Print(msg.Params.Delta)
			}
			if msg.Method == "turn/completed" {
				status = msg.Params.Turn.Status
				if status != "completed" {
					if msg.Params.Turn.Error != nil {
						return msg, errors.New(msg.Params.Turn.Error.Message)
					}
					return msg, fmt.Errorf("turn ended: %s", status)
				}
			}
			return msg, nil
		case err := <-parseErrors:
			return message{}, err
		case <-server.Done:
			return message{}, errors.New("App Server closed before completing the task")
		case <-ctx.Done():
			return message{}, ctx.Err()
		}
	}
	send := func(value any) error {
		data, err := json.Marshal(value)
		if err != nil {
			return err
		}
		_, err = server.Write(ctx, append(data, '\n'))
		return err
	}
	nextID := 0
	call := func(method string, params any) (json.RawMessage, error) {
		nextID++
		if err := send(map[string]any{"id": nextID, "method": method, "params": params}); err != nil {
			return nil, err
		}
		for {
			msg, err := receive()
			if err != nil {
				return nil, err
			}
			if msg.ID != nil && *msg.ID == nextID {
				return msg.Result, nil
			}
		}
	}
	if _, err := call("initialize", map[string]any{"clientInfo": map[string]string{"name": "sales-app", "version": "1.0.0"}}); err != nil {
		return err
	}
	if err := send(map[string]string{"method": "initialized"}); err != nil {
		return err
	}
	if _, err := call("account/login/start", map[string]string{"type": "apiKey", "apiKey": apiKey}); err != nil {
		return err
	}
	result, err := call("thread/start", map[string]any{
		"model": "gpt-5.6-luna", "cwd": "/home/user",
		"approvalPolicy": "never", "sandbox": "danger-full-access",
	})
	if err != nil {
		return err
	}
	var thread struct {
		Thread struct {
			ID string `json:"id"`
		} `json:"thread"`
	}
	if err := json.Unmarshal(result, &thread); err != nil {
		return err
	}
	if _, err := call("turn/start", map[string]any{
		"threadId": thread.Thread.ID,
		"input":    []map[string]string{{"type": "text", "text": "Read sales.csv. Give a short sales briefing with revenue by channel and the total in RUB."}},
	}); err != nil {
		return err
	}
	for status == "" {
		if _, err := receive(); err != nil {
			return err
		}
	}
	fmt.Println("\nStatus:", status)
	return nil
}

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

call matches responses by id while continuing to process notifications. The handler assembles complete JSON lines from stdout chunks, displays item/agentMessage/delta, and checks the status in turn/completed. account/login/start sends the API key through stdin rather than command arguments.

For another question, send a new turn/start with the same thread.id while keeping the process and sandbox alive. This example stops after the first response and deletes the sandbox. See the App Server protocol for other methods.

Timeouts and preserving work

Sandbox lifetime and command timeout are separate limits. These examples allow a ten-minute sandbox lifetime and five minutes for one task. If a command times out, stop it and decide which intermediate files to keep. The finally block deletes the sandbox even on failure.

To continue later, keep the sandbox ID and thread_id, then pause the sandbox. Deleting it also removes the report and Codex history unless your application has saved them elsewhere.

Codex ​

Connect ​

Prepare a sales report ​

Return structured data to your application ​

Stream events and ask a follow-up ​

Build a conversation with App Server ​

Timeouts and preserving work ​