Skip to main content
Pinework turns work into execution in three stages, tied together by one run. For the loop as a person sees it, see How Pinework works.

​
Three stages: orchestration, dispatch, runtime

​
A wake becomes at most one queued run

A wake names one agent and the reason it woke. The run stores that reason in triggerSource, such as assignment, mention, cron or webhook. Run defines every value. Some wakes create no run at all:
  • The agent is not active, or it was deleted.
  • The workspace paused all its agents.
  • The task has an open approval or question.
  • The agent is the assignee, and the task has an unfinished blocking task.
  • The task has a future start time. Most wake sources wait for it.
A wake folds into the agent’s queued or running run on the same task. Runs explains how duplicates merge. Dispatch then resolves the run’s settings. The model comes from the wake, then the task, then the agent, then the workspace default. The place comes from the wake, then the task, then the agent. Tool permissions and max turns come from the agent’s settings. Admission then decides the run’s fate.

​
A runner claims the run

Cloud and your machine explains how the place is picked.
  • Device. The runner on your machine polls the API for work. It names the harnesses installed on the machine. The API hands it a queued run for one of those harnesses. It never hands out more runs than the device’s max concurrent runs.
  • Cloud. The API runs cloud runs itself. A device never claims a cloud run.
A claim carries a 90-second lease. The device runner renews it with heartbeats while the harness works. A device run whose runner stops reporting ends as runner_lost. On a Mac, the runner stops claiming while swap use exceeds RAM or the 1-minute load exceeds the core count. Queued runs wait until the machine frees up. With no device online, the run waits as no_device. Environment and device lists liveness states and the run limit.

​
The runtime compiler builds the bundle

Before launch, the runtime compiler turns the run’s settings into a bundle in the harness’s own format. The bundle holds:
  • The model, reasoning effort and max turns.
  • Tool permissions as allow, ask and deny lists.
  • MCP servers, skills and hooks, including those from enabled plugins.
  • The system prompt as one context file, with the agent’s instructions and the rules that apply.
  • The harness command line and environment, with secrets only as references.
  • A pointer to resume the harness’s last session, when one applies.
Each harness adapter must keep the machine’s own harness settings out of the run. Pinework refuses to start Claude Code without the flags that skip the machine’s own settings and MCP servers. Pinework saves a redacted copy of the setup before the harness starts. pinework run manifest prints it. pinework run context prints the prompt, split into a system slot and a user slot. Run lists both routes.

​
The harness streams back

The harness values are claude (Claude Code), codex, cursor and opencode. All four run on a device and in the cloud. A fifth value, command, marks a workflow gate step that runs no model. The runner turns harness output into run events as the run goes. A device runner sends them to the API. When the harness exits, the runner reports the end. The exit reason then sets the run’s status. pinework run events and the dashboard’s run trace read them.

​
The agent calls back as itself

Each run gets a token for its agent, tied to that run. It stops working when the run ends, or after 48 hours. Inside a run, the CLI uses that token, even when a person is signed in on the same machine. The agent’s access comes from its own grants and grants to the whole workspace. Ownership of a resource counts only for people. An agent cannot take an action that needs the owner role. A workspace manager or owner grant given to an agent is ignored. An agent changes only its own config (agent_self_only). An author it names on a comment, approval or question must be itself (author_must_be_self). The agent calls back through the CLI, the REST API under /api/v1, or the MCP server at https://api.pinework.ai/mcp. The MCP server serves the agent toolset by default. It has 18 tools for tasks, comments, files, runs, agents, approvals and questions. ?toolset=admin serves every tool and needs a human user. An agent gets human_required.

​
The whole path

Run

States, exit reasons and routes.

Agent

The settings dispatch resolves.

Environment and device

Where a run executes.

How Pinework works

The loop as a person sees it.