Local Agents

Local agents run a supported coding tool on your machine. Send them work from One Horizon, and the run stays tied to the original initiative, bug, or todo.

The agent runs only for its owner on the machine where it was configured. The work item should already be a usable spec.

Before you start

Workspace access

Sign in to the workspace that owns the initiative, bug, or todo you want the local agent to run.

Local agent setup uses OAuth. API Keys can read and write workspace data through the REST API, but they cannot create or run local agents.

Before a local agent can run, these things need to be true:

• You are signed in to the workspace where the work lives.
• Git is installed and available to the app or terminal that starts the agent.
• Claude Code or Cursor is installed, available on PATH, and signed in when you select that runtime. Codex is bundled with the active Desktop and CLI runtime.
• The working directory exists, is writable, and is inside the git repository you want the agent to use.
• The repository has a usable base branch, such as main, master, or the base branch set in the workflow file.
• For pull requests, merge requests, or handoff to another local agent, the repository needs an origin remote that this machine can push to. For code changes, the agent needs to commit locally; One Horizon creates PRs and MRs through the connected GitHub or GitLab integration after the branch is pushed.

Supported runtimes

Choose the runtime the agent will use:

• Codex — bundled with One Horizon. A separately installed codex command is optional when you explicitly configure it as the runtime command. Codex covers recorded thread links and runtime behavior.
• Claude Code — the claude binary, with an authenticated Claude Code CLI session. Claude Code separates MCP setup from local agent setup.
• Cursor — the agent binary (some installs expose cursor-agent). This is a separate install from the Cursor IDE MCP integration; installing or configuring MCP in the editor does not satisfy local agent prerequisites.

Cursor local agents need the Cursor CLI installed and authenticated. The Cursor IDE and MCP connector do not satisfy either requirement on their own. Follow Cursor setup for installation and sign-in, or use the terminal guide to verify a runtime before creating the agent.

Repository folder

Choose the git repository you want the agent to work in. In the default worktree mode, One Horizon creates isolated task worktrees under ~/.one/worktrees and uses your repository as the source. In shared repository mode, runs use the selected folder directly.

Desktop or CLI

Desktop is the shortest setup path and does not require the One Horizon CLI. The optional CLI gives you terminal control.

Local agents are private to the person who starts them. Only you can send work to agents running on your machine. Other workspace members cannot trigger execution on your machine just because they can assign you work.

Desktop setup

Desktop handles the guided setup path from the agents page under Workflows. You can also start the same setup flow from a workflow step when that step needs an agent, or use Get started on the workflows overview to create Planner, Builder, and Reviewer agents plus starter definitions in one pass.

The agents page is the main place to add and manage local agents after setup.

The manual setup flow starts from Add agent on this page and returns here after the runtime is registered.

1. 1

   Open Add agent

   Sign in to Desktop, choose the workspace, open Workflows, then open the agents page and select Add agent.

2. 2

   Choose the runtime and preset

   Select Codex, Claude Code, or Cursor, then choose Builder, Planner, or Reviewer. Claude Code and Cursor must already be authenticated on this machine.

3. 3

   Set access and ownership

   Choose Read-only, Workspace access, or Full access. Set the agent name and select the repository folder this agent will own on this machine.

4. 4

   Configure the workspace

   Choose the workflow file, code isolation, and pull request or merge request behavior. Select a model and, for supported Codex models, reasoning effort. The wizard's Skills step is disabled and can be skipped.

5. 5

   Start the agent

   Select Set up agent. Desktop registers the agent, writes local runtime settings, starts the process when possible, and opens its details page. Start it from that page if automatic startup did not succeed.

The selected access level becomes the trust boundary for commands, files, and provider tools.

Desktop opens a browser sign-in to create a separate local-agent authorization. It writes identity-bound local config, registers or reuses your private local agent, and starts a detached process when setup succeeds. Closing the Desktop window does not stop that process. Stop agent releases its active work and shuts it down even after Desktop has reopened.

The workflow designer has an inline entry point for the same modal. Open a workflow, select an agent step, open the Agent selector, and choose Create agent. Desktop creates the agent without leaving the designer and selects it for that step after setup succeeds. This path fits agents created for a specific workflow definition.

The Workflow file in local agent setup is local runtime policy, such as hooks, worktree behavior, and command settings. The workflow definition you design in the workflow designer is the product-level process that routes work between steps.

Runtime presets

During setup, Builder, Planner, and Reviewer set the initial agent access level and PR/MR creation choice:

Preset	Default agent access	Default PR/MR creation
Builder	Workspace access	On
Planner	Read-only	Off
Reviewer	Workspace access	Off

