Automate, Embed, and Run Long Work Safely

Automation magnifies the quality of the underlying workflow. If the manual process has unclear inputs, unstable decisions, broad permissions, or inconsistent evidence, scheduling it will produce failures faster and with less visibility. Repeat the workflow under supervision until its boundaries and common exceptions are known.

Choose an automation candidate with a clear trigger, bounded data, deterministic prechecks, recoverable actions, and an operator who owns exceptions. Read-only monitoring, classification, and draft preparation are safer first candidates than publishing, deletion, payments, or external communication.

Non-interactive execution lets a script or workflow invoke Codex and receive output without an ongoing chat. That makes inputs, environment, exit behavior, and machine-readable results more important. Use the current CLI help and official non-interactive documentation for exact flags because command options can evolve.

Bound the task with an explicit working directory, authority profile, expected output, and timeout or stopping condition. Capture standard output, standard error, exit status, and produced artifacts. A paragraph that sounds successful is not enough for a machine-run workflow; require a result shape that downstream logic can validate.

Use `codex exec` for shell scripts, CI steps, scheduled jobs, and pipelines. It streams progress to standard error and prints the final message to standard output. `--json` changes standard output to JSON Lines events; `--output-schema` validates the final response against a JSON Schema; `-o` writes the last message to a file. It starts read-only by default, and `--sandbox workspace-write` is the explicit step when a controlled job must edit.

Use `@openai/codex-sdk` in server-side Node.js when your application needs to start, continue, or resume Codex threads programmatically. Use `codex app-server` only for a rich client that needs the lower-level JSON-RPC interface for authentication, conversation history, approvals, and streamed events. App-server powers clients such as the IDE extension; ordinary CI automation should use the SDK or `codex exec` instead.

The default app-server transport is newline-delimited JSON over standard input and output. A client starts the process, sends `initialize`, sends the `initialized` notification, then starts a thread and a turn while continuously reading notifications. Generate TypeScript or JSON Schema files from the installed CLI so the client matches that exact Codex version instead of copying protocol shapes from a blog post.

A local WebSocket listener exists for remote terminal and client experiments, but the current documentation marks that transport experimental and unsupported. Do not expose a non-loopback listener without the documented authentication and TLS protections. For this guide's lab, stay on the default stdio transport and generate schemas; that teaches the protocol boundary without creating a network service.

The desktop app can schedule a task after the prompt, project, cadence, and permission boundary are defined. In a Git project, scheduled tasks can use dedicated background worktrees so they do not collide with foreground changes; in a non-version-controlled project they run directly in the project directory. That difference should influence whether the task is safe to schedule.

A schedule is an operator-owned product. Define how to disable it, where results appear, what counts as unchanged, and which failures notify a human. Start with read-only drift checks. Do not schedule publishing, deletion, messaging, or production mutation until supervised runs demonstrate idempotence, recovery, and explicit authority for the side effect.

A scheduled task runs again. That single fact changes the design. The workflow must know which inputs are new, which work is already complete, and what should happen after an interrupted run. Idempotence means repeating the same operation does not create an unintended duplicate effect.

Use stable identifiers, checkpoints, last-success markers, and explicit deduplication where side effects are possible. Do not mark work complete until the receipt is durably stored. If a run fails after partially acting, the next run should reconcile what happened rather than starting blindly from the beginning.

Some work is not a schedule but an objective that requires many steps, checkpoints, or external waits. Break it into milestones with acceptance criteria and store progress outside transient reasoning. The agent should be able to resume from the last proven state and explain what is complete, active, pending, or blocked.

Long duration does not broaden authority. A goal to finish a release still does not authorize publishing, buying services, changing permissions, or contacting people unless those actions were explicitly included. Reconfirm consequential steps when the external state may have changed since the goal began.

Every run should produce a compact receipt containing the trigger, input window, environment, actions, outputs, checks, cost or usage signal when available, and remaining exceptions. Unchanged state is a valid monitoring result, not a reason to invent work.

Define escalation before launch: which failure retries automatically, which pauses, which pages a human, and what evidence accompanies the alert. A human should be able to resume without reconstructing the agent's hidden context.