Local Agents

Local agents run a coding agent, such as Codex or Claude Code, on your machine. You send them work from One Horizon, and each run stays linked to its initiative, bug, or todo.

A local agent only takes work from its owner, on the machine where it was set up. Other workspace members cannot start runs on your machine by assigning you work.

Before you begin

• Sign in to Desktop with the workspace that owns the work.
• Have Git available. Desktop can use its bundled Git; the CLI needs Git in your terminal.
• Install and sign in to the coding agent you want to use, unless it is Codex, which is bundled. See Coding agent requirements.
• Have a writable repository with a base branch such as main. Desktop can also create or clone one for you.
• For pull requests, merge requests, or handing work to another machine, the repository needs an origin remote this machine can push to.

Local agents sign in with OAuth. API keys cannot create or run them.

Desktop setup

Local agents are listed on the agents page under Workflows.

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 project path

   Create a new GitHub project, clone an existing remote, or select a valid existing folder. If you create a project, connect GitHub first, choose the owner and repository name, then confirm the local path preview. GitLab projects can be cloned or selected as existing folders when this machine can push to them. Public repositories show a warning before setup continues.

3. 3

   Choose the coding agent and preset

   Select Codex, Claude Code, Cursor, OpenCode, Mistral Vibe, Hermes, Cline, DeepSeek Harness, or OMP, then choose a compatible preset. OpenCode, Hermes, Cline, DeepSeek Harness, and OMP declare code work only, so choose Builder.

4. 4

   Set access and ownership

   Choose Read-only, Workspace access, or Full access. Set the agent name for the project this agent will own on this machine.

5. 5

   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. After setup, add skills, MCP servers, or plugins from the agent's Capabilities card; Agent capabilities lists which coding agents support each.

6. 6

   Start the agent

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

Desktop opens a browser sign-in to authorize the agent, which then runs as a separate process. Closing the Desktop window does not stop it. Stop agent releases its active work and shuts it down.

Once the agent is online, open an initiative, bug, or todo and select Send to... to start a run. Picking a specific agent sends the run to that agent only.

Other ways to create an agent

Get started on the Workflows overview creates one agent for your chosen harness plus starter workflows in one pass. That agent runs every workflow step. In the workflow designer, Create agent in an agent step's Agent selector creates an agent and selects it for that step. From a terminal, follow Use in Terminal.

Coding agent requirements

One Horizon never supplies a model credential. Each coding agent must be installed on your PATH and signed in with its own account before setup. Desktop and the CLI disable any agent they cannot find.

• Codex: bundled with One Horizon. Codex covers thread links and behavior.
• Claude Code: the claude binary, signed in to Claude Code. See Claude Code.
• Cursor: the agent binary (some installs call it cursor-agent), signed in. The Cursor IDE and its MCP connector are not enough on their own. See Cursor.
• OpenCode: the opencode CLI with a signed-in provider. Follow the OpenCode setup guidance.
• Mistral Vibe: the vibe-acp binary, with MISTRAL_API_KEY set on this machine.
• Hermes: the hermes binary from Nous Research. Sign in with hermes login or hermes acp --setup first. Setup runs hermes acp --check.
• Cline: the cline binary (npm install -g cline), signed in with cline auth. That covers a Cline account, a ChatGPT subscription, or your own provider key. Setup runs cline doctor.
• DeepSeek Harness: the dsh binary (npm install -g @deepseek-ai/dsh), a developer preview from DeepSeek whose behavior can change between versions. Set DEEPSEEK_API_KEY, or store the key with DeepSeek's credential service. Because DeepSeek Harness only reports a missing key on its first prompt, setup sends it one short test turn.
• OMP: the omp binary from Oh My Pi. Configure a provider inside OMP (/login, or a provider API key in its environment).

Claude Code and Cursor can start their own login from the setup dialog. The other coding agents use credentials you set up with the vendor. If one reports that it is signed out, setup stops before the agent is created, shows Sign in required, and links to the vendor's help page.

Presets

The preset sets the starting access level and pull or merge request behavior:

Builder edits files in the task workspace. Planner investigates and plans. Reviewer can run local tools and browser automation. You can change these settings later.

Project folder and worktrees

In Desktop, Create new project creates a GitHub repository and a local checkout, Clone repository clones an existing GitHub, GitLab, or Bitbucket repository, and Use existing folder uses a folder that is already a Git repository. The folder cannot be changed after the agent is created; create a new agent to use another repository.

By default, each run gets its own worktree under ~/.one/worktrees, created from your repository. To store worktrees elsewhere, add worktreesDir to ~/.one/config/local.json:

{  "worktreesDir": "D:\\OneHorizon\\worktrees"}

With Branch per task, runs use the selected folder directly and switch branches.

When you create or clone through a connected GitHub account, Desktop sets up a Git credential helper scoped to that repository, so no provider token is written into the project folder. GitLab, Bitbucket, and existing folders use the Git credentials already on this machine.

macOS protected folders

Choosing a repository in Documents, Downloads, or Desktop can trigger a macOS file-access prompt. The grant covers only the folder you select, and the agent inherits it. Running one agent from Terminal uses your shell's access instead.

Settings

Open the agent from the agents page to see its Settings card, in the browser or in Desktop.

The Workflow file holds local settings such as hooks, worktree behavior, and commands. It is not the same as a workflow you build in the workflow designer.

Change a setting, then select Save settings. Auto start saves immediately and is on by default; turn it off if the agent should not start when Desktop opens.

Settings saved in the browser apply after the agent restarts on its machine. In Desktop, use Agent actions → Restart agent, or Restart all agents on the agents page. From the CLI, run one agent stop and one agent start.

Only you can open or change a local agent you own.

Sign-in and account changes

One operating-system user profile runs one One Horizon account at a time. Local configuration, credentials, repositories, and processes stay inside that profile.

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 a config that belongs to another account, or an unbound config for a newly signed-in account.

After updates

When Desktop installs an update, it stops your running local agents, relaunches, and restarts them on the new version. If one does not come back, use Agent actions → Restart agent. If you replace the app outside the updater, restart your agents yourself.

After a CLI update, the next CLI command restarts background agents. Stop and start foreground agents yourself.

Fix project setup failures

When project setup fails, Desktop shows the problem and the fix in the setup flow. Run diagnostics collects redacted Git, remote, and credential details you can send to support.

Frequently asked questions