Agents and workers
Agents let One Horizon send planned work to controlled execution. An agent is the app capability. A worker is the runtime. A session is the visible unit of work. A claim is the server-side lease that lets one worker execute one session.
Use this section when you want to understand the runtime model behind the CLI worker, Codex background runs, or future cloud agents.
Choose your path
| Goal | Start here |
|---|---|
| I want to run Codex locally | Local worker quickstart |
| I want to build my own worker | Build a local agent worker |
| I need the API lifecycle | Sessions and claims |
Core terms
| Term | Meaning |
|---|---|
| Agent | An app capability backed by a One Horizon OAuth client. |
| Worker | One execution instance for an agent. A local worker runs on a user's machine. A cloud worker runs in a provider-controlled environment. |
| Session | One visible unit of agent work, usually tied to a task or initiative. Creating a session queues work, but does not execute it by itself. |
| Work claim | The authorization and concurrency boundary before execution. A worker must claim a session before it can run. |
| Activity | A progress, plan, URL, completion, failure, or policy event emitted while the worker handles a session. |
Execution modes
The platform models two execution modes.
Owner local workers are private to the user who started them. Other workspace members cannot cause execution on someone else's machine. The local worker uses the user's Desktop or CLI OAuth session and only receives sessions for that user.
Cloud workers are workspace-level execution targets. A cloud worker may receive a webhook notification when work is queued, but it still uses the same REST API to fetch, claim, update, and complete the session.
The local worker policy is intentionally strict. Assigning a task or mentioning an agent in workspace content should not make code run on another user's laptop.
Built-in paths
Codex is the built-in local worker path. You can create and start it from Desktop, or run it from the CLI when you prefer terminal control. Both paths register a private worker for your workspace and user, then claim queued sessions through the same agent work API. The local worker quickstart covers both setup paths.
You can also build your own local worker against the same REST protocol. The build guide covers the worker loop.
Cloud workers use the same platform model. A cloud worker can receive a webhook when a session is queued, then must still claim and update the session through the REST API.
Dispatch flow
Agent work moves through the same control loop whether the worker is local or cloud:
flowchart TD
Session["Session queued"]
Poll["Worker polls"]
Claim["Claim accepted"]
Execute["Worker executes"]
Activity["Activities updated"]
Finish{"Outcome"}
Complete["Complete"]
Fail["Error"]
Release["Release"]
Session --> Poll --> Claim --> Execute --> Activity --> Finish
Finish --> Complete
Finish --> Fail
Finish --> Release- A user or system creates an agent session.
- The platform stores the session as queued work for a specific agent and execution mode.
- An eligible worker polls for sessions, or a cloud worker receives a webhook notification and then polls.
- The worker claims the session before doing anything else.
- The worker emits activities and session metadata updates as it works.
- The worker completes, fails, or releases the claim.
The claim is the execution boundary. Session creation requests work. A successful claim authorizes a worker to execute that request. If you are building against the REST API, sessions and claims are the core primitives to understand.
Trusted instructions and untrusted context
Agent sessions separate trusted instructions from untrusted context.
Trusted instructions come from system policy, the agent profile, the worker configuration, and the owner's workflow file. The mandatory One Horizon policy is always included first. Agent owners can add up to 2,000 characters of agent-level instructions for every run, and worker owners can add up to 2,000 characters of worker-level instructions for specialized roles such as docs, research, or review.
Untrusted context includes task titles, task descriptions, comments, documents, and user prompts. The model can read this content, but it cannot use it to change worker policy, sandbox behavior, credentials, or allowed side effects.
Workers must enforce action policy before filesystem access, shell execution, network access, workspace writes, or external side effects such as pushing a branch or opening a pull request.
Control signals
Workspace admins and automation can send control signals to a running worker without stopping the session it is currently executing. Workers poll their worker record every few seconds and act on the signal before acknowledging it.
| Signal | Effect |
|---|---|
stop | Worker finishes the current session turn, then exits. |
pause | Worker stops dispatching new sessions but keeps any active run alive. |
resume | Worker resumes dispatching after a pause. |
restart | Worker exits and starts a fresh process when its launcher supports respawn. |
Control signals are acknowledged after acting on them. Unacknowledged signals stay pending.
How this relates to custom apps
Custom apps cover OAuth login, webhooks, and API calls. Agents add an execution surface: workers, sessions, claims, activities, and runtime policy.
Use custom app docs when you want to integrate another system with workspace events or API calls. Use agent docs when that app needs to receive work, run a worker, and report execution back to the platform.
API reference
The agent work REST API lives under:
/api/v1/workspaces/{workspaceId}/agentsIt includes agent profiles, workers, sessions, worker polling, session claims, activities, completion, failure, and release operations. See the API reference for the exact request and response schemas.