Builder fits implementation work that edits files in the task workspace. Planner fits investigation and planning. Reviewer fits critique and review passes that can still run local tools and browser automation, but does not request PR/MR creation by default.

The Workspace step shows Code isolation and the PR/MR toggle when agent access is Workspace access or Full access. Read-only agents still collect the workflow file path.

The preset stores agent access on the agent. You can change settings like model, reasoning effort, and agent access later from Settings on the agent details page.

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 agent process Desktop starts inherits the same access the app received for that folder, then runs detached from the Desktop window. Desktop must obtain the grant before the agent starts.

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

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

After the agent is online, open an initiative, bug, or todo and use Send to to start a local agent run. Selecting a specific agent in the launcher sends the run to that agent only.

Desktop, sign-in, and account lifecycle

One operating-system user profile can have one active One Horizon identity. Local config, credentials, repositories, and processes live inside that operating-system profile.

Event	What happens
Close Desktop while signed in	Detached agents keep running, refreshing authorization, and renewing active session claims.
Desktop session expires	Agents keep running with their separate local-agent authorization. Desktop asks you to sign in again.
Open Desktop while signed out	No agent starts until you authenticate as the identity that owns its local config.
Sign out of One Horizon	Desktop releases active claims, stops that identity's agents, and clears their local authorization. The configs stay on disk for the same identity.
Switch accounts in one operating-system profile	Sign-out finishes first. The next account cannot see or start the previous account's local agents.
Use separate macOS, Windows, or Linux login profiles	Each active operating-system session can run its own One Horizon identity, Desktop instance, credentials, and repositories.
Log out of the operating system, restart, or shut down	The operating system can stop agents. Matching agents with Auto start enabled start after that user opens Desktop and signs in again.

An agent config is bound to its owner, dashboard origin, and machine. Older unbound configs are checked against the server before Desktop binds them. Desktop never starts an unbound config for a newly signed-in account.

Settings

In the dashboard, open Agents and select your local agent to reach the agent details page. The Settings card 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 agent to start when Desktop opens on a machine where the agent is already configured.

Settings stay attached to the local agent profile, while the working directory remains machine-local and fixed after creation.

The repository folder is deliberately separate from the server-side settings shown above.

Desktop, dashboard setup, and CLI one agent create let you choose Model, reasoning effort, and agent access when you create the agent. Setup also stores the initial code isolation, workflow file, and related defaults. Return to Settings later when you need to change them without recreating the agent.

Setting	What it controls
Model	Which model the agent uses for local runs. Options depend on the agent runtime.
Reasoning effort	Codex only, for models that support adjustable reasoning. Low, Medium, High, and Max trade speed against depth and token use.
Agent access	Read-only blocks file modifications, Workspace access allows the agent to use local tools inside the configured workspace boundary, and Full access grants host-level trust. Provider-specific runtime flags are derived from this setting.
Code isolation	Worktree per task gives each run its own task worktree. Branch per task shares the repository and switches branches per run.
Workflow file	Path to the workflow file the agent reads, such as WORKFLOW.md.
Max visible runs	How many runs this agent can keep visible at the same time. Active local executions are also capped by WORKFLOW.md and local resource pressure.

Max visible runs is not the same as how many agent processes run at once. The laptop-wide execution cap and resource limits in the workflow file decide when a run can start local processes.

The Working directory is not in this table. It is stored only on this machine and cannot be replaced for an existing agent.

Change any setting in the table, then select Save settings. Visible concurrency changes apply after the agent process starts again.

In Desktop, when you own the agent and the local process is running on your machine, restart it from Agent actions → Restart agent, or select Restart agent in the message that appears after you save. On the Agents page, open the more menu and choose Restart all agents to restart every local agent configured on this machine.

After Desktop or CLI updates

When Desktop installs a direct-distribution update, it first stops running local agents that it can verify for the signed-in account. After relaunch, it restarts configured local agents so they run the new app bundle and shows a summary toast. If an agent does not restart, choose Agent actions → Restart agent. Auto start waits until the restart attempt finishes.

This protection applies to updates installed from Desktop. If you replace the app bundle outside the updater, stop and start local agents manually so they do not keep using the previous bundle.

After you update the CLI, the next CLI command restarts background agents. Foreground agents must be stopped and started again.

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

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

Terminal operation

The CLI can create the same local agent without Desktop and control foreground or background pickup. Run agents from the terminal owns installation, authentication, setup, doctor checks, command behavior, and worktree cleanup.

Local agent FAQs