---
title: "Running Codex as a Headless Agent"
url: https://daily.dev/posts/running-codex-as-a-headless-agent-hkosq0bdy
source_url: https://towardsdatascience.com/running-codex-as-a-headless-agent
type: article
source: "Towards Data Science"
published: 2026-08-21T18:03:50.150Z
updated: 2026-08-21T18:04:15.235Z
tags: ["python", "ai-agents", "automation", "cli", "openai-codex"]
reading_time: 7
upvotes: 1
comments: 0
language: en
---

> ## Documentation Index
> Fetch the complete documentation index at: https://daily.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Running Codex as a Headless Agent

**[Towards Data Science](https://daily.dev/sources/tds)** · 7 min read · 1 upvotes · 0 comments

## Summary

A tutorial demonstrates how to run OpenAI's Codex CLI in headless mode using codex exec, turning it into a callable step inside a deterministic automation workflow rather than an interactive chat assistant. The case study builds a three-step Python pipeline that prepares a research prompt, calls Codex with a JSON output schema and live web search to produce a structured research brief, and then renders that brief into an HTML digest. Key CLI flags covered include --search, --model, --output-schema, -o, --json, and --sandbox for controlling file access during automated runs.

## Full article

daily.dev links to this article rather than hosting it. Read it at the original source: <https://towardsdatascience.com/running-codex-as-a-headless-agent>

## Questions this post answers

### How do I run OpenAI Codex non-interactively from a script instead of using it as a chat assistant?

Use the codex exec subcommand with the CLI installed via npm install --global @openai/codex. Pass flags like --search for live web search, --model to pick a model, --output-schema to enforce a JSON schema, -o to write output to a file, --json to stream JSONL trace events to stdout, and a trailing dash to read the prompt from stdin, then call it from Python with subprocess.run().

_Track evolving agent CLI patterns like this by following daily.dev for automation workflow techniques._

### How can I make an AI agent return structured JSON instead of free-form text so downstream code can consume it?

Pass a JSON schema file to the agent's execution command using a flag such as --output-schema and instruct the prompt to return only the JSON object described by that schema. The agent then writes the structured result to a specified output file, which a script can load directly with json.loads() for the next processing step, such as rendering HTML.

_Developers wiring agents into deterministic pipelines can find more patterns like this on daily.dev._

## Similar posts on daily.dev

- [Codex CLI: OpenAI's Open Agent Harness — Installation, Commands, and CI Integration](https://daily.dev/posts/codex-cli-openai-s-open-agent-harness-installation-commands-and-ci-integration-sl98jxtwh) · SitePoint · 1 upvotes · 0 comments

---

Tags: [#python](https://daily.dev/tags/python), [#ai-agents](https://daily.dev/tags/ai-agents), [#automation](https://daily.dev/tags/automation), [#cli](https://daily.dev/tags/cli), [#openai-codex](https://daily.dev/tags/openai-codex)

[View this post on daily.dev](https://daily.dev/posts/running-codex-as-a-headless-agent-hkosq0bdy)