openai-agents

Self-hosted environment for OpenAI Agents API sessions (Codex CLI and codex exec-server helpers).

Use it on boxctl

1. On the dashboard, pick openai-agents in the Template picker and click Boot box.
2. The box boots, then runs openai-agents/codex-executor.sh on itself. The button reads Booting… until the script has finished.
3. Open the box's Terminal and follow the guide below. The box's row keeps a link back to this page under the template's name.

The guide is shared with the onctl CLI, so it starts from an onctl up -a openai-agents/codex-executor.sh command. Booting a box with this template replaces that command; everything the guide runs on the VM itself applies as written.

Options

boxctl cannot pass options to a template yet, so each of these keeps its default.

OpenAI Agents API self-hosted environment

Prepares the VM to be the environment of OpenAI Agents API sessions. OpenAI runs the agent; codex exec-server on the VM dials out to OpenAI to receive shell commands and file edits. The VM needs no inbound port.

onctl up -n agent -a openai-agents/codex-executor.sh

The template installs Node.js and the Codex CLI (@openai/codex@alpha), creates /workspace, and adds two helpers for the per-session part:

• codex-set-key saves the environment key to /root/.codex-env (mode 600). It reads the key from stdin, so the key never appears in a command line or a log. That's also why the key isn't a template variable.
• codex-connect <remote_url> <environment_id> starts the executor for one session as the systemd unit codex-exec-server. A new session replaces the previous one.

Connect a session

1. Create an environment key on the Agents tab of the OpenAI platform, in the same project as your application's key, with every other permission set to None. It can only connect environments.
2. On the VM, run codex-set-key and paste the key.
3. From your application, create a session with environment: {type: "self_hosted", workspace_directory: "/workspace"} using your application's key, which stays outside the VM.
4. On the VM, run codex-connect with the session's environment.remote_url and environment.id.
5. Send the session a task. The environment connects within seconds; follow the executor with journalctl -u codex-exec-server -f.

Debian and Ubuntu only. Use a separate VM per user or workload: agents that share a VM share its files and the key.

Options

onctl up -n agent -a openai-agents/codex-executor.sh \
  -e CODEX_VERSION=0.161.0-alpha.4 \
  -e WORKSPACE=/srv/agent

WORKSPACE must match the session's workspace_directory.

See the template's source for exactly what it runs.