Skip to content

Add Databricks sandbox executor example for codex - #3

Draft
HsingTang wants to merge 1 commit into
feat/codex-harnessfrom
hsingtang/databricks-codex
Draft

HsingTang wants to merge 1 commit into
feat/codex-harnessfrom
hsingtang/databricks-codex

Conversation

@HsingTang

@HsingTang HsingTang commented Nov 4, 2026 •

Copy link
Copy Markdown
Owner

Summary

Draft integration that backs the native executor (v1.0 / feat/codex-harness) with a Databricks sandbox, so an agent driven by this SDK runs exec_command / write_stdin / apply_patch inside the sandbox.

This PR is opened inside a personal fork (base feat/codex-harness, head hsingtang/databricks-codex) for Databricks and OpenAI folks to review before anything is proposed upstream. It is not a contribution request to openai/openai-agents-python yet.

Validated end-to-end against a live Databricks sandbox (2026-11-11). Through this gateway + environment.py, the native Environment connected to the gateway's wss:// endpoint and drove a real codex exec-server --listen stdio (reached with _UCODE_DISPATCH_ACTIVE=1, the ucode wrapper's internal recursion sentinel - see Remaining). NativeProvider ran against the sandbox's Databricks AI Gateway codex endpoint using a PAT (no OpenAI key). openai-agents 0.24.0-alpha.7 (preview wheel) on Ubuntu 24.04 / glibc 2.39. This confirmed the newline framing, the full-duplex stdio relay, the self-signed-loopback TLS trust, and bearer auth, plus the full tool/hook/lifecycle surface listed under Validated behaviors below. See the example README for details.

Integration style

It follows the "remote execution" pattern documented in docs/sdk/execution.md: an application-owned gateway speaking the exec-server protocol, plus a lifetime-managing Environment async context manager (the "manage the executor lifetime" pattern). It is the Databricks counterpart of examples/offline_docker.py, and is shipped as an example - not a src/agents module or a dependency extra - to match how the branch ships executor gateways. It deliberately does not use the agents.classic BaseSandboxClient provider model, which is a separate subsystem and not how execution.md connects a self-hosted executor.

Approach

The native Environment dials an authenticated wss:// executor and relays the exec-server protocol over it; a Databricks sandbox runs that exec-server in stdio mode, reached through the databricks-sdk streaming command API (WorkspaceClient.sandbox.execute_command). Nothing in the SDK speaks stdio and nothing in the sandbox speaks WebSocket, so a small localhost gateway bridges them - it terminates the WebSocket, authenticates the bearer token at the HTTP handshake, opens the exec-server's stdio, and relays newline-framed messages both ways. Because execute_command reaches the sandbox outbound through the Databricks control plane, the gateway runs on loopback next to the application and the sandbox needs no inbound ingress. The agent loop runs in-process via NativeProvider, which is what makes the Environment approval / transform / NetworkPolicy hooks available.

Contents

All under examples/codex/databricks/:

  • gateway.py - SandboxExecServerGateway (newline-framed relay + self-signed loopback TLS helper).
  • environment.py - databricks_sandbox_environment, the lifetime context manager that starts the gateway and yields a configured Environment.
  • runner.py - a runnable end-to-end example (optional SANDBOX_CREATE=1 provisioning).
  • README.md, requirements.txt.
  • tests/codex/ - tests for the relay, bearer auth, teardown paths, the context manager, and the SSL_CERT_FILE trust-bundle helper, with a fake CommandProcess.

Validated behaviors (Databricks staging, 2026-11-11)

