Skip to main content
Cloud and your machine are the two places a Pinework run can execute. A device run uses a harness on a machine you connected. A cloud run uses a sandbox that Pinework starts for the run.

​
Each agent has one place it runs

Every agent page has a Runs on setting. Its menu has two groups.
  • On a device lists Home · no project files and each folder you added on a device.
  • In the cloud lists Cloud · the task names the repo and each repo you connected.
Picking a folder or Home makes the agent a device agent. Picking Cloud or a repo makes it a cloud agent. A new agent runs on a device unless you pick Cloud. When you change Runs on, the agent posts a note in its conversation. Its next turn starts fresh in the new place, with the conversation replayed.

​
A run can override the agent’s choice

Pinework picks the place for each run in this order:
  1. A choice made for this run only, such as a routine’s Runs on or pinework agent run --env cloud.
  2. The task’s own setting, when a task sets one.
  3. The agent’s Runs on setting.
A conversation has no picker. The composer shows a read-only chip that names where the agent runs. To move a conversation, change the agent’s Runs on.

​
A device run needs your machine online

You connect a machine by installing the Pinework app and signing in with the same account. On Linux or a server, you install the CLI instead. Windows is not supported yet. A device run goes to the agent’s default device. If the agent has none, it goes to the workspace’s default device. The first device you connect becomes the workspace default. On that device, Pinework picks a working folder in this order:
  1. The folder the conversation already uses.
  2. A folder you mapped to the task’s repo.
  3. The agent’s default folder, then the workspace’s default folder.
  4. Your home directory.
The run uses a harness that is installed and signed in on that machine. If none is ready, it can use a provider key saved in the workspace. A device run waits while your machine is unavailable. It never moves to the cloud.
  • Offline device. A device counts as offline 90 seconds after its last heartbeat. The run shows that no device is available. It retries about every 10 seconds.
  • Busy device. Each device runs at most 3 runs at once by default. The run shows that the device is at capacity. It retries about every 30 seconds.
  • Long wait. A run that waits 7 days ends. Its reason says it waited too long to be allowed to start.
You can set the limit from 1 to 10:
The same limit appears as Max concurrent runs in the devices list of your workspace settings.

​
A cloud run works in a Pinework sandbox

Cloud runs work only when cloud is turned on for your workspace. Otherwise the run ends with “cloud runs are not enabled for this workspace”. Later cloud runs by the same agent on the same task reuse its sandbox, if the sandbox size stays the same. A conversation reuses its sandbox the same way. A new sandbox starts with no files of yours. If the run has a repo, the sandbox clones its branch from GitHub. The sandbox pushes each commit to GitHub as soon as the agent makes it.
  • Size. Sandboxes come in small, medium and large. Small is the default. The agent’s Sandbox size sets it, and a task can override it.
  • Time. A cloud run stops at a wall-clock ceiling just under 24 hours. A Codex or Cursor run stops after 5 hours.
  • MCP servers. A cloud run can reach remote MCP servers. It drops any MCP server that starts a local command, except Playwright.
  • Busy cloud. When the cloud has no free sandbox, Pinework retries the start with growing delays.
All four harnesses run in both places. The cloud limits which key or subscription each harness can use.
  • Claude Code uses an Anthropic API key or a Claude subscription.
  • Codex needs a ChatGPT subscription. It cannot use an API key in the cloud.
  • Cursor uses a saved Cursor API key.
  • OpenCode uses an Anthropic or OpenAI API key.
When a key or subscription is missing, the run shows a message that names the fix. The fix is to add a key or run the agent on a device.

​
Pick the place by what the work needs

Pick a device when the agent needs your local files, local tools or a signed-in harness. Pick the cloud when the work should run while your machine is off.

Run on your Mac

Connect your Mac and give an agent a folder.

Runs

What a run is and how it ends.