awml
Sign in

awml / platforms / codex-agent-laptop

Codex on a laptop

Platform · Public ·
Version 1 of 2
  1. #2 · chrismdp · · 0.4Latest
  2. #1 · chrismdp · · 0.3Showing

Codex on a person's own laptop, started on a schedule by the ChatGPT desktop app's scheduled tasks on a local project, or by cron or launchd running `codex exec`. This describes a kind of platform, not anyone's machine; AWML's example codex-laptop is a different one, where the laptop runs the workflow's own code. Checked against OpenAI's documentation on 22 October 2026.

What it offersInstall recipeYAML

Install a workflow on Codex on a laptop

Each run is a Codex session on the laptop, started by a scheduled task in the ChatGPT desktop app or by codex exec from launchd or cron, which carries out the workflow's steps by following written instructions. Codex runs commands in a sandbox: by default it may write only inside the project folder, and its commands have no network access.

Run awml fit with the workflow's security view and this description first. If it reports code steps, Codex will carry them out by following instructions here, so write each one as an exact procedure, or as a script the instructions tell Codex to run.

What to create

  1. A project folder under notes, holding every context the security view names with at, at the same paths.
  2. The instructions, in AGENTS.md in the project folder or in a skill the task invokes. Give one section to each step, in the order the drawing lists them, saying what it reads, what it writes and what its operation must not do. A draft step writes a draft and never sends it. An outside action marked Ask ends in a draft, or a message asking the person for a yes.
  3. Scripts for any code steps, in the project folder.
  4. A sandbox that lets the run write its notes: sandbox_mode = "workspace-write" in Codex's config.toml. Add network_access = true under [sandbox_workspace_write] only if a step's own code must reach the network, and say calls: any in your own description of the laptop if you do.

Where secrets go

codex login saves the sign in to ~/.codex/auth.json: treat that file like a password. For a run started by launchd or cron with an API key, keep the key in the keychain or a file only you can read, and set CODEX_API_KEY for that one command only, so no other process sees it. Keys for other services go in the services' own connections, or the same way. Never write a key into AGENTS.md, a skill, the scripts or the notes.

How to schedule the triggers

In the ChatGPT desktop app, open Scheduled and create a scheduled task on the local project, or ask in a Codex chat for one, with its cadence. In a Git repository, choose whether it runs in the project itself or in a separate worktree. The computer must be on and the app running, and the project must still be on disk, when the task is due. Scheduled tasks run unattended with your default sandbox settings.

With launchd on a Mac, a job with StartCalendarInterval that was due while the laptop slept runs when it wakes; cron on a Mac skips it. The job runs, in the project folder:

codex exec --sandbox workspace-write --json "Carry out today's run of the workflow in AGENTS.md." >> ~/Library/Logs/<workflow>.jsonl

How to check it is running

In the desktop app, Scheduled lists each task's runs, and runs with findings show as unread. For codex exec, the JSON Lines log records each run's events, including turn.completed or turn.failed. Run the task once by hand after setting it up, and confirm the files the workflow should change have changed.

Sources

  • https://learn.chatgpt.com/docs/automations
  • https://learn.chatgpt.com/docs/non-interactive-mode
  • https://learn.chatgpt.com/docs/agent-approvals-security
  • https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/ScheduledJobs.html