Run a local Codex worker

Run queued One Horizon work in Codex. A local worker runs on your machine, registers as your private Codex worker, claims one session at a time, and reports progress back to One Horizon.

Use Desktop to create, start, and stop a worker from the One Horizon app. Use the CLI for terminal control, scripts, or foreground logs. If you are building your own worker, start with Build a local agent worker.

Before you start

You need:

• Codex installed on this machine and available on your PATH
• Access to a One Horizon workspace
• A repo where the worker can create or use a task workspace
• One Horizon Desktop, or Node.js 20 or newer for the CLI path

Desktop setup

Desktop is the shortest path when you want a local worker without running one auth login first. It uses your signed-in One Horizon session to register the worker, then starts a local child process.

flowchart TD
  OpenDesktop["Open Desktop"]
  Agents["Open Agents"]
  Agent["Select Codex local"]
  Create["Create worker"]
  Start["Start worker"]
  Send["Send work to app"]
  Run["Worker claims session"]

  OpenDesktop --> Agents --> Agent --> Create --> Start --> Send --> Run

1. Open the One Horizon Desktop app and sign in.
2. Open the workspace where the work lives.
3. Go to Agents, open Codex local, and choose Create worker.
4. Pick the worker name, repo folder, workspace mode, workflow file, and optional worker instructions.
5. Create the worker, then open the worker details page and choose Start.

Desktop writes the same worker config the CLI uses, registers or reuses your private Codex local agent, and keeps worker status in sync. Stop asks the server to stop the worker and shuts down the local process when this Desktop app owns it.

After the worker is online, open a task or initiative and use Send to… to start a Codex local run. The work appears as an app run, moves through queued and running states, and links back to session activity.

CLI setup

Install the CLI when you want the worker loop in a terminal:

flowchart TD
  Install["Install CLI"]
  Login["Sign in"]
  Workspace["Select workspace"]
  Setup["Run setup"]
  Doctor["Check setup"]
  Run{"Run mode"}
  OneTask["one worker run"]
  Watch["one worker watch"]
  Start["one worker start"]

  Install --> Login --> Workspace --> Setup --> Doctor --> Run
  Run --> OneTask
  Run --> Watch
  Run --> Start

npm install -g @onehorizon/cli

Sign in with your One Horizon account:

one auth login

Confirm the CLI can see your session:

one auth status

Select a workspace

Choose the workspace where your queued work lives:

one ws use

You can also pass a workspace name or ID:

one ws use <name-or-id>

Set up the worker

Run guided setup once:

one worker setup

Setup creates or reuses a One Horizon worker for your active workspace and user, then saves local runtime settings under ~/.one/config/ for this machine.

The starter workflow tells the worker how to prepare the repo, run Codex, post a handoff comment, and move finished work after checks pass.

You can add custom instructions from the One Horizon agent and worker screens. Agent instructions apply to every Codex local run for that agent. Worker instructions apply only when that worker claims the run, which is useful for roles such as docs polish or research-heavy tasks. Desktop also lets you add worker instructions during worker creation.

Check setup

Run the doctor before you leave a worker running:

one worker doctor

It checks auth, the selected workspace, server worker registration, local runtime settings, the workflow file, the workspace root, and the Codex command.

one worker doctor also reports stale local runtime configs that no longer have a matching One Horizon worker. Those files are ignored by normal worker lists and starts.

Run one task

Use run to validate your workflow or handle one known task:

one worker run tsk_123

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

Start a foreground worker

Use watch to see progress in the current terminal:

one worker watch

The worker heartbeats, polls queued sessions assigned to your local worker, claims one session before execution, and then starts Codex.

If the active workspace has multiple server workers, the CLI asks which worker to use. Workers missing local runtime settings are shown as not configured on this machine, and workers that already have a background process are shown as already running; neither can be selected.

Stop a foreground worker with Ctrl+C.

Start a background worker

Use start to run the same worker loop in the background:

one worker start

If the active workspace has multiple server workers, the CLI asks which available worker to start. Use --worker <worker-id> when you already know the worker ID.

Manage it with:

one worker statusone worker logsone worker stop

status and logs only track the background worker started with one worker start. A foreground watch run prints progress in its own terminal.

When multiple server workers exist in the active workspace, one worker status summarizes them. Add --worker <worker-id> to show detailed progress and queued pickup for one worker.

Safety boundaries

Your local worker can run code on your machine. One Horizon keeps local execution owner-only.

• Other workspace users cannot target your local worker.
• Task assignment alone does not authorize execution on your machine.
• The worker uses your Desktop or CLI OAuth session for local execution.
• Your workflow file is trusted local policy.
• Task titles, descriptions, comments, documents, and prompts are untrusted context.

For the deeper model, read Agents and workers and Sessions and claims.

Troubleshooting

If Desktop cannot start the worker, check that the server worker still exists, the repo folder still exists, Codex is available from that machine, and this Desktop install has local runtime settings for that worker.

If CLI watch or start says setup is incomplete, run:

one worker setupone worker doctor

If no work is picked up, check that the task has an agent session for your local worker and that the worker is online. In Desktop, open the worker details page. In the CLI, use one worker status for background runs or check the terminal running one worker watch.

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

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

For command details, see the CLI reference.