Local Workers

Local workers let Codex pick up queued work from your machine while the session stays tied to the original initiative, bug, or todo.

This is the intermediate path: more automated than Send to app, but still private to the person running the worker. A local worker is not a team-shared agent. The queued work item should be a usable spec before the worker claims it.

Before you start

Workspace access

Sign in to the workspace that owns the initiative, bug, or todo you want Codex to pick up.

Local worker creation uses OAuth. API Keys can read and write workspace data through the REST API, but they cannot register local workers, claim sessions, or emit worker activity.

Codex

Install Codex and make sure it is available on your PATH.

Repository folder

Choose a folder where the worker can create isolated task worktrees, or use a shared repository mode when that fits your workflow.

Desktop or CLI

Desktop is the shortest setup path. The installed and signed-in CLI gives you terminal control.

Owner-local workers are private to the person who starts them. Only you can delegate work to them. Other workspace members cannot trigger execution on your machine just because they can assign you work.

Desktop setup

Desktop handles the guided setup path.

1. Open the Desktop app and sign in.
2. Open the workspace where the work lives.
3. Go to Agents and select the Codex local agent.
4. Create a worker.
5. Choose the worker name, repo folder, worktree mode, workflow file, and optional worker instructions.
6. Start the worker from the worker details page.

Desktop uses your signed-in session, writes the local worker config, registers or reuses your private Codex worker, and starts the local process. Stop asks the server to stop the worker and shuts down the local process when this Desktop app owns it.

macOS repository folders

On macOS, choosing a repository inside Documents, Downloads, or on the Desktop can trigger a system file-access prompt when Desktop opens the native folder picker. The grant applies to the folder you explicitly select, not your entire home directory or disk.

The worker process Desktop starts runs as a child of the Desktop app and inherits the same access the app received for that folder, so the app must obtain the grant before the worker starts.

Worker registration data under ~/.one/config/ lives in your home folder and does not rely on that protected-folder grant for the repository path.

Running one worker from Terminal uses your shell environment instead of Desktop's macOS grant for the same folder-selection flow.

After the worker is online, open an initiative, bug, or todo and use Send to to queue a Codex local run. Selecting a specific worker in the launcher pins the session to that worker — no other worker can claim it.

Worker settings

In the dashboard, open Agents and select your local worker to reach the worker details page. Worker settings appears on that page in the browser and in Desktop.

The Auto start toggle saves as soon as you change it. Auto start is on by default; turn it off if you do not want this worker to start when Desktop opens on a machine where the worker is already configured.

Worker creation (Desktop, dashboard, or CLI) sets the initial code isolation, workflow file, and related defaults. Return to Worker settings later when you need to change them without recreating the worker.

From the terminal, change the same fields with one worker configure or edit the worker config under ~/.one/config/workers/. See CLI worker creation below.

Change code isolation, workflow file, concurrency, or worktree root, then select Save runtime settings. Runtime changes apply after the worker process starts again.

In Desktop, when you own the worker and the local process is running on your machine, restart it from Worker actions → Restart worker, or select Restart worker in the message that appears after you save.

In the web dashboard, saving stores runtime values on the server. Apply them by restarting the worker on the machine that runs it — use Start and Stop in Desktop on that machine, run one worker stop and one worker start in the CLI, or wait until the worker starts again if it is already offline.

Only you can open or update a local worker you own. Other workspace members cannot load or change another person's local worker or its runtime settings.

CLI worker creation

The CLI gives you terminal control, foreground logs, background worker management, and scriptable worker creation. Install, sign in, and choose a workspace from CLI first.

one worker createone worker doctor

one worker create registers a new server worker for the active workspace and signed-in user, saves local runtime settings under ~/.one/config/workers/, and creates a starter WORKFLOW.md when needed.

one worker doctor checks authentication, workspace selection, server worker registration, local runtime settings, the workflow file, the worktree root, and the Codex command.

What creation configures

The local worker runtime reads the workflow file and worker config for:

Run modes

Run one known work item:

one worker run tsk_123

run creates a local agent session for that work item, claims it, prepares the worktree, runs workflow hooks, starts Codex, emits activities, and completes or fails the session.

Watch for queued sessions in the foreground:

one worker watch

watch heartbeats the worker, polls queued sessions visible to that worker, claims one session at a time, and prints progress in the current terminal. Stop it with Ctrl+C.

Run a background worker:

one worker startone worker statusone worker logsone worker stop

status and logs only track background workers started with one worker start. Foreground watch runs report progress in their own terminal.

If the active workspace has multiple server workers, watch, start, and status can target one worker with --worker <worker-id>. Workers without local runtime settings on this machine are shown as not configured until you run one worker configure for them.

What the worker does

The local worker loop is:

1. Heartbeat the worker so the platform knows it is online.
2. Poll for queued sessions visible to the signed-in owner.
3. Claim one session before execution.
4. Set up the task worktree or shared repository folder according to WORKFLOW.md.
5. Start Codex through the worker runtime.
6. Emit progress, plan, external URL, completion, failure, or policy activities.
7. Complete, fail, or release the claim.

The default runtime polls every 30 seconds, runs one session at a time, and uses codex app-server. Worker creation can use isolated task worktrees or a shared repository mode. Commits created by the worker are attributed to the agent and worker name in git user.name.

Worktrees and workflow files

In task mode, each session gets its own subdirectory under the worker worktree root. This supports isolated git worktrees per task.

In repository mode, sessions share the configured repository folder.

The workflow file can define worktree settings, hooks, retry limits, polling interval, runtime command, and timeouts. The platform still owns session policy and work state transitions.

Safety boundary

Your local worker can run code on your machine and use local tools or secrets that you explicitly make available. Keep trusted workflow policy separate from untrusted work text, comments, documents, and prompts.

Trusted inputs include platform policy, the agent profile, worker config, and your local workflow file. Untrusted inputs include work titles, descriptions, comments, documents, and user prompts.

Review code, tests, and pull requests before merging model-produced work.

Troubleshooting

Common local worker issues are usually missing local configuration or workspace selection problems.

If watch or start says no worker has been created, run:

one worker createone worker doctor

If the server worker exists but this machine is not configured for it, run one worker configure in the active workspace to bind local runtime settings to the existing worker without registering a new one.

If no work is picked up, check that a session exists for your local worker and that the worker is online. Use Desktop worker details, Worker queue in the main menu or title bar, one worker status, or the terminal running one worker watch.

If one worker doctor reports stale local runtime configs, those configs no longer match a server worker. Normal worker lists ignore stale configs.

Clean up worker-managed worktrees when they take too much disk space:

one worker worktreesone worker worktrees remove tsk_123one worker worktrees remove --all

Agent Sessions explains the lifecycle. Build a Local Agent covers a custom polling-based runtime.

Frequently asked questions