Driven through this gateway over the real execute_command transport. The live-agent tool calls were scripted deterministically with the SDK's own Responses fixture, so each behavior is exercised directly rather than left to the model's discretion:

  1. exec-server stdio mode - SUPPORTED. The image's codex is a Databricks "ucode" wrapper over a real codex-cli 0.167.0 at /usr/local/libexec/codex-package/bin/codex. Its exec-server supports stdio via the --listen option (values: ws://IP:PORT default, stdio, stdio://); stdio is not a subcommand, which is why exec-server stdio errors. The gateway runs codex exec-server --listen stdio with _UCODE_DISPATCH_ACTIVE=1.
  2. Full-duplex relay + newline framing - CONFIRMED. Real agent.session(environment=...) turns drove tool calls through the gateway to the exec-server and back over the databricks-sdk execute_command streaming CommandProcess (stdin, stdout.readline, text=False).
  3. All three tools - CONFIRMED. exec_command, interactive-TTY write_stdin, and apply_patch (which added a file in the sandbox).
  4. Multi-turn, resume, stop-start - CONFIRMED. Two turns in one session (turn 2 read turn 1's file); a fresh session relaunched the exec-server; a real stop_sandbox + start_sandbox cycle returned to service with the workspace preserved.
  5. Large output - CONFIRMED. A 200k-line stream and a single ~4 MB line both relayed through the newline framing without truncation.
  6. Environment policy hooks - CONFIRMED. approval returning False blocked a command's side-effect; transform_arguments rewrote the command; transform_result changed what the model saw; and a NetworkPolicy was enforced by the executor's managed proxy (an allowed domain returned 200, a non-allowed domain was blocked).
  7. Model via AI Gateway - CONFIRMED. NativeProvider(base_url=".../ai-gateway/codex/v1", api_key=<PAT>) works with the Databricks PAT from ~/.databrickscfg; no OpenAI key. model="gpt-5.5" is served by system.ai.gpt-5-5.

Static checks: ruff check / ruff format --check pass; pytest tests/codex (11 passed) and mypy --strict are clean against the preview wheel on a glibc-2.39 host. Running mypy also caught and fixed a latent bug in the runner's optional provisioning path, which set a non-existent SandboxSpec.image instead of SandboxSpec.environment.image_uri.

Validated topologies

  • In-sandbox: controller co-located with a local codex exec-server --listen stdio subprocess.
  • External controller (product topology): a glibc-2.39 container drove a separate sandbox over the real databricks-sdk execute_command streaming CommandProcess, with tool side-effects confirmed back in the executor sandbox.

Remaining

Internal dependency to resolve before any public release: the gateway reaches the real exec-server via _UCODE_DISPATCH_ACTIVE=1. On the image, codex is a Databricks "ucode" self-healing wrapper that re-dispatches through ucode codex; that env var is the wrapper's internal recursion sentinel (gated by a Databricks feature flag), not a documented or supported interface, and could change. A supported invocation (e.g. the image exposing an exec-server entrypoint, or the wrapper passing exec-server through) should be confirmed with the Databricks sandbox team before this is publicized or used in production.

Open design question (not a blocker): auto-managed trust rewrites the process-global SSL_CERT_FILE, so only one auto-managed environment runs per process; a per-connection trust lever on Environment would remove that constraint. The exec-server also offers a native --listen ws:// mode with built-in --ws-auth that, with the sandbox port_forward API, could simplify the gateway; the SDK's wss/TLS requirement still needs termination somewhere. The managed Agents API path (sandbox codex exec-server --remote dialing OpenAI) remains the alternative and is covered by the cookbook.

This pull request and its description were written by Isaac.

@HsingTang HsingTang changed the title feat: add Databricks sandbox backend for the native executor Add Databricks sandbox backend for the native executor Nov 11, 2026
@HsingTang
HsingTang force-pushed the hsingtang/databricks-codex branch 2 times, most recently from 0adf796 to 7011b5e Compare November 11, 2026 17:36
@HsingTang HsingTang changed the title Add Databricks sandbox backend for the native executor Add Databricks sandbox executor example for codex Nov 11, 2026
@HsingTang
HsingTang force-pushed the hsingtang/databricks-codex branch 5 times, most recently from cd36445 to ef527b5 Compare November 11, 2026 23:30
Add examples/codex/databricks: an application-owned gateway and a
lifetime-managing Environment context manager that back the native
executor with a Databricks sandbox, following the remote-execution
pattern in docs/sdk/execution.md (the Databricks counterpart of
offline_docker.py). The gateway relays the SDK's WSS executor
connection to the sandbox exec-server over the databricks-sdk streaming
command API; databricks_sandbox_environment starts the gateway and
yields a configured Environment.

Ship as an example (not a src/agents module or dependency extra) to
match how the branch ships executor gateways. Include a runnable runner,
a README, example requirements, and tests for the relay, bearer auth,
teardown paths, the context manager, and the SSL_CERT_FILE trust helper.

Validated end-to-end against a live sandbox (personal-staging): the
exec-server stdio mode, bidirectional streaming over execute_command,
and newline framing, plus exec_command / write_stdin / apply_patch,
multi-turn with session resume and a real sandbox stop-start, large and
single-line output, and the Environment approval / transform_arguments /
transform_result hooks with an enforced NetworkPolicy. tests/codex pass
(11) and mypy --strict is clean against the preview wheel on a
glibc-2.39 host. This also fixes the runner's sandbox-image spec, which
set a non-existent SandboxSpec.image instead of
SandboxSpec.environment.image_uri.

Co-authored-by: Isaac <no-reply@databricks.com>
@HsingTang
HsingTang force-pushed the hsingtang/databricks-codex branch from ef527b5 to 1124c2e Compare November 12, 2026 05:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant